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

هناك عدة مبادئ يجب اتّباعها عند استخدام 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 في المستند الذي يتم تطبيق طلب الكتابة عليه. إذا تم تعديل المستند منذ طلب قراءة واجهة برمجة التطبيقات، يتم تطبيق تغييرات طلب الكتابة مقابل تغييرات المتعاون. تتضمن نتيجة طلب الكتابة كلاً من تغييرات طلب الكتابة وتغييرات المتعاون في مراجعة جديدة للوثيقة. يكون خادم محرّر المستندات مسئولاً عن دمج المحتوى.

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