مستند

يعرّف هذا الدليل مفاهيم مثل الطرق الأساسية التي تشكّل 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"

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

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

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

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

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

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

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

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