مستند

يقدم هذا الدليل مفاهيم مثل الطرق الأساسية التي تشكل واجهة برمجة التطبيقات لمحرّر مستندات 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. سير العمل لإنشاء مستند جديد وتعبئته

في الشكل 1.، قد يتفاعل أحد المستخدمين مع يحتوي مورد documents على ما يلي تدفق المعلومات:

  1. يستدعي أحد التطبيقات تم تفعيل إجراء documents.create خادم ويب.
  2. يرسل خادم الويب استجابة HTTP تتضمن مثيلاً لخطأ تم إنشاء المستند كمورد documents.
  3. يمكن للتطبيق استدعاء الطريقة documents.batchUpdate اختياريًا لتنفيذ مجموعة من طلبات التعديل بشكلٍ موحّد لتعبئة المستند بالبيانات.
  4. يرسل خادم الويب استجابة HTTP. بعض طُرق documents.batchUpdate وتوفر هيئة استجابة تضم معلومات حول الطلبات المطبقة، بينما يعرض البعض الآخر ردًا فارغًا.

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

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

سير العمل لتحديث جلسة المراجعة.
الشكل 2. سير العمل لتعديل مستند

في الشكل 2، يتلقّى المستخدِم الذي يتفاعل مع المورد documents المسار التالي للمعلومات:

  1. يستدعي أحد التطبيقات طريقة documents.get على الويب الخادم، مع documentId من الملف المطلوب العثور عليه.
  2. يرسل خادم الويب استجابة HTTP تتضمن مثيلاً لخطأ المستند المحدد كمورد documents. يحتوي ملف JSON المعروض على ومحتوى المستند والتنسيق والميزات الأخرى.
  3. يحلّل التطبيق ملف JSON ليتمكّن المستخدم من تحديد المحتوى أو التنسيق تحديث.
  4. يستدعي التطبيق طريقة documents.batchUpdate لتنفيذ مجموعة من طلبات التعديل بشكلٍ موحّد لتعديل المستند.
  5. يرسل خادم الويب استجابة HTTP. بعض طُرق documents.batchUpdate وتوفر هيئة استجابة تضم معلومات حول الطلبات المطبقة، بينما يعرض البعض الآخر ردًا فارغًا.

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