Введение

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

Приложения могут интегрироваться с Docs API для создания безупречных документов как из пользовательских, так и из системных данных. 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 соответствует идентификатору ресурса File .

Расположение в документе: указатели

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

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

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

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

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

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

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