بهترین روش ها برای بهترین نتایج
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
هنگام استفاده از Google Docs API چندین اصل وجود دارد که باید رعایت کنید. این موارد عبارتند از:
- برای بهره وری به عقب ویرایش کنید
- برای همکاری برنامه ریزی کنید
- از سازگاری حالت با استفاده از فیلد
WriteControl اطمینان حاصل کنید - برگه ها را در نظر بگیرید
بخش های بعدی این اصول را توضیح می دهند.
برای بهره وری به عقب ویرایش کنید
در طی یک تماس با روش documents.batchUpdate ، درخواست‌های خود را به ترتیب نزولی مکان فهرست سفارش دهید. این نیاز به محاسبه تغییرات شاخص به دلیل درج و حذف را حذف می کند.
برای همکاری برنامه ریزی کنید
انتظار داشته باشید که وضعیت سند تغییر کند. بین یک فراخوانی روش و دیگری، همکاران دیگر ممکن است سند را به روز کنند، همانطور که در نمودار زیر نشان داده شده است:
اگر ایندکس های شما اشتباه باشد، این می تواند منجر به خطا شود. با چندین کاربر که یک سند را با استفاده از رابط کاربری ویرایش می‌کنند، Google Docs به طور شفاف از این موضوع مراقبت می‌کند. با این حال، به عنوان یک مشتری API، برنامه شما باید این را مدیریت کند. حتی اگر همکاری در سند را پیش‌بینی نمی‌کنید، مهم است که به صورت تدافعی برنامه‌ریزی کنید و مطمئن شوید که وضعیت سند ثابت می‌ماند. برای یک راه برای اطمینان از سازگاری، بخش WriteControl بررسی کنید.
سازگاری حالت را با WriteControl ایجاد کنید
هنگامی که یک سند را می خوانید و سپس به روز می کنید، می توانید با استفاده از فیلد WriteControl در روش documents.batchUpdate ، رفتار تغییرات رقیب را کنترل کنید. WriteControl بر نحوه اجرای درخواست های نوشتن اختیار می دهد.
در اینجا نحوه استفاده از آن آمده است:
- سند را با استفاده از روش
documents.get دریافت کنید و revisionId را از منبع documents برگشتی ذخیره کنید. - درخواست های به روز رسانی خود را بنویسید.
- شامل یک شی
WriteControl اختیاری با یکی از دو گزینه:- فیلد
requiredRevisionId روی revisionId سندی که درخواست نوشتن روی آن اعمال می شود تنظیم می شود. اگر سند از زمان درخواست خواندن API اصلاح شده باشد، درخواست نوشتن پردازش نمی‌شود و یک خطا برمی‌گرداند. - فیلد
targetRevisionId روی revisionId سندی که درخواست نوشتن روی آن اعمال می شود تنظیم می شود. اگر سند از زمان درخواست خواندن API اصلاح شده باشد، تغییرات درخواست نوشتن در برابر تغییرات همکار اعمال می شود. نتیجه درخواست نوشتن، هم تغییرات درخواست نوشتن و هم تغییرات همکار را در یک ویرایش جدید از سند ترکیب می‌کند. سرور Docs مسئول ادغام محتوا است.
برای مثالی از نحوه ساخت یک درخواست دسته ای با استفاده از WriteControl ، به این مثال درخواست دسته ای مراجعه کنید.
برگه ها را در نظر بگیرید
یک سند واحد می‌تواند حاوی چندین برگه باشد که نیاز به رسیدگی خاصی در درخواست‌های API شما دارند.
در اینجا چیزی است که باید به خاطر بسپارید:
- پارامتر
includeTabsContent را در متد documents.get روی true تنظیم کنید تا محتوا را از همه برگه های یک سند بازیابی کنید. به طور پیش فرض، همه محتویات برگه برگردانده نمی شوند. - شناسه(های) برگه(ها) را برای اعمال هر
Request در متد documents.batchUpdate مشخص کنید. هر Request شامل راهی برای مشخص کردن برگه هایی است که به روز رسانی را در آنها اعمال کنید. به‌طور پیش‌فرض، اگر یک برگه مشخص نشده باشد، در بیشتر موارد Request در اولین برگه سند اعمال می‌شود. برای جزئیات بیشتر به مستندات Request مراجعه کنید.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده 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)"]]
