Введение

API Документов Google позволяет создавать и изменять документы.

Приложения могут интегрироваться с API Docs для создания безупречных документов на основе пользовательских и системных данных. API позволяет:

  • Автоматизировать процессы
  • Массовое создание документации
  • Генерация счетов или договоров

Обзор API

Ресурс документов предоставляет методы, которые вы используете для вызова API Документов.

Методы API

Следующие методы позволяют создавать, читать и обновлять документы Google Docs:

  • Используйте document.create для создания документа.
  • Используйте document.get для получения содержимого указанного документа.
  • Используйте document.batchUpdate для атомарного выполнения набора обновлений для указанного документа.

Методам get и batchUpdate требуется documentId (см. ниже) в качестве параметра для указания целевого документа. Метод create возвращает экземпляр созданного документа, из которого можно прочитать идентификатор.

Пакетные обновления

Метод batchUpdate принимает список объектов запроса и выполняет обновления в том же порядке, в котором они появляются в пакетном запросе. Обновления в пакетном обновлении применяются атомарно. То есть, если какой-либо запрос недействителен, то все обновление завершается неудачей и ни одно из (потенциально зависимых) изменений не применяется.

Метод batchUpdate возвращает список объектов ответа. Объекты в этом списке занимают тот же порядок индексации, что и соответствующий запрос.

См. рекомендации по пакетному запросу , чтобы узнать, как группировать вызовы API, а также справочную документацию по пакетному обновлению для типов запроса и ответа.

Идентификатор документа

Идентификаторы документов ссылаются на документ и могут быть получены из URL-адреса:

https://docs.google.com/document/d/documentId/edit

documentId — это уникальная строка, содержащая буквы, цифры и некоторые специальные символы. Следующее регулярное выражение можно использовать для извлечения идентификатора документа из URL-адреса Документов Google:

/document/d/([a-zA-Z0-9-_]+)

Если вы знакомы с API Google Диска, documentId соответствует идентификатору файлового ресурса.

Места внутри документа: индексы

Когда вы обновляете содержимое документа, каждое обновление происходит в определенном месте или в диапазоне внутри документа. Эти местоположения и диапазоны задаются с помощью индексов , которые представляют собой смещение внутри содержащего его сегмента документа. Чтобы узнать больше об индексах и о том, как их использовать, см. концептуальное руководство «Структура документа Google Docs» .

Рабочий процесс обновления документа

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

Рабочий процесс создания и заполнения нового документа.

Обновление существующего документа является более сложным. Прежде чем вы сможете совершать осмысленные вызовы для обновления документа, вам необходимо знать текущее состояние документа: какие элементы его составляют, какое содержимое находится в этих элементах и ​​где все эти элементы расположены в документе. Следующая диаграмма последовательности показывает, как это работает:

Рабочий процесс для обновления документа.

На этой схеме не рассматриваются рабочие процессы, в которых другие соавторы одновременно вносят обновления в один и тот же документ. См. План сотрудничества для обсуждения этой темы.