مروری بر راهنمای توسعه‌دهنده
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
اخطار : این صفحه درباره APIهای قدیمی Google، Google Data APIها است. فقط مربوط به APIهایی است که در فهرست راهنمای Google Data APIs فهرست شده اند، که بسیاری از آنها با APIهای جدیدتر جایگزین شده اند. برای اطلاعات در مورد یک API جدید خاص، به مستندات API جدید مراجعه کنید. برای اطلاعات در مورد تأیید درخواست‌ها با یک API جدیدتر، به تأیید اعتبار و مجوز حساب‌های Google مراجعه کنید.
ماموریت گوگل این است که اطلاعات جهان را سازماندهی کند و آنها را در دسترس و مفید قرار دهد. این شامل دسترسی به اطلاعات در زمینه‌هایی غیر از مرورگر وب و دسترسی به سرویس‌های خارج از Google است.
Google Data Protocol ابزاری امن برای توسعه دهندگان خارجی برای نوشتن برنامه های کاربردی جدید فراهم می کند که به کاربران نهایی امکان دسترسی و به روز رسانی داده های ذخیره شده توسط بسیاری از محصولات Google را می دهد. توسعه دهندگان خارجی می توانند مستقیماً از پروتکل داده های Google استفاده کنند، یا می توانند از هر یک از زبان های برنامه نویسی پشتیبانی شده ارائه شده توسط کتابخانه های سرویس گیرنده استفاده کنند.
حضار
این مجموعه اسناد برای هر کسی که می‌خواهد پروتکل داده‌های Google را درک کند در نظر گرفته شده است. حتی اگر فقط می‌خواهید کدی بنویسید که از کتابخانه‌های مشتری خاص زبان استفاده می‌کند، این مجموعه اسناد می‌تواند مفید باشد اگر می‌خواهید بفهمید در زیر لایه انتزاعی کلاینت-کتابخانه چه می‌گذرد.
اگر به دنبال راهنمای برنامه‌نویس برای یک API خاص هستید، از فهرست API پروتکل داده Google دیدن کنید.
اگر می خواهید به یک API در زبان برنامه نویسی مورد علاقه خود دسترسی داشته باشید، از صفحه دانلود Client Libraries دیدن کنید.
زمینه
تعدادی از محصولات Google، مانند تقویم و صفحات گسترده، API هایی را ارائه می دهند که بر اساس پروتکل داده های Google هستند. شما، توسعه‌دهنده، می‌توانید از این APIها برای نوشتن برنامه‌های مشتری استفاده کنید که به کاربران نهایی راه‌های جدیدی برای دسترسی و دستکاری داده‌هایی که در آن محصولات Google ذخیره می‌کنند، می‌دهد.
توجه: محصولات Google که API ارائه می کنند، گاهی اوقات در این اسناد و سایر اسناد مرتبط به عنوان خدمات نامیده می شوند.
اگر کدی بنویسید که مستقیماً از پروتکل داده Google استفاده می کند، با استفاده از درخواست های HTTP مانند GET یا POST به API دسترسی پیدا می کند. با این درخواست‌ها، داده‌های ذخیره‌شده توسط محصول Google به صورت فید داده از طریق سیم به عقب و جلو منتقل می‌شوند. فیدهای داده به سادگی لیست های ساختاری هستند که حاوی داده ها هستند. از لحاظ تاریخی، فرمت اصلی فید AtomPub XML بوده است، اما اکنون JSON یا JavaScript Object Notation نیز به عنوان یک فرمت جایگزین در دسترس است.
اگر ترجیح می‌دهید کدی را که مستقیماً درخواست‌های HTTP را ارسال می‌کند، ننویسید، می‌توانید در عوض برنامه مشتری خود را با استفاده از یکی از زبان‌های برنامه‌نویسی موجود در مجموعه کتابخانه‌های سرویس گیرنده برنامه‌نویسی کنید. هنگامی که این کار را انجام می دهید، جزئیات درخواست های HTTP توسط کتابخانه مشتری مدیریت می شود. شما کد خود را در سطح مفهومی تری با استفاده از روش ها و کلاس های خاص زبان ارائه شده توسط کتابخانه مشتری می نویسید.
برای اطلاعات بیشتر درباره زبان‌های خاص موجود برای API یا نسخه API که استفاده می‌کنید، به مستندات محصول خاص مراجعه کنید.
نسخه های پروتکل
نسخه پروتکل 2.0 در مقابل پروتکل نسخه 1.0
اولین نسخه از پروتکل داده گوگل قبل از نهایی شدن پروتکل انتشار اتم توسعه یافت. نسخه دوم پروتکل داده گوگل کاملاً با استاندارد AtomPub RFC 5023 مطابقت دارد.
Google Data Protocol نسخه 2.0 همچنین شامل پشتیبانی از موارد زیر است:
- HTTP ETags یک استاندارد وب که به برنامه های مشتری شما کمک می کند تا از حافظه پنهان HTTP بهتر استفاده کنند. سرویس‌های موجود در کتابخانه‌های سرویس گیرنده که از Protocol v2.0 پشتیبانی می‌کنند، ETagها را به‌طور خودکار مدیریت می‌کنند.
- پاسخ بخشی و به روز رسانی جزئی (تجربی) . ویژگی هایی که به شما امکان می دهد درخواست هایی ارسال کنید که داده های کمتری را منتقل می کند. با درخواست تنها اطلاعاتی که واقعاً نیاز دارید، یا با ارسال به‌روزرسانی‌هایی که فقط شامل داده‌هایی می‌شوند که واقعاً می‌خواهید تغییر دهید، برنامه مشتری شما می‌تواند در استفاده از شبکه، CPU و منابع حافظه بسیار کارآمدتر باشد. در حال حاضر، پاسخ جزئی و به روز رسانی جزئی فقط برای برخی از محصولات موجود است. برای اطلاع از اینکه آیا API شما از آن پشتیبانی می کند یا خیر، به مستندات محصول خاص مراجعه کنید.
در حال به روز رسانی برنامه شما
اگر API مورد استفاده شما بر اساس آخرین نسخه پروتکل ساخته شده است، عملکرد Protocol v2.0 در مستندات آن گنجانده شده است. به طور کلی، توصیه می کنیم که برنامه مشتری خود را به آخرین نسخه موجود برای API خود ارتقا دهید.
به روز رسانی یک سرویس گیرنده مبتنی بر کتابخانه-کلینت
اگر برنامه سرویس گیرنده شما از کتابخانه سرویس گیرنده استفاده می کند، مانند کتابخانه سرویس گیرنده جاوا یا کتابخانه سرویس گیرنده دات نت، ممکن است حاوی نسخه ای از API باشد که از ویژگی های Protocol v2.0 پشتیبانی می کند. برای اطلاع از این موضوع، به اسناد API محصول Google که استفاده می‌کنید مراجعه کنید تا از صحت هر دو مورد زیر مطلع شوید:
- یک نسخه API وجود دارد که از ویژگی های Google Data Protocol v2.0 پشتیبانی می کند.
- کتابخانه سرویس گیرنده ای که استفاده می کنید نیز از آن نسخه API پشتیبانی می کند.
اگر کتابخانه مشتری از آن پشتیبانی می کند و می خواهید برنامه موجود خود را به روز کنید، کافی است آخرین نسخه کتابخانه مشتری را دانلود کرده و استفاده کنید. همه کدهای شما هنوز کار می کنند و کتابخانه مشتری از تغییرات پروتکل نسخه 2.0 در زیر هود مراقبت می کند.
به روز رسانی یک سرویس گیرنده HTTP خام
اگر برنامه مشتری خود را مستقیماً با استفاده از پروتکل داده Google نوشته اید، باید این تغییرات را انجام دهید:
- درخواست های نسخه غیر پیش فرض یک سرصفحه نسخه HTTP (
GData-Version: X .0 ) را به هر درخواست HTTP که ارسال می کنید اضافه کنید، جایی که X نسخه API است که از ویژگی های Google Data Protocol نسخه 2.0 پشتیبانی می کند. از طرف دیگر، یک پارامتر پرس و جو ( v= X .0 ) را به URL هر درخواست اضافه کنید، جایی که X دوباره نسخه صحیح API است. اگر نسخه بعدی را مشخص نکنید، درخواست های شما به طور پیش فرض به اولین نسخه پشتیبانی شده از API ارسال می شود. - همزمانی خوش بینانه اگر از نسخه‌ای از یک API استفاده می‌کردید که از همزمانی خوش‌بینانه پشتیبانی می‌کرد، ممکن است لازم باشد به‌روزرسانی خود را تغییر دهید و کد را برای استفاده از ETags حذف کنید. برای اطلاعات بیشتر، بخش ETags اسناد مرجع پروتکل داده Google را بخوانید و بخش‌های به‌روزرسانی و حذف راهنمای توسعه‌دهنده پروتکل را برای سرویسی که برنامه مشتری شما استفاده می‌کند، بخوانید.
- URI ها را خودتان یا ویرایش کنید. اگر مشتری شما URI های خود را برای فیدها یا ورودی ها ردیابی می کند یا URI را ویرایش می کند، توجه داشته باشید که این URI ها ممکن است تغییر کرده باشند. برای دریافت URI جدید، مورد را با استفاده از URI قدیمی دوباره درخواست کنید، اما درخواست را به عنوان درخواست نسخه X .0 علامت گذاری کنید، جایی که X نسخه API است که از ویژگی های Google Data Protocol v2.0 پشتیبانی می کند. سرور نمایش جدید ورودی شامل URI های جدید را برمی گرداند که می توانید آنها را به جای URI های قدیمی ذخیره کنید.
- URI های فضای نام اگر مشتری شما URI های فضای نام API پروتکل داده Google را به صورت محلی ذخیره می کند، یا آنها را به صورت سخت کدگذاری کرده است، باید آنها را به روز کنید:
- فضای نام AtomPub (
app پیشوند) از http://purl.org/atom/app به http://www.w3.org/2007/app تغییر کرده است. - فضای نام OpenSearch (پیشوند
openSearch ) از http://a9.com/-/spec/opensearchrss/1.0/ به http://a9.com/-/spec/opensearch/1.1/ تغییر یافته است.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین به‌روزرسانی 2023-03-01 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین به‌روزرسانی 2023-03-01 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eThe Google Data Protocol enables external developers to build applications that access and update data stored in various Google products.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers can use the protocol directly via HTTP requests or leverage client libraries for supported programming languages.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Data Protocol v2.0, aligned with AtomPub RFC 5023, introduces features like HTTP ETags, Partial Response, and Partial Update for enhanced efficiency.\u003c/p\u003e\n"],["\u003cp\u003eUpgrading to Protocol v2.0 may require updating client applications to handle changes related to version requests, optimistic concurrency, URIs, and namespaces.\u003c/p\u003e\n"],["\u003cp\u003eRefer to specific product documentation and the Google Data APIs directory for API details and compatibility.\u003c/p\u003e\n"]]],[],null,["# Developer's Guide Overview\n\n**Warning** : This page is about Google's older APIs, the Google Data APIs; it's relevant only to the APIs that are listed in the [Google Data APIs directory](/gdata/docs/directory), many of which have been replaced with newer APIs. For information about a specific new API, see the new API's documentation. For information about authorizing requests with a newer API, see [Google Accounts Authentication and Authorization](/accounts).\n\nGoogle's mission is to organize the world's information and make it universally accessible and useful. This includes making information accessible in contexts other than a web browser and accessible to services outside of Google.\n\nThe Google Data Protocol provides a secure means for external developers to write new applications that let end users access and update the data stored by many Google products. External developers can use the Google Data Protocol directly, or they can use any of the supported programming languages provided by the client libraries. \n\nAudience\n========\n\nThis set of documents is intended for anyone who wants to understand Google Data Protocol. Even if you just want to write code that uses the language-specific [client libraries](/gdata/docs/client-libraries), this document set can be helpful if you want to understand what's going on beneath the client-library abstraction layer.\n\nIf you're looking for the Developer's Guide for a specific API, visit the Google Data Protocol [API Directory](/gdata/docs/directory).\n\nIf you want to access an API in your favorite programming language, visit the [Client Libraries](/gdata/docs/client-libraries) download page.\n\nBackground\n==========\n\nA number of Google products, such as Calendar and Spreadsheets, provide APIs that are based on the Google Data Protocol. You, the developer, can use these APIs to write client applications that give end users new ways to access and manipulate the data they store in those Google products.\n\n**Note:** Google products that provide APIs are sometimes referred to as *services* in these and other related documents.\n\nIf you write code that uses the Google Data Protocol directly, it accesses the API using HTTP requests like `GET` or `POST`. With these requests, data stored by the Google product is transferred back and forth over the wire in the form of data feeds. The data feeds are simply structured lists that contain the data. Historically, the primary feed format has been AtomPub XML, but now JSON, or JavaScript Object Notation, is also available as an [alternate format](/gdata/docs/json).\n\nIf you prefer not to write code that makes HTTP requests directly, you can instead program your client application using one of the programming languages available in the set of client libraries provided. When you do this, the details of the HTTP requests are handled by the client library; you write your code at a more conceptual level using the language-specific methods and classes provided by the client library.\n\nRefer to the product-specific documentation for more information about the particular languages available for the API, or API version, you are using.\n\nVersions of the protocol\n========================\n\n### Protocol Version 2.0 vs. Protocol Version 1.0\n\nThe first version of the Google Data Protocol was developed before the Atom Publishing Protocol was finalized. The second version of the Google Data Protocol is fully compliant with the AtomPub [RFC 5023](http://www.rfc-editor.org/rfc/rfc5023.txt) standard.\n\nThe Google Data Protocol Version 2.0 also includes support for:\n\n- [HTTP ETags](/gdata/docs/2.0/reference#ResourceVersioning). A web standard that helps your client applications make better use of HTTP caching. The services included in the client libraries that support Protocol v2.0 handle ETags automatically.\n- [Partial Response](/gdata/docs/2.0/reference#PartialResponse) and [Partial Update](/gdata/docs/2.0/reference#PartialUpdate) (Experimental). Features that let you make requests that transfer less data. By requesting only the information that you actually need, or by sending updates that include only the data that you actually want to change, your client application can be much more efficient in its use of network, CPU, and memory resources. Currently, partial response and partial update are available only for some products; see the product-specific documentation to find out if your API supports it.\n\n### Updating your application\n\nIf the API you are using was built upon the latest version of the protocol, then the Protocol v2.0 functionality is included in its documentation. In general, we recommend that you upgrade your client application to the latest version available for your API.\n\n#### Updating a client-library-based client\n\nIf your client application uses a client library, such as the Java client library or the .NET client library, it may contain a version of the API that supports Protocol v2.0 features. To find out, refer to the API documentation for the Google product you are using to find out if both of the following are true:\n\n- There is an API version that supports Google Data Protocol v2.0 features.\n- The client library you are using also supports that API version.\n\nIf the client library supports it and you want to update your existing application, just download and use the latest version of the client library. All of your code still works, and the client library takes care of the Protocol v2.0 changes under the hood.\n\n#### Updating a raw HTTP client\n\nIf you wrote your client application using the Google Data Protocol directly, you need to make these changes:\n\n- **Non-default version requests.** Add an HTTP version header (`GData-Version: `*X*`.0`) to every HTTP request you send, where *`X`* is the version of the API that supports Google Data Protocol v2.0 features. Alternatively, add a query parameter (`v=`*X*`.0`) to the URL of every request, where *`X`* is, again, the correct version of the API. If you do not specify a later version, your requests are sent to the earliest supported version of the API by default.\n- **Optimistic concurrency.** If you were using a version of an API that supported optimistic concurrency, you may need to change your update and delete code to use ETags. For more information, read the [ETags section](/gdata/docs/2.0/reference#ResourceVersioning) of the Google Data Protocol reference documentation, and read the Update and Delete sections of the Protocol developer's guide for the service your client application is using.\n- **Self or edit URIs.** If your client keeps track of self or edit URIs for feeds or entries, note that those URIs may have changed. To get the new URI, re-request the item using the old URI, but mark the request as a version *X* .0 request, where *X* is the version of the API that supports Google Data Protocol v2.0 features. The server returns the new representation of the entry, including the new URIs, which you can store in place of the old ones.\n- **Namespace URIs.** If your client stores Google Data Protocol API namespace URIs locally, or has them hard-coded, you'll need to update them:\n - The AtomPub namespace (prefix `app`) has been changed from `http://purl.org/atom/app` to `http://www.w3.org/2007/app`.\n - The OpenSearch namespace (prefix `openSearch`) has been changed from `http://a9.com/-/spec/opensearchrss/1.0/` to `http://a9.com/-/spec/opensearch/1.1/`."]]
