Документ

В этом руководстве рассматриваются такие понятия, как основные методы, составляющие 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, а также данные, возвращаемые каждым из них:

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

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

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

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

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

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

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

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

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

Похожие темы

• Структура документа Google Docs
• Запросы и ответы
• Правила и поведение структурного редактирования
• Лучшие практики для достижения наилучших результатов