Документ

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

Методы API

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

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

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

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

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

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

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

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

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

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

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

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

Работа с файлами Документов

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

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

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

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

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

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

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

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

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

Оператор Описание Использование
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 предоставляют тело ответа с информацией о примененных запросах, тогда как другие выдают пустой ответ.

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