أفضل الممارسات لتحقيق أفضل النتائج

هناك عدة مبادئ يجب اتّباعها عند استخدام Google Docs API. ومن بينها:

  • التعديل من الخلف لتحقيق الكفاءة
  • التخطيط للتعاون
  • ضمان اتساق الحالة باستخدام الحقل WriteControl
  • مراعاة علامات التبويب

توضّح الأقسام التالية هذه المبادئ.

التعديل من الخلف لتحقيق الكفاءة

ضمن طلب واحد يتم إرساله إلى الطريقة documents.batchUpdate، رتِّب طلباتك ترتيبًا تنازليًا حسب الموقع الجغرافي للفهرس. وهذا يلغي الحاجة إلى احتساب التغييرات في الفهرس بسبب عمليات الإدراج والحذف.

التخطيط للتعاون

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

كيف يمكن أن يتغيّر المستند بين استدعاءات الطُرق؟

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

ضمان اتساق الحالة باستخدام WriteControl

عند قراءة مستند ثم تعديله، يمكنك التحكّم في طريقة التعامل مع التغييرات المتعارضة باستخدام الحقل WriteControl في طريقة documents.batchUpdate. توفّر السمة WriteControl إذنًا بالتحكّم في طريقة تنفيذ طلبات الكتابة.

إليك كيفية استخدامه:

  1. احصل على المستند باستخدام طريقة documents.get واحفظ revisionId من المرجع documents الذي تم عرضه.
  2. إنشاء طلبات التعديل
  3. أدرِج عنصر WriteControl اختياريًا مع أحد الخيارَين التاليَين:
    1. يتم ضبط الحقل requiredRevisionId على revisionId للمستند الذي يتم تطبيق طلب الكتابة عليه. إذا تم تعديل المستند منذ طلب القراءة من واجهة برمجة التطبيقات، لن تتم معالجة طلب الكتابة وسيتم عرض خطأ.
    2. يتم ضبط الحقل targetRevisionId على revisionId الخاص بالمستند الذي يتم تطبيق طلب الكتابة عليه. إذا تم تعديل المستند منذ طلب القراءة من واجهة برمجة التطبيقات، سيتم تطبيق تغييرات طلب الكتابة على تغييرات المتعاون. تتضمّن نتيجة طلب الكتابة التغييرات التي تم إجراؤها على طلب الكتابة والتغييرات التي أجراها المتعاون في نسخة جديدة من المستند. يكون خادم "مستندات Google" مسؤولاً عن دمج المحتوى.

للاطّلاع على مثال حول كيفية إنشاء طلب مجمّع باستخدام WriteControl، راجِع مثال الطلب المجمّع هذا.

مراعاة علامات التبويب

يمكن أن يحتوي مستند واحد على عدة علامات تبويب، ما يتطلّب معالجة خاصة في طلبات واجهة برمجة التطبيقات.

في ما يلي ما يجب تذكُّره:

  1. اضبط المَعلمة includeTabsContent على true في طريقة documents.get لاسترداد المحتوى من جميع علامات التبويب في مستند. بشكل تلقائي، لا يتم عرض كل محتوى علامات التبويب.
  2. حدِّد معرّفات علامات التبويب التي تريد تطبيق كل Request عليها في طريقة documents.batchUpdate. يتضمّن كل Request طريقة لتحديد علامات التبويب التي سيتم تطبيق التحديث عليها. بشكلٍ تلقائي، إذا لم يتم تحديد علامة تبويب، سيتم تطبيق Request في معظم الحالات على علامة التبويب الأولى في المستند. يُرجى الرجوع إلى مستندات Requests للحصول على التفاصيل.