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

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

  • التعديل للخلف لتعزيز الكفاءة
  • التخطيط للتعاون
  • تأكَّد من اتساق الحالة باستخدام WriteControl.

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

التعديل للخلف لتعزيز الكفاءة

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

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

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

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

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

ضمان تناسق الحالة مع WriteControl

عند قراءة مستند ثم تعديله، يمكنك التأكّد من أنّه لم يتم تعديله باستخدام الحقل WriteControl في طريقة BatchUpdate. يتيح لك ذلك إجراء تعديلات على المستند فقط إذا لم يتم تغيير النسخة. إليك كيفية الاستخدام:

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