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