تحذير: تتعلق هذه الصفحة بواجهات برمجة التطبيقات القديمة من Google، وهي واجهات برمجة التطبيقات لبيانات Google؛ وهي مرتبطة فقط بواجهات برمجة التطبيقات المدرجة في دليل Google Data APIs، والتي تم استبدال العديد منها بواجهات برمجة تطبيقات أحدث. للحصول على معلومات حول واجهة برمجة تطبيقات جديدة، اطلع على وثائق واجهة برمجة التطبيقات الجديدة. للحصول على معلومات حول تفويض الطلبات باستخدام واجهة برمجة تطبيقات أحدث، اطلع على مصادقة حسابات Google وتفويضها.
يصف هذا المستند أساسيات بروتوكول بيانات Google الذي تستخدمه العديد من واجهات برمجة تطبيقات Google، بما في ذلك أمثلة على شكل طلب البحث والشكل الذي تظهر به النتائج وما إلى ذلك.
لمزيد من المعلومات حول بروتوكول بيانات Google، اطلع على صفحة نظرة عامة على دليل مطور البرامج ومرجع البروتوكول.
الجمهور
تم إعداد هذا المستند لأي شخص يريد فهم الفكرة العامة حول تنسيق وبروتوكول XML المستخدمَين في Google Data APIs.
حتى إذا كنت ترغب فقط في كتابة شفرة تستخدم مكتبات العملاء الخاصة بلغة معينة، فقد تحتاج إلى قراءة هذا المستند لفهم ما يجري تحت طبقة الصورة التجريدية في مكتبة العميل.
يفترض هذا المستند أنك تفهم أساسيات XML ومساحات الأسماء والخلاصات المشتركة والطلبات GET وPOST وPUT وDELETE في HTTP، بالإضافة إلى مفهوم HTTP لـ "المورد". للحصول على مزيد من المعلومات حول هذه الأمور، يمكنك الاطلاع على قسم الموارد الإضافية في هذا المستند.
لا يعتمد هذا المستند على أي لغة برمجة محددة؛ حيث يمكن للبرنامج التفاعل مع الخادم باستخدام أي لغة برمجة تتيح لك إصدار طلبات HTTP وتحليل الردود المستندة إلى XML.
إذا كنت ترغب في تجربة الأمثلة في هذا المستند بدون كتابة أية شفرة، فقد تجد أدوات سطر الأوامر cURL أو Wget مفيدة؛ للحصول على مزيد من المعلومات، اطلع على الصفحات اليدوية لهذه الأدوات أو مستند عن استخدام cURL للتفاعل مع الخدمات التي تستخدم بروتوكول بيانات Google.
أمثلة
توضح الأمثلة التالية طلبات HTTP التي قد ترسلها إلى خدمة عامة باستخدام بروتوكول Google Data Protocol مباشرةً، والنتائج التي قد تتلقاها. للحصول على أمثلة حول كيفية إرسال الطلبات باستخدام لغات برمجة مختلفة، راجع النماذج ومكتبات البرامج الخاصة بكل لغة. للحصول على معلومات حول استخدام بروتوكول بيانات Google مع خدمات معينة من Google، اطلع على الوثائق الخاصة بالخدمة.
طلب خلاصة أو مورد آخر
لنفترض أن هناك خلاصة باسم /myFeed، وافترض أنها لا تحتوي حاليًا على أية إدخالات. لعرضه، أرسل طلب HTTP التالي إلى الخادم:
GET /myFeed
يستجيب الخادم:
200 OK
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
<title>Foo</title>
<updated>2006-01-23T16:25:00-08:00</updated>
<id>http://www.example.com/myFeed</id>
<author>
<name>Jo March</name>
</author>
<link href='/myFeed' rel='self'/>
</feed>
لاحظ أنه على الرغم من أن الخلاصة لا تشتمل على أية إدخالات، فإنها تحتوي على بيانات وصفية، مثل العنوان واسم المؤلف. ويتضمّن أيضًا معرّف الإصدار على شكل علامة HTTP ETag.
إدراج إدخال جديد
لإنشاء إدخال جديد، أرسل طلب POST وأدخل تمثيل XML للإدخال الجديد:
POST /myFeed
<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<title type='text'>Entry 1</title>
<content type='text'>This is my entry</content>
</entry>
لاحظ أنك لا توفر عناصر Atom القياسية <id> أو <link> أو <updated>، وسينشئ الخادم هذه العناصر استجابة لطلب POST. لاحظ أيضًا أنه لا يجب أن يكون مؤلف الخلاصة هو نفسه مؤلف المشاركة.
يستجيب الخادم:
201 CREATED
<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
<id>http://www.example.com/id/1</id>
<link rel='edit' href='http://example.com/myFeed/1/1/'/>
<updated>2006-01-23T16:26:03-08:00</updated>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<title type='text'>Entry 1</title>
<content type='text'>This is my entry</content>
</entry>
البحث عن سلسلة
لإجراء بحث بالنص الكامل لسلسلة معيّنة، عند استخدام خدمة تدعم عمليات البحث بالنص الكامل، أرسِل طلب GET مع المعلمة q. لمزيد من المعلومات عن معامِلات طلب البحث، راجع طلبات البحث في المستند المرجعي للبروتوكول.
GET /myFeed?q=This
يستجيب الخادم بخلاصة تحتوي على جميع الإدخالات التي تطابق سلسلة البحث This. (في هذه الحالة لا يوجد إلا 1).
200 OK
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"S0wCTlpIIip7ImA0X0QI"'>
<title>Foo</title>
<updated>2006-01-23T16:26:03-08:00</updated>
<id>http://www.example.com/myFeed</id>
<author>
<name>Jo March</name>
</author>
<link href='/myFeed' rel='self'/>
<entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
<id>http://www.example.com/id/1</id>
<link rel='edit' href='http://example.com/myFeed/1/'/>
<updated>2006-01-23T16:26:03-08:00</updated>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<title type='text'>Entry 1</title>
<content type='text'>This is my entry</content>
</entry>
</feed>
تحديث إدخال
لتحديث إدخال حالي، تحتاج إلى تنفيذ الخطوات التالية.
- استرد الإدخال الذي تريد تحديثه.
- عدّله كما تشاء.
- أرسِل طلب
PUT، مع إدخال محدّث في نص الرسالة، إلى معرّف الموارد المنتظم (URI) لتعديل الإدخال. يظهر معرف الموارد المنتظم (URI) للتعديل في المثال السابق كسمةhrefللعنصر<link rel='edit'>.
يجب عليك أيضًا تحديد ETag للإدخال الأصلي، لضمان عدم استبدال تغييرات أي شخص آخر.
في المثال التالي، نحن بصدد تغيير نص الإدخال من قيمته القديمة ("هذا هو إدخالي") إلى قيمة جديدة ("هذا أول إدخال لي"):
PUT /myFeed/1/1/
<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
<id>http://www.example.com/id/1</id>
<link rel='edit' href='http://example.com/myFeed/1/'/>
<updated>2006-01-23T16:28:05-08:00</updated>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<title type='text'>Entry 1</title>
<content type='text'>This is my first entry.</content>
</entry>
يستجيب الخادم:
200 OK
<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
<id>http://www.example.com/id/1</id>
<link rel='edit' href='http://example.com/myFeed/1/'/>
<updated>2006-01-23T16:28:05-08:00</updated>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<title type='text'>Entry 1</title>
<content type='text'>This is my first entry.</content>
</entry>
تجدر الإشارة إلى أن ETag قد تغيّر. لمزيد من المعلومات حول إصدارات الموارد، راجع قسم تحديد إصدارات الموارد (ETags) في المستند المرجعي للبروتوكول.
لمشاهدة الإدخال الجديد في السياق، اطلب المورد بالكامل مرة أخرى:
GET /myFeed
يستجيب الخادم:
200 OK
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"D08FQn8-eil7ImA9WxZbFEw."'>
<title>Foo</title>
<updated>2006-01-23T16:28:05-08:00</updated>
<id>http://www.example.com/myFeed</id>
<author>
<name>Jo March</name>
</author>
<link href='/myFeed' rel='self'/>
<entry gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
<id>http://www.example.com/id/1</id>
<link rel='edit' href='http://example.com/myFeed/1/'/>
<updated>2006-01-23T16:28:05-08:00</updated>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<title type='text'>Entry 1</title>
<content type='text'>This is my first entry.</content>
</entry>
</feed>
ملاحظة: إذا لم يسمح الجدار الناري بـ PUT، يمكنك تنفيذ HTTP POST وضبط رأس إلغاء الطريقة على النحو التالي:
X-HTTP-Method-Override: PUT
حذف إدخال
لحذف إدخال حالي، أرسل طلب DELETE، باستخدام معرف الموارد المنتظم (URI) لتعديل الإدخال (كما تم تقديمه بواسطة الخادم في المثال السابق).
إذا كان الجدار الناري لا يسمح بـ DELETE، فعليك تنفيذ HTTP POST وتعيين رأس إلغاء الطريقة على النحو التالي:
X-HTTP-Method-Override: DELETE
عند حذف إدخال، يمكنك اختيار ما إذا كنت تريد إجراء حذف مشروط (الحذف فقط إذا لم يتغير الإدخال منذ آخر مرة استردته فيها) أو حذف غير مشروط. لمزيد من المعلومات، راجع قسم تحديد إصدارات الموارد (ETags) لمستند مرجع البروتوكول. لإجراء حذف غير مشروط، اضبط رأس HTTP التالي:
If-Match: *
يحذف المثال التالي إدخالاً (في حالة تعيين الرؤوس بشكل مناسب):
DELETE /myFeed/1/
يستجيب الخادم:
200 OK
يمكنك إجراء GET أخرى للتأكد من عدم احتواء الخلاصة الآن على أي إدخالات:
GET /myFeed
يستجيب الخادم بخلاصة لا تحتوي على شيء سوى البيانات الوصفية:
200 OK
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
<title>Foo</title>
<updated>2006-01-23T16:30:11-08:00</updated>
<id>http://www.example.com/myFeed</id>
<author>
<name>Jo March</name>
</author>
<link href='/myFeed' rel='self'/>
</feed>
إذا أخفق الحذف، فسيستجيب الخادم برمز خطأ. لمزيد من المعلومات، راجع رموز حالة HTTP في المستند المرجعي للبروتوكول.
طلب خلاصات أو إدخالات جزئية (تجريبية)
وعلى عكس مثال الخلاصة البسيط الموضح في هذا المستند، يمكن أن تكون الخلاصات عملية معقدة إلى حد كبير. في بعض واجهات برمجة التطبيقات، يمكنك طلب العناصر أو السمات محل الاهتمام فقط، بدلاً من التمثيل الكامل للموارد. عند تجنب استرجاع البيانات غير الضرورية وتحليلها، يمكنك تحسين فعالية تطبيق العميل بشكل ملحوظ.
لطلب استجابة جزئية، يمكنك استخدام معلمة طلب البحث fields لتحديد العناصر أو السمات التي تريد عرضها. لمزيد من المعلومات، راجع الاستجابة الجزئية في المستند المرجعي للبروتوكول.
يطلب المثال التالي معرّف الخلاصة فقط، واسم المؤلف والعنوان لكل إدخال خلاصة،
GET /myFeed?fields=id,entry(author)
يستجيب الخادم:
200 OK
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'>
<id>http://www.example.com/myFeed</id>
<entry>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<title type='text'>Entry 1</title>
</entry>
<entry>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<title type='text'>Entry 2</title>
</entry>
</feed>
يمكنك استخدام المعلَمة fields مع أي نوع من الطلبات التي تعرض بيانات. بالإضافة إلى GET، يتضمن ذلك POST وPUT (بالإضافة إلى PATCH، الذي يستخدم لإجراء تحديث جزئي).
ملاحظة: تتحكم معلمة طلب البحث fields فقط في البيانات التي يتم إرسالها ردًا على طلب، ولا تؤثر في البيانات التي يجب تقديمها في النص الأساسي لطلب PUT أو POST أو PATCH.
في ما يلي أمثلة على POST وPUT.
- عند تقديم طلب
POSTلاستجابة جزئية، يجب عليك تقديم البيانات نفسها كما هو موضح في إدراج إدخال جديد. يطلب المثال التالي ردًا جزئيًا يحتوي فقط على عنوان الإدخال الجديد:POST /myFeed?fields=title ...data...يستجيب الخادم:
200 OK <?xml version='1.0' encoding='utf-8'?> <entry xmlns='http://www.w3.org/2005/Atom'> <title type='text'>Entry 1</title> </entry>
- عند تقديم طلب
PUTللحصول على رد جزئي، عليك تقديم نسخة معدَّلة من تمثيل المورد بالكامل، كما هو موضَّح في تعديل إدخال. يطلب المثال التالي ردًا جزئيًا يحتوي على قيمة ETag الجديدة للإدخال الذي تم تعديله فقط:PUT /myFeed/1/1?fields=@gd:etag ...data...
يستجيب الخادم:
200 OK <?xml version='1.0' encoding='utf-8'?> <entry xmlns='http://www.w3.org/2005/Atom' gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>
تحديث حقول معينة (تجريبي)
إذا كانت واجهة برمجة التطبيقات التي تستخدمها تدعم الاستجابة الجزئية وتحتوي على حقول قابلة للتعديل، يمكنك أيضًا تجنب إرسال بيانات غير ضرورية عند تعديل إدخال. يسمح لك التحديث الجزئي بإرسال البيانات فقط للحقول التي ترغب في تغييرها.
لاستخدام التحديث الجزئي، يجب إرسال طلب PATCH إلى معرّف الموارد المنتظم (URI) نفسه الذي تستخدمه مع PUT. يجب أن تتبع البيانات التي ترسلها باستخدام PATCH اصطلاحات معينة. ومع ذلك، فإن دلالات الألفاظ مرنة بما يكفي لاستبدال البيانات في المورد الهدف أو الإضافة إليه أو حتى إجراء عمليات الحذف منه، وكل ذلك بطلب واحد.
ملاحظة: كما هو الحال مع PUT، يجب تحديد ETag للإدخال الأصلي، لضمان عدم تجاوز تغييرات أي شخص آخر.
لمزيد من المعلومات حول PATCH ومعانيه، راجع تحديث جزئي في المستند المرجعي للبروتوكول.
يعرض هذا المثال طلب تحديث جزئيًا يعدّل عنوان الإدخال:
PATCH /myFeed/1/1/
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag="EksPTg1Bfyp7IWA6WhJT"
gd:fields='title'>
<title>New Title</title>
</entry>
عندما يتلقى الخادم طلب PATCH، يزيل أولاً أي حقول محدّدة من خلال سمة الإدخال gd:fields (إذا كانت موجودة)، ثم يدمج أي بيانات مقدّمة في نص الطلب مع المورد الهدف. في هذا المثال، تتم إزالة عنصر العنوان أولاً من المورد الهدف؛ ثم يتم دمج قيمة العنوان الجديدة. ويحل هذا الطلب بفعالية محل العنوان القديم بالعنوان الجديد.
تجدر الإشارة إلى أن دلالات PATCH هي دمج التمثيل الجزئي في المورد الحالي. ولا تحتاج دائمًا إلى إزالة أي حقل لتحديث قيمته.
- إذا كان الحقل موجودًا مرة واحدة فقط في الإدخال الهدف، فإنه عند الدمج، يؤدي الحقل في التمثيل الجزئي إلى استبدال الحقل المقابل في الإدخال الهدف.
- وإذا كان الحقل يمكن أن يوجد أكثر من مرة في الإدخال الهدف، فإنه عند الدمج، تتم إضافة الحقل الجزئي إلى الإدخال الهدف.
يعرض المثال التالي الفرق بين كيفية دمج الحقول المتكرّرة وتلك غير المتكرّرة، ما يؤدي إلى إضافة عنوان ومؤلف جديدَين إلى الإدخال بدون استخدام السمة gd:fields لإزالة أيٍّ منهما.
PATCH /myFeed/1/1/
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:edtag="EksPTg1Bfyp7IWA6WhJT">
<title>A new title</title>
<author>
<name>Fitzwilliam Darcy</name>
<email>darcy@gmail.com</email>
</author>
</entry>
ونظرًا لأن تمثيل الإدخال الجزئي لا يحتوي على سمة gd:fields، لا تتم إزالة أي حقول. ومع ذلك، يتم دمج القيم الجديدة للعناصر <title> و<author> مع المورد الهدف:
- ونظرًا لأن تنسيق Atom لا يسمح إلا بعنوان واحد فقط لكل إدخال، يستبدل العنوان الجديد القيمة الحالية.
- ونظرًا لأن Atom تسمح بعدة مؤلفين لكل إدخال، يتم إلحاق المؤلف الجديد بقائمة عناصر المؤلف الموجودة فعلاً في المورد الهدف.
ملاحظة: لا تتوافق جميع واجهات برمجة التطبيقات مع معيار Atom. على سبيل المثال، تسمح بعض واجهات برمجة التطبيقات بعنصر واحد فقط
<author>لكل إدخال، بينما ترث واجهات برمجة تطبيقات أخرى مؤلف الإدخالمن مستوى الخلاصة، مما يجعل الحقل للقراءة فقط.
بعد أن يعالج الخادم طلب PATCH صالحًا، يعرض رمز حالة HTTP 200 مع نسخة من التمثيل الكامل للإدخال المحدّث.
إذا كنت تفضِّل أن يعرض الخادم عناصر أو سمات معينة فقط، يمكنك استخدام معلَمة طلب البحث fields مع PATCH لطلب استجابة جزئية.
مراجع إضافية
قد تجد مستندات الجهات الخارجية التالية مفيدة:
- نظرة عامة على Atom من IBM
- تعريفات الطريقة HTTP 1.1؛ مواصفات
GETوPOSTوPUTوDELETE - تعريفات رمز الحالة لبروتوكول HTTP 1.1
- كيفية إنشاء بروتوكول REST
- تصميم خدمات الويب بطريقة REST
- مقدمة فنية عن XML
- مساحات أسماء XML حسب المثال