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» .
Рабочий процесс обновления документа
Создать и заполнить новый документ несложно, поскольку нет существующего контента, о котором стоит беспокоиться, и нет соавторов, которые могли бы изменить состояние документа. Концептуально это работает, как показано на следующей диаграмме последовательности:
Обновление существующего документа является более сложным. Прежде чем вы сможете совершать осмысленные вызовы для обновления документа, вам необходимо знать текущее состояние документа: какие элементы его составляют, какое содержимое находится в этих элементах и где все эти элементы расположены в документе. Следующая диаграмма последовательности показывает, как это работает:
На этой схеме не рассматриваются рабочие процессы, в которых другие соавторы одновременно вносят обновления в один и тот же документ. См. План сотрудничества для обсуждения этой темы.