Документ

This guide introduces concepts such as the primary methods that make up the Google Docs API, how to access a document, and the workflow when creating a document.

Методы API

The documents resource provides methods you use to invoke the Docs API. The following methods let you create, read, and update Docs documents:

  • Use the documents.create method to create a document.
  • Используйте метод 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

The following regular expression can be used to extract the documentId from a Google Docs URL:

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

If you're familiar with the Google Drive API, the documentId corresponds to id in the files resource.

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

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

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

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

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

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

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

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

Для получения дополнительной информации о фильтрах параметров запроса см. раздел «Поиск файлов и папок» .

Получив идентификатор documentId , используйте метод documents.get для получения полного экземпляра указанного документа. Дополнительную информацию см. в разделе «Запросы и ответы» .

Для экспорта содержимого документа Google Workspace в байтах используйте метод files.export в Google Drive, указав 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 предоставляют тело ответа с информацией об обработанных запросах, в то время как другие выдают пустой ответ.

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