يقدّم هذا الدليل طرق الطلب والاستجابة الأساسية التي تشكّل واجهة برمجة التطبيقات 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.get لاسترداد الوثائق
المنشورة. بعد نشر المستندات العامة، يتم استخدام تنسيق مختلف لعنوان URL. تؤدي محاولات
استخدام documentId الجديد لعنوان URL مع الطريقة documents.get إلى عرض 404 رمز حالة HTTP للاستجابة. لا تتوفّر طرق لاسترداد
documentId الأصلي من عنوان URL المنشور. لحلّ هذه المشكلة، يمكنك استخدام واجهة برمجة التطبيقات
Drive API من أجل نسخ المستند الذي تم نشره إلى مستند
مشترَك، ثم الوصول إلى هذا الملف بدلاً من ذلك. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إتاحة "مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google" و"نماذج Google" للجميع.
التحديثات المجمّعة
تأخذ الطريقة
documents.batchUpdate
قائمة بعناصر
request، يحدّد كلّ منها طلبًا واحدًا لتنفيذه. على سبيل المثال، يمكنك تنسيق فقرة ثم
إضافة صورة مضمّنة. يتم التحقّق من كل طلب قبل تطبيقه، وتتم معالجة الطلبات وفقًا للترتيب الذي تظهر به في طلب الحزمة.
يتم تطبيق جميع الطلبات في التحديث المجمّع بشكل موحّد. وهذا يعني أنّه إذا لم يكن أي طلب صالحًا، لن يتم إكمال عملية التحديث بالكامل ولن يتم تطبيق أي من التغييرات (التي قد تكون مرتبطة).
توفّر بعض طرق documents.batchUpdate ردودًا تتضمّن معلومات عن
الطلبات التي تم تطبيقها. تُعرِض هذه الطرق جسم الردّ الذي يحتوي على قائمة بكائنات response. لا تحتاج الطلبات الأخرى إلى عرض معلومات وتعرض بدلاً من ذلك
ردًا فارغًا. تحتلّ العناصر في قائمة الردود ترتيب الفهرس نفسه الذي يحتله
الطلب المقابل.
يظهر نمط شائع لطلبات الحِزم على النحو التالي:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
اطّلِع على أفضل الممارسات المتعلّقة بطلبات البيانات المجمّعة للحصول على التفاصيل الكاملة حول كيفية تجميع طلبات البيانات من واجهة برمجة التطبيقات في "مستندات Google" والمستندات المرجعية
documents.batchUpdate
لأنواع الطلبات والردود.
عمليات التعديل المجمّع
هناك أنواع مختلفة من طلبات التعديل المجمّع. في ما يلي تفاصيل أنواع الطلبات، التي تم تجميعها في فئات مختلفة.