Лучшие практики для достижения наилучших результатов

При использовании API Google Docs следует соблюдать несколько принципов. Вот некоторые из них:

  • Редактировать в обратном порядке для эффективности
  • План сотрудничества
  • Обеспечение согласованности состояния с помощью поля WriteControl
  • Учитывайте вкладки

В следующих разделах эти принципы объясняются.

Редактировать в обратном порядке для эффективности

В одном вызове метода documents.batchUpdate упорядочьте запросы по убыванию местоположения индекса. Это избавит от необходимости вычислять изменения индекса, связанные с вставками и удалениями.

План сотрудничества

Будьте готовы к изменению состояния документа. Между вызовами одного метода другие участники могут обновить документ, как показано на следующей диаграмме:

Как документ может изменяться между вызовами методов.

Это может привести к ошибкам, если ваши индексы неверны. При редактировании документа несколькими пользователями через пользовательский интерфейс Google Docs обеспечивает прозрачную обработку. Однако, будучи клиентом API, ваше приложение должно контролировать это. Даже если вы не планируете совместную работу над документом, важно программировать с учётом безопасности и обеспечивать согласованность состояния документа. Один из способов обеспечения согласованности описан в разделе WriteControl .

Установите согласованность состояний с помощью WriteControl

При чтении и последующем обновлении документа вы можете управлять обработкой конкурирующих изменений с помощью поля WriteControl в методе documents.batchUpdate . WriteControl обеспечивает управление выполнением запросов на запись.

Вот как это использовать:

  1. Получите документ с помощью метода documents.get и сохраните revisionId из возвращенного ресурса documents .
  2. Составьте ваши запросы на обновление.
  3. Включите необязательный объект WriteControl с одним из двух вариантов:
    1. Поле requiredRevisionId содержит revisionId документа, к которому применяется запрос на запись. Если документ был изменён с момента запроса на чтение через API, запрос на запись не обрабатывается и возвращает ошибку.
    2. Поле targetRevisionId содержит значение revisionId документа, к которому применяется запрос на запись. Если документ был изменён с момента запроса на чтение через API, изменения, внесённые в запросе на запись, применяются к изменениям, внесённым соавтором. Результат запроса на запись включает как изменения, внесённые в запросе на запись, так и изменения, внесённые соавтором, в новую редакцию документа. Сервер Docs отвечает за объединение содержимого.

Пример создания пакетного запроса с использованием WriteControl см. в этом примере пакетного запроса .

Учитывайте вкладки

Один документ может содержать несколько вкладок , что требует особой обработки в запросах API.

Вот что следует помнить:

  1. Установите параметр includeTabsContent в true в методе documents.get , чтобы получить содержимое всех вкладок документа. По умолчанию возвращается не всё содержимое вкладок.
  2. Укажите идентификаторы вкладок, к которым будет применяться каждый Request , в методе documents.batchUpdate . Каждый Request включает способ указать вкладки, к которым будет применено обновление. По умолчанию, если вкладка не указана, Request в большинстве случаев будет применен к первой вкладке документа. Подробности см. в документации по Request .