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