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

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

أخذ علامات التبويب في الاعتبار

يمكن أن يحتوي مستند واحد على عدة علامات تبويب، والتي معالجة معيّنة في طلبات البيانات من واجهة برمجة التطبيقات.

إليك ما يجب تذكره:

  1. اضبط المَعلمة includeTabsContent على true في documents.get من أجل استرداد المحتوى من كل علامات التبويب في المستند. علامة التبويب ليست كلها متاحة تلقائيًا يتم إرجاع المحتويات.
  2. حدِّد أرقام التعريف لعلامات التبويب لتطبيق كل Request. إلى في documents.batchUpdate . كل Request طريقة لتحديد علامات التبويب لتطبيق التحديث عليها. بشكل افتراضي، إذا تم لم يتم تحديد علامة التبويب، فإن Request سيتم تطبيقه في معظم الحالات على علامة التبويب الأولى في المستند. ارجع إلى Request وثائق للتفاصيل.