نظرة عامة على دليل مطوّر البرامج
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تحذير: تتعلق هذه الصفحة بواجهات برمجة التطبيقات القديمة من Google، وهي واجهات برمجة التطبيقات لبيانات Google؛ وهي مرتبطة فقط بواجهات برمجة التطبيقات المدرجة في دليل Google Data APIs، والتي تم استبدال العديد منها بواجهات برمجة تطبيقات أحدث. للحصول على معلومات حول واجهة برمجة تطبيقات جديدة، اطلع على وثائق واجهة برمجة التطبيقات الجديدة. للحصول على معلومات حول تفويض الطلبات باستخدام واجهة برمجة تطبيقات أحدث، اطلع على مصادقة حسابات Google وتفويضها.
تتمثل مهمة Google في تنظيم المعلومات وتيسير سبل الوصول إليها والإفادة منها للعالم أجمع. ويشمل ذلك إتاحة الوصول إلى المعلومات في سياقات أخرى غير متصفح الويب، وكذلك الوصول إلى الخدمات خارج نطاق Google.
يوفر بروتوكول بيانات Google وسيلة آمنة لمطوري البرامج الخارجيين لكتابة تطبيقات جديدة تتيح للمستخدمين الدخول إلى البيانات المخزنة بواسطة العديد من منتجات Google وتحديثها. ويمكن لمطوّري البرامج الخارجيين استخدام بروتوكول بيانات Google مباشرةً أو استخدام أي من لغات البرمجة المتوافقة التي توفّرها مكتبات البرامج.
الجمهور
هذه المجموعة من المستندات مخصصة لأي شخص يريد فهم بروتوكول بيانات Google. حتى إذا كنت ترغب فقط في كتابة شفرة تستخدم مكتبات العميل الخاصة بلغة معينة، يمكن أن تكون مجموعة المستندات هذه مفيدة إذا كنت ترغب في استيعاب ما يجري أسفل طبقة التجريد في مكتبة العميل.
إذا كنت تبحث عن دليل مطور البرامج لواجهة برمجة تطبيقات معينة، فانتقل إلى دليل واجهة برمجة التطبيقات لبروتوكول Google Data.
إذا كنت تريد الوصول إلى واجهة برمجة التطبيقات بلغة البرمجة المفضلة، فانتقل إلى صفحة تنزيل مكتبات العميل.
الخلفية
يوفر عدد من منتجات Google، مثل التقويم وجداول البيانات، واجهات برمجة تطبيقات تستند إلى بروتوكول بيانات Google. ويمكنك بصفتك مطوّر البرامج استخدام واجهات برمجة التطبيقات هذه لكتابة تطبيقات عميل تمنح المستخدمين طرقًا جديدة للوصول إلى البيانات التي يخزّنونها في منتجات Google تلك ومعالجتها.
ملاحظة: يُشار أحيانًا إلى منتجات Google التي توفر واجهات برمجة التطبيقات باسم الخدمات في هذه المستندات والمستندات الأخرى ذات الصلة.
إذا كتبت رمزًا يستخدم بروتوكول بيانات Google مباشرةً، سيدخل إلى واجهة برمجة التطبيقات باستخدام طلبات HTTP مثل GET أو POST. وباستخدام هذه الطلبات، يتم نقل البيانات المخزَّنة بواسطة منتج Google مرارًا وتكرارًا عبر السلك في شكل خلاصات بيانات. خلاصات البيانات هي ببساطة قوائم منظَّمة تحتوي على البيانات. في السابق، كان تنسيق الخلاصة الأساسيّ هو AtomPub XML، ولكنه أصبح الآن بتنسيق JSON أو JavaScript Object Notation كتنسيق بديل.
إذا كنت تفضّل عدم كتابة شفرة تُرسل طلبات HTTP مباشرةً، يمكنك بدلاً من ذلك برمجة تطبيق العميل باستخدام إحدى لغات البرمجة المتاحة في مجموعة مكتبات العملاء المتوفرة. وعند إجراء ذلك، تعالج مكتبة العميل تفاصيل طلبات HTTP؛ حيث تكتب الشفرة على مستوى أكثر تصورًا باستخدام الطرق والفئات المتعلقة باللغة التي توفرها مكتبة العميل.
ارجع إلى الوثائق المتعلقة بالمنتج لمزيد من المعلومات عن اللغات المعينة المتوفرة لواجهة برمجة التطبيقات أو إصدار واجهة برمجة التطبيقات الذي تستخدمه.
إصدارات البروتوكول
بروتوكول الإصدار 2.0 في مقابل بروتوكول الإصدار 1.0
تم تطوير الإصدار الأول من بروتوكول Google Data قبل إنهاء بروتوكول النشر Atom. الإصدار الثاني من بروتوكول Google Data متوافق تمامًا مع معيار AtomPub RFC 5023.
يتضمن الإصدار 2.0 من بروتوكول بيانات Google أيضًا دعمًا لما يلي:
- HTTP ETags. معيار ويب يساعد تطبيقات العميل على الاستفادة بشكل أفضل من التخزين المؤقت عبر HTTP. تعمل الخدمات المضمّنة في مكتبات البرامج التي تتوافق مع Protocol v2.0 على معالجة العلامات الإلكترونية تلقائيًا.
- الاستجابة الجزئية والتحديث الجزئي (تجريبي). ميزات تتيح لك إجراء طلبات نقل بيانات أقل. ومن خلال طلب المعلومات التي تحتاج إليها فقط أو إرسال التحديثات التي تتضمن فقط البيانات التي تريد تغييرها فعليًا، يمكن أن يكون تطبيق العميل أكثر فعالية في استخدامه للشبكة ووحدة المعالجة المركزية وموارد الذاكرة. تتوفر الاستجابة الجزئية والتحديث الجزئي حاليًا لبعض المنتجات فقط. راجع الوثائق المتعلقة بالمنتج لمعرفة ما إذا كانت واجهة برمجة التطبيقات تتيح ذلك أم لا.
جارٍ تحديث طلبك
إذا كانت واجهة برمجة التطبيقات التي تستخدمها مستندة إلى أحدث إصدار من البروتوكول، سيتم تضمين وظيفة بروتوكول الإصدار 2.0 في وثائقه. وبوجه عام، ننصحك بترقية تطبيق العميل إلى أحدث إصدار متاح لواجهة برمجة التطبيقات.
تحديث عميل مستند إلى مكتبة العميل
إذا كان تطبيق العميل يستخدم مكتبة برامج، مثل مكتبة برامج جافا أو مكتبة عميل NET.، فقد يحتوي على إصدار من واجهة برمجة التطبيقات التي تدعم ميزات الإصدار 2.0 من البروتوكول. لمعرفة ذلك، ارجع إلى وثائق واجهة برمجة التطبيقات لمنتج Google الذي تستخدمه لمعرفة ما إذا كان أي مما يلي صحيحًا:
- هناك إصدار لواجهة برمجة التطبيقات يتوافق مع ميزات الإصدار 2.0 من بروتوكول Google Data.
- تدعم مكتبة العميل التي تستخدمها إصدار واجهة برمجة التطبيقات هذا أيضًا.
إذا كانت مكتبة العملاء تدعمها وكنت تريد تحديث تطبيقك الحالي، فعليك بتنزيل أحدث إصدار من مكتبة العملاء واستخدامه. ستظل جميع شفراتك تعمل، وستتولى مكتبة العميل تغيير بروتوكول v2.0.
تحديث برنامج HTTP أولي
إذا كتبت تطبيق العميل مباشرة باستخدام بروتوكول بيانات Google، فيجب إجراء هذه التغييرات:
- طلبات النسخة غير الافتراضية. يمكنك إضافة عنوان إصدار HTTP (
GData-Version: X.0) إلى كل طلب HTTP ترسله، حيث يكون X هو إصدار واجهة برمجة التطبيقات الذي يتوافق مع ميزات الإصدار 2.0 من بروتوكول Google Data. ويمكنك بدلاً من ذلك إضافة معلّمة طلب بحث (v=X.0) إلى عنوان URL لكل طلب، حيث يكون X هو النسخة الصحيحة من واجهة برمجة التطبيقات مرة أخرى. وفي حال عدم تحديد إصدار أحدث، سيتم إرسال طلباتك تلقائيًا إلى أقدم إصدار متوافق من واجهة برمجة التطبيقات.
- التزامن المتفائل. إذا كنت تستخدم إصدارًا من واجهة برمجة تطبيقات يتوافق مع التفاؤل الإيجابي، قد تحتاج إلى تغيير التحديث وحذف الرمز لاستخدام أداة ETags. للحصول على مزيد من المعلومات، اطلع على قسم ETags لمستندات بروتوكول Google Data Protocol، واقرأ أقسام "التحديث والحذف" من دليل مطور البروتوكول للخدمة التي يستخدمها تطبيق العميل.
- معرّفات الموارد المنتظمة (URI) الذاتية أو تعديلها. إذا كان البرنامج يتتبع بنفسك أو يُعدِّل معرّفات الموارد المنتظمة (URI) للخلاصات أو الإدخالات، لاحظ أنه ربما تم تغيير معرّفات الموارد المنتظمة (URI) هذه. للحصول على معرّف الموارد المنتظم الجديد، أعِد طلب العنصر باستخدام معرّف الموارد المنتظم القديم، ولكن ضَع علامة على الطلب كطلب الإصدار X.0، حيث تمثل القيمة X إصدار واجهة برمجة التطبيقات الذي يتوافق مع ميزات الإصدار 2.0 من بروتوكول Google Data. يعرض الخادم التمثيل الجديد للإدخال، بما في ذلك معرفات الموارد المنتظمة (URI) الجديدة التي يمكنك تخزينها بدلاً من معرفات الموارد القديمة.
- معرفات الموارد المنتظمة (URI) لمساحة الاسم. إذا كان العميل يخزّن معرّفات الموارد المنتظمة (URI) لمساحة اسم بروتوكول Google Data Protocol محليًا أو إذا كانت لديه معرّفات غير ثابتة، عليك تعديلها:
- تم تغيير مساحة الاسم 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 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة 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/`."]]
