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

При использовании 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. В методе documents.batchUpdate укажите идентификаторы вкладок, к которым будет применяться каждый Request . Каждый Request включает в себя способ указания вкладок, к которым будет применяться обновление. По умолчанию, если вкладка не указана, Request в большинстве случаев будет применен к первой вкладке в документе. Для получения более подробной информации обратитесь к документации по Request .