В этом руководстве описаны основные методы запроса и ответа, составляющие API Google Docs, а также способы пакетного обновления документа.
Вы можете вызвать API Google Docs с помощью HTTP-запроса или с помощью вызова метода в клиентской библиотеке , специфичной для конкретного языка программирования. В целом, это эквивалентные способы.
API Google Docs возвращает HTTP-ответ, который обычно включает результат выполнения запроса. При использовании клиентской библиотеки для отправки запросов ответы возвращаются в формате, специфичном для конкретного языка.
Методы запроса
API документации поддерживает следующие методы:
documents.create: Создать пустой документ Google Docs.documents.get: Возвращает полный экземпляр указанного документа. Вы можете проанализировать полученный JSON, чтобы извлечь содержимое документа, форматирование и другие характеристики.documents.batchUpdate: Отправляет список запросов на редактирование, которые будут применены к документу атомарно, и возвращает список результатов.
Методы documents.get и documents.batchUpdate принимают в качестве параметра documentId для указания целевого документа. Метод documents.create возвращает экземпляр созданного документа, из которого можно прочитать documentId . Дополнительную информацию о documentId см. в разделе «Идентификатор документа» .
Опубликованные документы
Метод documents.get нельзя использовать для получения опубликованных документов. После публикации общедоступные документы используют другой формат URL с уникальным публичным documentId . Попытки использовать публичный documentId с методом documents.get приводят к ошибке 404 (код состояния HTTP).
Аналогично, вы не можете использовать метод files.copy из API Google Drive для копирования опубликованного документа.
Для получения или копирования опубликованного документа необходимо использовать исходный documentId . Способов извлечения исходного documentId из опубликованного URL-адреса не существует.
Для получения более подробной информации см.:
- Сделайте документы, таблицы, презентации и формы Google общедоступными.
- Скопировать существующий документ
Пакетные обновления
Метод documents.batchUpdate принимает список объектов request , каждый из которых определяет отдельный запрос для выполнения. Например, форматирование абзаца и последующее добавление встроенного изображения. Каждый запрос проверяется перед применением, и запросы обрабатываются в порядке их появления в пакетном запросе.
Все запросы в пакетном обновлении применяются атомарно. То есть, если какой-либо запрос недействителен, то все обновление считается неудачным, и ни одно из (потенциально зависимых) изменений не применяется.
Некоторые методы documents.batchUpdate предоставляют ответы с информацией о выполненных запросах. Эти методы возвращают тело ответа , содержащее список объектов response . Другие запросы не требуют возврата информации и выдают пустой ответ. Объекты в списке ответов занимают тот же порядок индексации, что и соответствующий запрос.
Популярный шаблон для создания пакетных запросов выглядит следующим образом:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Подробную информацию о том, как объединять вызовы Docs API в пакетную обработку, см. в разделе «Рекомендации по пакетным запросам» , а также в справочной документации по типу запроса и ответам, содержащейся в файле documents.batchUpdate .
Операции пакетного обновления
Существует несколько типов запросов на пакетное обновление. Ниже приведено описание типов запросов , сгруппированных по различным категориям.