مستند

يقدم هذا الدليل مفاهيم مثل الأساليب الأساسية التي يتكون منها واجهة برمجة التطبيقات لمستندات Google وكيفية الوصول إلى المستند وسير العمل عند إنشاء المستند.

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

يوفّر المورد documents طرقًا تستخدمها لاستدعاء واجهة برمجة تطبيقات "مستندات Google". تتيح لك الطرق التالية إنشاء مستندات في "مستندات 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. لمزيد من المعلومات، يُرجى الاطّلاع على نسخ مستند حالي.

عند استخدام واجهة برمجة تطبيقات "مستندات Google" تلقائيًا، يتم حفظ مستند جديد في المجلد الجذر للمستخدم على Drive. هناك خيارات لحفظ ملف في مجلد Drive. لمزيد من المعلومات، يُرجى الاطّلاع على العمل باستخدام مجلدات Google Drive.

العمل باستخدام ملفات "مستندات Google"

لاسترداد مستند من "ملفاتي" لمستخدم، غالبًا ما يكون من الضروري استخدام طريقة files.list في Drive أولاً لاسترداد رقم تعريف ملف. يؤدي استدعاء الطريقة بدون أي معلمات إلى عرض قائمة بجميع الملفات والمجلدات، بما في ذلك المعرّفات، للمستخدم.

يشير نوع MIME للمستند إلى نوع البيانات وتنسيقها. تنسيق نوع MIME لمستندات Google هو application/vnd.google-apps.document. للحصول على قائمة بأنواع MIME، يُرجى الاطّلاع على أنواع رموز MIME المتوافقة مع Google Workspace وGoogle Drive.

للبحث حسب نوع MIME لملفات "مستندات Google" فقط ضمن "ملفاتي"، أضِف فلتر سلسلة طلب البحث التالي:

q: mimeType = 'application/vnd.google-apps.document'

لمزيد من المعلومات حول فلاتر سلسلة طلب البحث، يُرجى الاطّلاع على قسم البحث عن الملفات والمجلدات.

بعد التعرّف على documentId، استخدِم طريقة documents.get لاسترداد نسخة كاملة من المستند المحدّد. لمزيد من المعلومات، يُرجى الاطّلاع على الطلبات والردود.

لتصدير محتوى مستندات Google Workspace بالبايت، استخدِم طريقة files.export في Drive مع 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 نصًا للاستجابة يتضمّن معلومات عن الطلبات المطبَّقة، بينما تعرض طرق أخرى ردًا فارغًا.

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