أفضل الممارسات لتحقيق أفضل النتائج
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
هناك عدة مبادئ يجب اتّباعها عند استخدام 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 في معظم الحالات على علامة التبويب الأولى في المستند. يُرجى الرجوع إلى مستندات
Requests
للحصول على التفاصيل.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Best practices for best results\n\nThere are several principles you should follow when using the Google Docs API.\nThese include:\n\n- Edit backwards for efficiency\n- Plan for collaboration\n- Ensure state consistency using the [`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol) field\n- Take tabs into account\n\nThe following sections explain these principles.\n\nEdit backwards for efficiency\n-----------------------------\n\nWithin a single call to the\n[`documents.batchUpdate`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate)\nmethod, order your requests in\n*descending order* of index location. This eliminates the need to compute the\nindex changes due to insertions and deletions.\n\nPlan for collaboration\n----------------------\n\nExpect the document state to change. Between one method call and another, other\ncollaborators might update the document, as shown in the following diagram:\n\nThis can lead to errors if your indexes are wrong. With multiple users editing a\ndocument using the UI, Google Docs takes care of this transparently. However,\nas an API client your app must manage this. Even if you don't anticipate\ncollaboration on the document, it's important to program defensively and make\nsure the document state remains consistent. For one way to ensure consistency,\nreview the [`WriteControl`](#establish-state-consistency) section.\n\nEstablish state consistency with WriteControl\n---------------------------------------------\n\nWhen you read and then update a document, you can control the behavior of how\ncompeting changes are handled using the\n[`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol)\nfield in the `documents.batchUpdate` method. `WriteControl` provides authority\nover how write requests are executed.\n\nHere's how you use it:\n\n1. Get the document using the [`documents.get`](/workspace/docs/api/reference/rest/v1/documents/get) method and save the [`revisionId`](/workspace/docs/api/reference/rest/v1/documents#Document.FIELDS.revision_id) from the returned `documents` resource.\n2. Compose your update requests.\n3. Include an optional [`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol) object with one of two options:\n 1. The `requiredRevisionId` field is set to the `revisionId` of the document the write request is applied to. If the document was modified since the API read request, the write request isn't processed and it returns an error.\n 2. The `targetRevisionId` field is set to the `revisionId` of the document the write request is applied to. If the document was modified since the API read request, the write request changes are applied against the collaborator changes. The result of the write request incorporates both the write request changes and the collaborator changes into a new revision of the document. The Docs server is responsible for merging the content.\n\nFor an example of how to construct a batch request using `WriteControl`, see\nthis [batch request example](/workspace/docs/api/how-tos/batch#example).\n\nTake tabs into account\n----------------------\n\nA single document can contain multiple [tabs](/workspace/docs/api/how-tos/tabs),\nwhich require specific handling in your API requests.\n\nHere's what to remember:\n\n1. Set the `includeTabsContent` parameter to `true` in the [`documents.get`](/workspace/docs/api/reference/rest/v1/documents/get) method to retrieve the content from all tabs in a document. By default, not all tab contents are returned.\n2. Specify the ID(s) of the tab(s) to apply each [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) to in the [`documents.batchUpdate`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate) method. Each [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) includes a way to specify the tabs to apply the update to. By default, if a tab is not specified, the [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) will in most cases be applied to the first tab in the document. Refer to the [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request)s documentation for specifics.\n\nRelated topics\n--------------\n\n- [Batch requests](/workspace/docs/api/how-tos/batch)\n- [Requests and responses](/workspace/docs/api/concepts/request-response)\n- [Work with tabs](/workspace/docs/api/how-tos/tabs)"]]
