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