أساسيات بروتوكول Google APIs APIs

يصف هذا المستند أساسيات البروتوكول المستخدَم في Google Data APIs، بما في ذلك أمثلة على شكل طلب البحث وطريقة عرضه وما إلى ذلك.

لمزيد من المعلومات حول واجهات برمجة التطبيقات لبيانات Google، اطلع على مستند دليل مطوري بيانات Google والدليل المرجعي.

الجمهور

تم إعداد هذا المستند لأي شخص يريد فهم الفكرة العامة حول تنسيق وبروتوكول XML المستخدمَين في Google Data APIs.

حتى إذا كنت ترغب فقط في كتابة شفرة تستخدم مكتبات العملاء الخاصة بلغة معينة، فقد تحتاج إلى قراءة هذا المستند لفهم ما يجري تحت طبقة الصورة التجريدية في مكتبة العميل.

يفترض هذا المستند أنك تفهم أساسيات XML ومساحات الأسماء والخلاصات المشتركة والطلبات GET وPOST وPUT وDELETE في HTTP، بالإضافة إلى مفهوم HTTP لـ "المورد". للحصول على مزيد من المعلومات حول هذه الأمور، يمكنك الاطلاع على قسم الموارد الإضافية في هذا المستند.

لا يعتمد هذا المستند على أي لغة برمجة محددة؛ حيث يمكن للبرنامج التفاعل مع الخادم باستخدام أي لغة برمجة تتيح لك إصدار طلبات HTTP وتحليل الردود المستندة إلى XML.

أمثلة

تعرض الأمثلة التالية طلبات بروتوكول البيانات غير المُرسَلة التي قد ترسلها إلى خدمة عامة، والنتائج التي قد تتلقاها. للحصول على أمثلة حول كيفية إرسال الطلبات باستخدام لغات برمجة مختلفة، راجع النماذج ومكتبات البرامج الخاصة بكل لغة. للحصول على معلومات حول استخدام واجهات برمجة التطبيقات لبيانات Google مع خدمات معينة من Google، اطلع على الوثائق الخاصة بالخدمة.

طلب خلاصة أو مورد آخر

لنفترض أن هناك خلاصة باسم /myFeed، وافترض أنها لا تحتوي حاليًا على أية إدخالات. لعرضه، أرسل الطلب التالي إلى الخادم:

GET /myFeed

يستجيب الخادم:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>

لاحظ أنه على الرغم من أن الخلاصة لا تشتمل على أية إدخالات، فإنها تحتوي على بيانات وصفية، مثل العنوان واسم المؤلف.

إدراج إدخال جديد

لإنشاء إدخال جديد، أرسل طلب POST وأدخل تمثيل XML للإدخال الجديد:

POST /myFeed

<?xml version="1.0"?>
<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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <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"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <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>
</feed>

تحديث إدخال

لتحديث إدخال حالي، استخدِم PUT مع معرّف الموارد المنتظم (URI) لتعديل الإدخال (على النحو الذي وفّره الخادم في المثال السابق، في العنصر <link rel="edit">).

إذا كان الجدار الناري لا يسمح بـ PUT، فعليك تنفيذ HTTP POST وتعيين رأس إلغاء الطريقة على النحو التالي:

X-HTTP-Method-Override: PUT

في المثال التالي، نحن بصدد تغيير نص الإدخال من قيمته القديمة ("هذا هو إدخالي") إلى قيمة جديدة ("هذا أول إدخال لي"):

PUT /myFeed/1/1/

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/2/"/>
  <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>

لاحظ أن معرّف الموارد المنتظم (URI) للتعديل قد تغير، وينتهي الآن بـ "/2/" بدلاً من "/1/". الرقم النهائي في معرف الموارد المنتظم (URI) للتعديل هو رقم إصدار. لمزيد من المعلومات عن الإصدارات، يُرجى الاطِّلاع على قسم التزامن المتفائل في المستند المرجعي للبروتوكول.

لمشاهدة الإدخال الجديد في السياق، اطلب المورد بالكامل مرة أخرى:

GET /myFeed

يستجيب الخادم:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/2/"/>
    <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>

حذف إدخال

لحذف إدخال حالي، أرسل طلب DELETE، باستخدام معرف الموارد المنتظم (URI) لتعديل الإدخال (كما تم تقديمه بواسطة الخادم في المثال السابق).

إذا كان الجدار الناري لا يسمح بـ DELETE، فعليك تنفيذ HTTP POST وتعيين رأس إلغاء الطريقة على النحو التالي:

 X-HTTP-Method-Override: DELETE

يؤدي المثال التالي إلى حذف إدخال:

DELETE /myFeed/1/2/

يستجيب الخادم:

200 OK

يمكنك إجراء GET أخرى للتأكد من عدم احتواء الخلاصة الآن على أي إدخالات:

GET /myFeed

يستجيب الخادم:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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 في المستند المرجعي للبروتوكول.

مراجع إضافية

قد تجد مستندات الجهات الخارجية التالية مفيدة:

الرجوع إلى الأعلى