يقدّم هذا الدليل طرق الطلب والاستجابة الأساسية التي تشكّل واجهة برمجة التطبيقات 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
لأنواع الطلبات والردود.
عمليات التعديل المجمّع
هناك أنواع مختلفة من طلبات التعديل المجمّع. في ما يلي تفاصيل أنواع الطلبات، التي تم تجميعها في فئات مختلفة.