تتيح لك واجهة برمجة تطبيقات "مستندات Google" إنشاء المستندات وتعديلها.
يمكن دمج التطبيقات مع Docs API لإنشاء مستندات مصقولة من كل من البيانات المقدّمة من المستخدم والنظام. تتيح لك واجهة برمجة التطبيقات ما يلي:
- التشغيل التلقائي للعمليات
- إنشاء المستندات بشكلٍ مجمّع
- إنشاء فواتير أو عقود
نظرة عامة على واجهة برمجة التطبيقات
يوفر مورد المستندات طرقًا تستخدمها لاستدعاء Docs API.
طرق واجهة برمجة التطبيقات
تتيح لك الطرق التالية إنشاء مستندات "مستندات 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 API، يتوافق documentId مع معرِّف مورد الملف.
المواقع داخل المستند: الفهارس
عند إجراء تحديثات على محتوى مستند، يتم كل تحديث في موقع ما أو عبر نطاق داخل المستند. يتم تحديد هذه المواقع الجغرافية والنطاقات باستخدام الفهارس، التي تمثل إزاحة ضمن شريحة مستند يتضمّنها. لمزيد من المعلومات حول الفهارس وكيفية استخدامها، راجِع دليل بنية مستند "مستندات Google".
سير عمل تحديث المستند
إنّ إنشاء مستند جديد وتعبئته أمر بسيط، لأنّه لا يوجد محتوى حالي يمكن القلق بشأنه ولا يوجد متعاونون يمكنهم تغيير حالة المستند. نظريًا، يعمل هذا كما هو موضح في مخطط التسلسل التالي:
تحديث مستند موجود هو أكثر تعقيدًا. قبل أن تتمكن من إجراء استدعاءات ذات مغزى لتعديل مستند، عليك معرفة الحالة الحالية للمستند: ما العناصر التي يتألف منها، والمحتوى الموجود في تلك العناصر، وأين توجد كل هذه العناصر داخل المستند. يوضح مخطط التسلسل التالي كيف يعمل ذلك:
لا يأخذ هذا الرسم البياني في الاعتبار مهام سير العمل التي يتم فيها إجراء تحديثات متزامنة من قبل متعاونين آخرين في المستند ذاته. يمكنك الاطّلاع على القسم التخطيط للتعاون لمناقشة هذا الموضوع.