مستند

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

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

يوفر المورد documents طرقًا يمكنك استخدامها لتفعيل Docs API. تتيح لك الطرق التالية إنشاء مستندات "مستندات Google" وقراءتها وتعديلها:

  • استخدِم طريقة documents.create لإنشاء مستند.
  • استخدِم طريقة documents.get لاسترداد محتوى مستند محدّد.
  • استخدِم طريقة documents.batchUpdate لإجراء مجموعة من التعديلات بشكل متزامن على مستند محدّد.

تتطلّب الطريقتان documents.get وdocuments.batchUpdate استخدام documentId كمَعلمة لتحديد المستند المستهدف. تعرض الطريقة documents.create نسخة من المستند الذي تم إنشاؤه، ويمكنك من خلالها قراءة documentId. لمزيد من المعلومات حول طلبات واجهة برمجة التطبيقات Docs API وطُرق الاستجابة، يُرجى الاطّلاع على الطلبات والاستجابات.

معرّف المستند

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

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

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