مستند

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

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

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

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

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

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

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. الحصول على المستند لمعرّف مستند محدّد

سير عمل إنشاء المستندات

إنّ إنشاء مستند جديد وملؤه أمران مباشران، لأنّه ما مِن محتوًى حالي يدعو للقلق، ولا يوجد متعاونون يمكنهم تغيير حالة المستند. من الناحية النظرية، يعمل هذا الإجراء على النحو الموضّح في الرسم البياني التالي لسلسلة الخطوات:

سير العمل لإنشاء مستند جديد و preenchimento
الشكل 1. سير العمل لإنشاء مستند جديد وملؤه

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

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

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

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

سير العمل لتعديل مستند
الشكل 2. سير العمل لتعديل مستند

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

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

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