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

هناك عدة مبادئ يجب اتّباعها عند استخدام 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 في معظم الحالات على علامة التبويب الأولى في المستند. يمكنك الرجوع إلى مستندات Request للاطّلاع على التفاصيل.