يقدم هذا الدليل الطرق الأساسية للطلب والاستجابة التي تتألف منها واجهة برمجة التطبيقات لمستندات Google وكيفية تحديث مستند على دفعات.
يمكنك استدعاء واجهة برمجة تطبيقات "مستندات Google" باستخدام طلب HTTP أو من خلال استخدام طريقة استدعاء في مكتبة برامج خاصة بلغة معيّنة. هما متكافئان على نطاق واسع.
تعرض واجهة برمجة التطبيقات Google Docs API استجابة HTTP، التي تتضمن عادةً نتيجة استدعاء الطلب. عند استخدام مكتبة عملاء لتقديم الطلبات، يتم إرجاع الردود بطريقة خاصة باللغة.
طُرق الطلب
تتيح واجهة برمجة تطبيقات المستندات استخدام الطرق التالية:
documents.create: أنشئ مستندًا فارغًا في "مستندات Google".documents.get: تعرض نسخة كاملة من المستند المحدّد. يمكنك تحليل ملف JSON المعروض لاستخراج محتوى المستند وتنسيقه وميزات أخرى.documents.batchUpdate: أرسِل قائمة بطلبات التعديل لتطبيقها بشكل شامل على المستند، واعرض قائمة بالنتائج.
تتطلب الطريقتان documents.get وdocuments.batchUpdate documentId
كمَعلمة لتحديد المستند المستهدف. تعرض الطريقة documents.create مثيلاً من المستند الذي تم إنشاؤه، ويمكنك من خلاله قراءة documentId. لمزيد من المعلومات عن "documentId"، يُرجى الاطّلاع على رقم تعريف المستند.
التحديثات المجمّعة
تأخذ الطريقة documents.batchUpdate
قائمة بكائنات request، ويحدد كل منها طلبًا واحدًا لتنفيذه. على سبيل المثال، يمكنك تنسيق فقرة ثم
إضافة صورة مضمّنة. يتم التحقق من صحة كل طلب قبل تطبيقه وتتم معالجة الطلبات وفقًا للترتيب الذي تظهر به في الطلب المجمّع.
يتم تطبيق جميع الطلبات في التحديث المجمّع بشكل جزئي. أي، إذا كان أي طلب غير صالح، فلن ينجح التحديث بالكامل ولن يتم تطبيق أي من التغييرات (المحتملة التبعية).
توفِّر بعض طرق documents.batchUpdate ردودًا تتضمّن معلومات حول الطلبات المطبَّقة. تعرض هاتان الطريقتان Response
body الذي
يحتوي على قائمة بكائنات response. ولا تحتاج الطلبات الأخرى إلى عرض المعلومات وعرض رد فارغ. تشغل الكائنات في قائمة الاستجابة نفس ترتيب الفهرس مثل الطلب المقابل.
يبدو أحد الأنماط الشائعة لإنشاء الطلبات المجمّعة كما يلي:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
يمكنك الاطّلاع على أفضل ممارسات الطلبات المجمّعة للحصول على تفاصيل كاملة حول كيفية تجميع طلبات البيانات من واجهة برمجة التطبيقات لمستندات Google، بالإضافة إلى المستندات المرجعية documents.batchUpdate حول أنواع الطلبات والاستجابة.
عمليات التحديث المجمّع
هناك أنواع مختلفة من طلبات التعديل المجمّع. في ما يلي تفاصيل لأنواع الطلبات مجمّعة في فئات مختلفة.