Документ

В этом руководстве рассматриваются такие понятия, как основные методы, составляющие API Google Docs, способы доступа к документу и рабочий процесс создания документа.

API-методы

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

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

Методы documents.get и documents.batchUpdate требуют documentId в качестве параметра для указания целевого документа. Метод documents.create возвращает экземпляр созданного документа, из которого можно прочитать documentId . Подробнее о запросах и методах ответов API Docs см. в разделе Запросы и ответы .

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

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

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

Для извлечения documentId из URL-адреса Google Docs можно использовать следующее регулярное выражение:

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

Если вы знакомы с API Google Drive, documentId соответствует id в ресурсе files .

Управление документами в Google Диске

Файлы Docs хранятся в Google Диске, нашем облачном сервисе хранения. Хотя API Docs имеет собственные автономные методы, часто требуется использовать методы API Google Drive для взаимодействия с файлами Docs пользователя. Например, для копирования файлов Docs используйте метод files.copy API Drive. Подробнее см. в разделе Копирование существующего документа .

По умолчанию при использовании Docs API новый документ сохраняется в корневой папке пользователя на Диске. Существует возможность сохранить файл в папке на Диске. Подробнее см. в статье Работа с папками Google Диска .

Работа с файлами Docs

Чтобы получить документ из раздела «Мой диск» пользователя, часто необходимо сначала воспользоваться методом files.list Диска для получения идентификатора файла. Вызов метода без параметров возвращает список всех файлов и папок пользователя, включая идентификаторы.

Тип MIME документа определяет тип данных и формат. Формат типа MIME для Docs — application/vnd.google-apps.document . Список типов MIME см. в разделе «Поддерживаемые типы MIME для Google Workspace и Google Drive» .

Чтобы выполнить поиск по типу MIME только для файлов Docs в разделе «Мой диск», добавьте следующий фильтр строки запроса:

q: mimeType = 'application/vnd.google-apps.document'

Дополнительные сведения о фильтрах строк запроса см. в разделе Поиск файлов и папок .

Узнав documentId , используйте метод documents.get для получения полного экземпляра указанного документа. Подробнее см. в разделе Запросы и ответы .

Чтобы экспортировать байтовое содержимое документа Google Workspace, используйте метод files.export Диска, указав documentId экспортируемого файла и правильный тип MIME для экспорта . Подробнее см. в статье Экспорт содержимого документа Google Workspace .

Сравните методы Get и List

В следующей таблице описываются различия между методами Drive и Docs, а также данные, возвращаемые каждым из них:

Оператор Описание Использование
drive.files.get Получает метаданные файла по идентификатору. Возвращает экземпляр ресурса files . Получить метаданные для конкретного файла.
drive.files.list Получает файлы пользователя. Возвращает список файлов. Получите список пользовательских файлов, если вы не уверены, какой файл необходимо изменить.
docs.documents.get Получает последнюю версию указанного документа, включая всё форматирование и текст. Возвращает экземпляр ресурса documents . Получить документ по определенному идентификатору документа.

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

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

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

На рисунке 1 пользователь, взаимодействующий с ресурсом documents имеет следующий поток информации:

  1. Приложение вызывает метод documents.create на веб-сервере.
  2. Веб-сервер отправляет HTTP-ответ, содержащий экземпляр созданного документа в качестве ресурса documents .
  3. При необходимости приложение вызывает метод documents.batchUpdate для атомарного выполнения набора запросов на редактирование с целью заполнения документа данными.
  4. Веб-сервер отправляет HTTP-ответ. Некоторые методы documents.batchUpdate предоставляют тело ответа с информацией о выполненных запросах, тогда как другие возвращают пустой ответ.

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

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

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

На рисунке 2 пользователь, взаимодействующий с ресурсом documents имеет следующий поток информации:

  1. Приложение вызывает метод documents.get на веб-сервере, передавая documentId искомого файла.
  2. Веб-сервер отправляет HTTP-ответ, содержащий экземпляр указанного документа в качестве documents . Возвращаемый JSON-файл содержит содержимое документа, его форматирование и другие характеристики.
  3. Приложение анализирует JSON, чтобы пользователь мог определить, какой контент или формат следует обновить.
  4. Приложение вызывает метод documents.batchUpdate для атомарного выполнения набора запросов на редактирование с целью обновления документа.
  5. Веб-сервер отправляет HTTP-ответ. Некоторые методы documents.batchUpdate предоставляют тело ответа с информацией о выполненных запросах, тогда как другие возвращают пустой ответ.

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