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

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