يتناول هذا الدليل طرق الطلب والاستجابة الأساسية التي تتألف منها واجهة برمجة التطبيقات 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، يُرجى الاطّلاع على معرّف المستند.
يُرجى العِلم أنّه لا يمكنك استخدام طريقة documents.get لاسترداد المستندات المنشورة. بعد نشر المستندات، تستخدم المستندات العامة تنسيقًا مختلفًا لعنوان URL. محاولات استخدام documentId الجديد لعنوان URL مع طريقة documents.get تؤدي إلى عرض رمز حالة HTTP 404. لا تتوفّر طرق لاسترداد
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)
يمكنك الاطّلاع على أفضل الممارسات المتعلقة بالطلبات المجمّعة للحصول على تفاصيل كاملة حول كيفية تجميع طلبات البيانات من Docs API، بالإضافة إلى documents.batchUpdate المستندات المرجعية لأنواع الطلبات والردود.
عمليات التعديل المجمّع
تتوفّر أنواع مختلفة من طلبات التعديل المجمّع. في ما يلي تصنيف أنواع الطلبات المقسّمة إلى فئات مختلفة.