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

Существует несколько принципов, которым следует следовать при использовании API Документов Google. К ним относятся:

  • Редактируйте в обратном порядке для повышения эффективности
  • План сотрудничества
  • Обеспечьте согласованность состояния с помощью поля 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, изменения запроса на запись применяются к изменениям соавтора. Результат запроса на запись включает в себя как изменения запроса на запись, так и изменения соавтора в новой версии документа. Сервер Документов отвечает за объединение контента.

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

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

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

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

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