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