במסגרת קריאה אחת לשיטת
documents.batchUpdate, מסדרים את הבקשות בסדר יורד של מיקום האינדקס. כך לא צריך לחשב את השינויים באינדקס בגלל הוספות ומחיקות.
תכנון שיתוף הפעולה
מצב המסמך צפוי להשתנות. בין קריאה אחת של method לקריאה אחרת, יכול להיות שמשתפי פעולה אחרים יעדכנו את המסמך, כמו שמוצג בתרשים הבא:
אם האינדקסים שגויים, יכולות להופיע שגיאות. אם כמה משתמשים עורכים מסמך באמצעות ממשק המשתמש, Google Docs מטפל בזה באופן שקוף. עם זאת, האפליקציה שלכם צריכה לנהל את זה כלקוח API. גם אם אתם לא צופים שיהיה שיתוף פעולה במסמך, חשוב לתכנת בצורה שתמנע בעיות ולוודא שמצב המסמך יישאר עקבי. כדי להבטיח עקביות, אפשר לעיין בקטע WriteControl.
איך שומרים על עקביות המצב באמצעות WriteControl
כשקוראים מסמך ואז מעדכנים אותו, אפשר לשלוט בהתנהגות של הטיפול בשינויים מתחרים באמצעות השדה WriteControl בשיטה documents.batchUpdate. WriteControl מספק הרשאה לגבי אופן הביצוע של בקשות כתיבה.
אפשר לכלול אובייקט WriteControl אופציונלי עם אחת משתי האפשרויות הבאות:
השדה requiredRevisionId מוגדר לערך revisionId של המסמך שאליו מוחלת בקשת הכתיבה. אם המסמך השתנה מאז בקשת הקריאה של ה-API, בקשת הכתיבה לא תעובד ותוחזר שגיאה.
השדה targetRevisionId מוגדר לערך revisionId של המסמך שאליו מוחלת בקשת הכתיבה. אם המסמך שונה מאז בקשת הקריאה של ה-API, השינויים שבוצעו בבקשת הכתיבה יחולו על השינויים שבוצעו על ידי שותפי העריכה. התוצאה של בקשת הכתיבה משלבת את השינויים של בקשת הכתיבה ואת השינויים של שותף העריכה בגרסה חדשה של המסמך. השרת של Docs אחראי למיזוג התוכן.
דוגמה לאופן יצירת בקשה באצווה באמצעות WriteControl מופיעה כאן.
התחשבות ברווחים מפרסום בכרטיסיות
מסמך יחיד יכול להכיל כמה כרטיסיות, שנדרש טיפול ספציפי בבקשות ה-API.
חשוב לזכור:
מגדירים את הפרמטר includeTabsContent לערך true בשיטה
documents.get
כדי לאחזר את התוכן מכל הכרטיסיות במסמך. כברירת מחדל, לא מוחזר כל התוכן של הכרטיסייה.
מציינים את המזהים של הכרטיסיות שרוצים להחיל עליהן כל Request
בשיטה documents.batchUpdate. כל
Request
כולל דרך לציין את הכרטיסיות שבהן יחול העדכון. כברירת מחדל, אם לא מציינים כרטיסייה, התג Request יחול ברוב המקרים על הכרטיסייה הראשונה במסמך. פרטים נוספים מופיעים במסמכי התיעוד של Request.
[[["התוכן קל להבנה","easyToUnderstand","thumb-up"],["התוכן עזר לי לפתור בעיה","solvedMyProblem","thumb-up"],["סיבה אחרת","otherUp","thumb-up"]],[["חסרים לי מידע או פרטים","missingTheInformationINeed","thumb-down"],["התוכן מורכב מדי או עם יותר מדי שלבים","tooComplicatedTooManySteps","thumb-down"],["התוכן לא עדכני","outOfDate","thumb-down"],["בעיה בתרגום","translationIssue","thumb-down"],["בעיה בדוגמאות/בקוד","samplesCodeIssue","thumb-down"],["סיבה אחרת","otherDown","thumb-down"]],["עדכון אחרון: 2025-08-29 (שעון UTC)."],[],[],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)"]]
