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