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

هناك العديد من المبادئ التي يجب اتباعها عند استخدام واجهة برمجة تطبيقات محرر مستندات Google. وتشمل هذه المعلومات ما يلي:

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

تشرح الأقسام التالية هذه المبادئ.

التعديل العكسي لتحسين الكفاءة

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

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

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

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

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

الحفاظ على اتّساق الحالة باستخدام writeControl

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

في ما يلي طريقة استخدام هذا البرنامج:

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

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