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