مستند

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

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

يوفر المورد documents طرقًا تستخدمها لاستدعاء واجهة برمجة تطبيقات Docs. تتيح لك الطرق التالية إنشاء مستندات في "مستندات 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 API، يتوافق documentId مع id في مورد files.

إدارة المستندات في Google Drive

يتم تخزين ملفات المستندات في Google Drive، وهي خدمة تخزين في السحابة الإلكترونية. على الرغم من أنّ واجهة برمجة تطبيقات محرّر المستندات لها طرق مستقلة خاصة بها، من الضروري أيضًا استخدام طرق واجهة برمجة تطبيقات Google Drive أيضًا للتفاعل مع ملفات المستخدم في "مستندات Google". على سبيل المثال، لنسخ ملفات "مستندات Google"، استخدِم طريقة files.copy في Drive API. لمزيد من المعلومات، يُرجى الاطّلاع على نسخ مستند حالي.

بشكل تلقائي، عند استخدام واجهة برمجة تطبيقات المستندات، يتم حفظ مستند جديد في المجلد الجذر للمستخدم على 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 و"مستندات Google" والبيانات التي يتم عرضها مع كل منهما:

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

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