Лучшие практики для достижения наилучших результатов
Оптимизируйте свои подборки
Сохраняйте и классифицируйте контент в соответствии со своими настройками.
При использовании API Google Docs следует соблюдать несколько принципов. Вот некоторые из них:
Редактировать в обратном порядке для эффективности
План сотрудничества
Обеспечение согласованности состояния с помощью поля 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 в 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)"]]
