يقدم هذا الدليل مفاهيم مثل الطرق الأساسية التي تشكل واجهة برمجة التطبيقات لمحرّر مستندات Google وكيفية الوصول إلى مستند وسير العمل عند إنشاء جلسة المراجعة.
طرق واجهة برمجة التطبيقات
يوفّر مرجع documents
الطرق التي تستخدمها لاستدعاء واجهة برمجة تطبيقات المستندات. تتيح لك الطرق التالية
إنشاء مستندات في "مستندات Google" وقراءتها وتحديثها:
- استخدام
documents.create
لإنشاء مستند. - استخدام الطريقة
documents.get
لاسترداد محتويات مستند محدد. - استخدام
documents.batchUpdate
لإجراء مجموعة من التحديثات على مستند محدد بشكل كامل.
تتطلّب الطريقتان documents.get
وdocuments.batchUpdate
السمة documentId
.
كمعلمة لتحديد المستند المستهدف. الطريقة documents.create
مثيل للمستند الذي تم إنشاؤه، والذي يمكنك من خلاله قراءة
documentId
لمزيد من المعلومات حول طلبات واجهة برمجة التطبيقات لـ "مستندات Google"
طريقة الاستجابة، راجع الطلبات
الردود.
معرّف المستند
documentId
هو المعرّف الفريد للمستند ويمكن اشتقاقه.
من عنوان URL لمستند. إنها سلسلة معينة تحتوي على أحرف وأرقام
بعض الرموز الخاصة. تكون معرّفات المستندات ثابتة، حتى إذا كان اسم المستند
التغييرات.
https://docs.google.com/document/d/DOCUMENT_ID/edit
يمكن استخدام التعبير العادي التالي لاستخراج documentId
من
عنوان URL لـ "مستندات Google":
/document/d/([a-zA-Z0-9-_]+)
إذا كنت على دراية بواجهة برمجة تطبيقات Google Drive، يتوافق documentId
مع id
.
في المرجع files
.
إدارة المستندات في Google Drive
يتم تخزين ملفات المستندات في Google Drive، وهو عبارة عن مساحة تخزين مستنِدة إلى السحابة الإلكترونية
خدمة ما. وعلى الرغم من أن واجهة برمجة التطبيقات لـ Docs API لها طرقها المستقلة، إلا أنها غالبًا ما
أيضًا استخدام طرق واجهة برمجة تطبيقات Google Drive للتفاعل مع حسابات
ملفات "مستندات Google" على سبيل المثال، لنسخ ملفات المستندات، استخدم
files.copy
في Drive API
. لمزيد من المعلومات، يُرجى الاطّلاع على نسخ مستند حالي
المستند.
بشكل افتراضي، عند استخدام واجهة برمجة تطبيقات المستندات، يتم حفظ مستند جديد في المجلد الجذر للمستخدم على Drive. هناك خيارات لحفظ ملف إلى مجلد في Drive. لمزيد من المعلومات، يُرجى الاطّلاع على العمل مع مجلدات Google Drive.
العمل باستخدام ملفات "مستندات Google"
لاسترداد مستند ما من "ملفاتي" لدى أحد المستخدمين، غالبًا ما
لاستخدام واجهة برمجة تطبيقات Drive أولاً
files.list
لاسترداد
رقم تعريف لملف. يؤدي استدعاء الطريقة بدون أي معلمات إلى إرجاع قائمة بجميع
الملفات والمجلدات، بما في ذلك أرقام التعريف، للمستخدم.
يشير نوع MIME للمستند إلى نوع البيانات وتنسيقها. تنسيق نوع MIME
بالنسبة إلى "مستندات Google" هو application/vnd.google-apps.document
. للحصول على قائمة
أنواع MIME، يُرجى الاطّلاع على ترميز MIME المتوافق مع Google Workspace وGoogle Drive.
الأنواع.
للبحث حسب نوع MIME لملفات "مستندات Google" فقط ضمن Drive، أضِف فلتر سلسلة طلب البحث التالي:
q: mimeType = 'application/vnd.google-apps.document'
لمزيد من المعلومات حول فلاتر سلسلة طلب البحث، اطّلِع على المقالة البحث عن الملفات و المجلدات.
بعد معرفة documentId
، استخدِم
documents.get
لاسترداد
مثيل كامل للوثيقة المحددة. لمزيد من المعلومات، يُرجى مراجعة
الطلبات والردود:
لتصدير محتوى مستندات Google Workspace بالبايت، استخدم
files.export
مع
documentId
للملف المطلوب تصديره وتصدير MIME الصحيح
النوع. لمزيد من المعلومات، راجع تصدير
مستند Google Workspace
المحتوى.
المقارنة بين الطريقتَين Get
وList
يوضّح الجدول التالي الاختلافات بين Drive ومحرّر المستندات والبيانات التي يتم عرضها مع كل منهما:
مُشغِّل | الوصف | الاستخدام |
---|---|---|
drive.files.get |
الحصول على البيانات الوصفية للملف حسب رقم التعريف تعرض هذه السمة مثالاً على مورد files . |
الحصول على البيانات الوصفية لملف معيّن |
drive.files.list |
الحصول على ملفات المستخدم عرض قائمة بالملفات. | احصل على قائمة بملفات المستخدمين إذا لم تكن متأكدًا من الملف الذي يجب تعديله. |
docs.documents.get |
الحصول على أحدث نسخة من المستند المحدّد، بما في ذلك جميع التنسيقات والنصوص تعرض هذه السمة مثالاً على مورد documents . |
احصل على المستند للحصول على معرّف مستند محدّد. |
سير عمل إنشاء المستندات
يُعد إنشاء مستند جديد وتعبئته أمرًا سهلاً، نظرًا لعدم وجود المحتوى الحالي الذي يدعو إلى القلق ولن يكون هناك أي متعاونين يمكنهم تغيير حالة المستند. من الناحية النظرية، يعمل ذلك على النحو الموضّح في التسلسل التالي الرسم التخطيطي:
في الشكل 1.، قد يتفاعل أحد المستخدمين مع
يحتوي مورد documents
على ما يلي
تدفق المعلومات:
- يستدعي أحد التطبيقات
تم تفعيل إجراء
documents.create
خادم ويب. - يرسل خادم الويب استجابة HTTP تتضمن مثيلاً لخطأ
تم إنشاء المستند كمورد
documents
. - اختياريًا، يستدعي التطبيق
documents.batchUpdate
لتنفيذ مجموعة من طلبات التعديل بشكل كامل لتعبئة المستند مع البيانات. - يرسل خادم الويب استجابة HTTP. بعض طُرق
documents.batchUpdate
وتوفر هيئة استجابة تضم معلومات حول الطلبات المطبقة، بينما يعرض البعض الآخر ردًا فارغًا.
سير عمل تعديل المستندات
تُعد تحديث مستند حالي أكثر تعقيدًا. قبل أن تتمكن من توضيح لتحديث مستند، يجب أن تعرف حالته الحالية وهي: ما العناصر التي والمحتوى الموجود في هذه العناصر، وترتيب العناصر داخل المستند. ويوضح مخطط التسلسل التالي كيفية عمل ذلك:
في الشكل 2.، يحصل أي مستخدم يتفاعل مع مورد documents
على
التدفق التالي للمعلومات:
- يستدعي أحد التطبيقات
طريقة
documents.get
على الويب الخادم، معdocumentId
من الملف المطلوب العثور عليه. - يرسل خادم الويب استجابة HTTP تتضمن مثيلاً لخطأ
المستند المحدد كمورد
documents
. يحتوي ملف JSON المعروض على ومحتوى المستند والتنسيق والميزات الأخرى. - يحلّل التطبيق ملف JSON ليتمكّن المستخدم من تحديد المحتوى أو التنسيق تحديث.
- يطلب التطبيق طريقة
documents.batchUpdate
لتنفيذ مجموعة بشكل كامل. من طلبات التعديل لتحديث المستند. - يرسل خادم الويب استجابة HTTP. بعض طُرق
documents.batchUpdate
وتوفر هيئة استجابة تضم معلومات حول الطلبات المطبقة، بينما يعرض البعض الآخر ردًا فارغًا.
لا يراعي هذا الرسم البياني عمليات سير العمل حيث تُجري تحديثات متزامنة كل المتعاونين في نفس المستند. لمزيد من المعلومات، راجع أفضل قسم الممارسات التخطيط والتعاون.
مواضيع ذات صلة
- بنية مستند "مستندات Google"
- الطلبات والردود
- قواعد التعديل وسلوكه الهيكلي
- أفضل الممارسات لتحقيق أفضل النتائج