مقدمة

تتيح لك واجهة برمجة تطبيقات "مستندات Google" إنشاء المستندات وتعديلها.

يمكن أن تتكامل التطبيقات مع واجهة برمجة تطبيقات محرّر المستندات لإنشاء مستندات رائعة من كل من البيانات التي يقدمها المستخدم والبيانات التي يقدمها النظام. تسمح لك واجهة برمجة التطبيقات بما يلي:

  • التشغيل التلقائي للعمليات
  • إنشاء مستندات بشكل مجمّع
  • إنشاء فواتير أو عقود

نظرة عامة على واجهة برمجة التطبيقات

يوفر مورد المستندات الطرق التي تستخدمها لاستدعاء واجهة برمجة تطبيقات المستندات.

طرق واجهة برمجة التطبيقات

تتيح لك الطرق التالية إنشاء مستندات Google وقراءتها وتحديثها:

  • استخدم documents.create لإنشاء مستند.
  • استخدم documents.get لاسترداد محتويات مستند محدد.
  • استخدم documents.batchUpdate لإجراء مجموعة من التحديثات على مستند محدد بشكل ذري.

تتطلب المناهج get وbatchUpdate documentId (انظر أدناه) باعتبارها معلمة لتحديد المستند المستهدف. تعرض طريقة create نسخة افتراضية من المستند الذي تم إنشاؤه، والتي يمكنك قراءة رقم التعريف منها.

تحديثات مجمّعة

تأخذ طريقة batchUpdate قائمة بكائنات الطلب، وتجري التحديثات بالترتيب نفسه الذي تظهر به في الطلب المجمّع. يتم تطبيق التحديثات في التحديث المجمّع بالكامل. وهذا يعني أنه إذا لم يكن أي طلب صالحًا، فهذا يعني أن التحديث بالكامل لم يتم تطبيقه ولم يتم تطبيق أي من التغييرات (التي يُحتمل أن تكون تابعة).

تعرض طريقة batchUpdate قائمة بكائنات الاستجابة. تشغل العناصر في هذه القائمة ترتيب الفهرس نفسه كالطلب المقابل.

اطّلع على أفضل ممارسات الطلبات المجمّعة للتعرّف على كيفية تجميع طلبات البيانات من واجهة برمجة التطبيقات معًا واطلع على الوثائق المرجعية batchUpdate لأنواع الطلبات والاستجابة.

معرّف المستند

تشير معرفات المستند إلى مستند ويمكن اشتقاقه من عنوان URL:

https://docs.google.com/document/d/documentId/edit

documentId عبارة عن سلسلة فريدة تحتوي على أحرف وأرقام وبعض الأحرف الخاصة. يمكن استخدام التعبير العادي التالي لاستخراج رقم تعريف المستند من عنوان URL لمحرّر مستندات Google:

/document/d/([a-zA-Z0-9-_]+)

إذا كنت معتادًا على استخدام واجهة برمجة تطبيقات Google Drive، فسيتوافق documentId مع معرّف مورد الملف.

المواقع داخل المستند: الفهارس

عند إجراء تحديثات على محتوى أحد المستندات، يتم إجراء كل تحديث في موقع أو عبر نطاق ضمن المستند. ويتم تحديد هذه المواقع والنطاقات باستخدام الفهارس، التي تمثل إزاحة ضمن قسم المستند الذي يحتوي على. للتعرف على مزيد من المعلومات حول الفهارس وكيفية استخدامها، راجع دليل مفهوم بنية مستند محرّر مستندات Google.

سير عمل تحديث المستند

يعد إنشاء مستند جديد وملئه أمرًا مباشرًا، نظرًا لعدم وجود محتوى يدعو إلى القلق وعدم وجود متعاونين يمكنهم تغيير حالة المستند. من الناحية النظرية، يعمل هذا على النحو الموضح في مخطط التسلسل التالي:

سير العمل لإنشاء مستند جديد وتعبئته.

عملية تحديث مستند حالي أكثر تعقيدًا. قبل أن تتمكن من إجراء استدعاءات مفيدة لتحديث مستند، يجب أن تعرف الحالة الحالية للمستند: العناصر التي يتكون منها، والمحتوى الموجود في هذه العناصر، ومكان كل هذه العناصر في المستند. يوضّح الرسم البياني التالي للتسلسل كيفية عمل ذلك:

سير العمل لتحديث مستند.

لا يضع هذا الرسم البياني في الاعتبار عمليات سير العمل التي يتم من خلالها إجراء تحديثات متزامنة من قِبل متعاونين آخرين في نفس المستند. انظر التخطيط للتعاون للحصول على مناقشة حول هذا الموضوع.