يوضِّح هذا الدليل طريقتَي الطلب والاستجابة الأساسية التي تتألف منها واجهة برمجة التطبيقات Google Docs API وكيفية تعديل أي مستند على دفعات.
يمكنك استدعاء Google Docs API باستخدام طلب HTTP أو باستخدام طريقة استدعاء في مكتبة عملاء خاصة بلغة. وهذان العنصران متكافئان على نطاق واسع.
تعرض واجهة برمجة التطبيقات لمستندات Google استجابة HTTP، تتضمن بشكل عام نتيجة استدعاء الطلب. عند استخدام مكتبة برامج لتقديم الطلبات، يتم عرض الردود بطريقة خاصة باللغة.
طرق الطلب
تتيح واجهة برمجة التطبيقات لتطبيق "مستندات Google" استخدام الطرق التالية:
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 المرجعية لأنواع الطلبات والاستجابة.
عمليات التحديث المجمع
هناك أنواع مختلفة من طلبات التحديث المجمّع. يمكنك الاطّلاع في ما يلي على تقسيم أنواع الطلبات، وقد تم تجميعها في فئات مختلفة.