هناك عدة مبادئ يجب اتّباعها عند استخدام Google Docs API. ومن بينها:
- التعديل العكسي لزيادة الكفاءة
- التخطيط للتعاون
- يمكنك التأكّد من اتساق الحالة باستخدام حقل
WriteControl
.
توضح الأقسام التالية هذه المبادئ.
التعديل العكسي لزيادة الكفاءة
من خلال استدعاء واحد للطريقة
documents.batchUpdate
،
رتِّب طلباتك
بترتيب تنازلي للموقع الجغرافي للفهرس. ويلغي ذلك الحاجة إلى حساب تغييرات الفهرس الناتجة عن عمليات الإدراج والحذف.
التخطيط للتعاون
توقّع أن تتغير حالة المستند. بين استدعاء طريقة وأخرى، قد يقوم متعاونون آخرون بتحديث المستند، كما هو موضح في الرسم التخطيطي التالي:
ويمكن أن يؤدي ذلك إلى حدوث أخطاء إذا كانت الفهارس الخاصة بك خاطئة. نظرًا لتحرير العديد من المستخدمين لأحد المستندات باستخدام
واجهة المستخدم، يتولى محرر مستندات Google هذا بشفافية. ومع ذلك، يجب على تطبيقك إدارة هذه الميزة
بصفتك عميل واجهة برمجة التطبيقات. حتى إذا كنت لا تتوقع التعاون في الوثيقة،
من المهم أن تقوم بالبرمجة بشكل دفاعي والتأكد من بقاء حالة الوثيقة متسقة. لإحدى طُرق ضمان الاتساق، راجِع القسم WriteControl
.
الحفاظ على اتساق الحالة باستخدام WriteControl
عند قراءة مستند ثم تعديله، يمكنك التحكّم في سلوك كيفية
معالجة التغييرات التنافسية باستخدام الحقل
WriteControl
في طريقة documents.batchUpdate
. يمنح WriteControl
صلاحية
كيفية تنفيذ طلبات الكتابة.
إليك كيفية استخدامه:
- احصل على المستند باستخدام طريقة
documents.get
واحفظrevisionId
من موردdocuments
الذي تم إرجاعه. - أنشئ طلبات التحديث.
- يمكنك تضمين كائن
WriteControl
اختياري مع أحد الخيارين:- يتم ضبط الحقل
requiredRevisionId
علىrevisionId
في المستند الذي يتم تطبيق طلب الكتابة عليه. إذا تم تعديل المستند بعد أن تم طلب قراءة واجهة برمجة التطبيقات، فلن تتم معالجة طلب الكتابة وسيعرض رسالة خطأ. - يتم ضبط الحقل
targetRevisionId
علىrevisionId
في المستند الذي يتم تطبيق طلب الكتابة عليه. إذا تم تعديل المستند منذ طلب قراءة واجهة برمجة التطبيقات، يتم تطبيق تغييرات طلب الكتابة مقابل تغييرات المتعاون. تتضمن نتيجة طلب الكتابة كلاً من تغييرات طلب الكتابة وتغييرات المتعاون في مراجعة جديدة للوثيقة. يكون خادم محرّر المستندات مسئولاً عن دمج المحتوى.
- يتم ضبط الحقل
للاطّلاع على مثال حول كيفية إنشاء طلب مجمّع باستخدام WriteControl
، يمكنك الاطّلاع على مثال الطلب المجمّع هذا.