مستند

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

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

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

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

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

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

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