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

هناك عدة مبادئ يجب اتّباعها عند استخدام 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 ل retrieving the content from all tabs in a document. لا يتم عرض كل محتوى علامة التبويب بشكل تلقائي.
  2. حدِّد أرقام تعريف علامات التبويب لتطبيق كل Request في الطريقة documents.batchUpdate. يتضمّن كل Request طريقة لتحديد علامات التبويب التي سيتم تطبيق التعديل عليها. في معظم الحالات، سيتم تطبيق Request تلقائيًا على علامة التبويب الأولى في المستند إذا لم يتم تحديد علامة تبويب. يُرجى الرجوع إلى مستندات Request للاطّلاع على التفاصيل.