В этом руководстве представлены такие понятия, как основные методы, составляющие 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 пользователь, взаимодействующий с ресурсом documents
, имеет следующий поток информации:
- Приложение вызывает метод
documents.create
на веб-сервере. - Веб-сервер отправляет HTTP-ответ, содержащий экземпляр созданного документа в качестве ресурса
documents
. - При необходимости приложение вызывает метод
documents.batchUpdate
для атомарного выполнения набора запросов на редактирование для заполнения документа данными. - Веб-сервер отправляет HTTP-ответ. Некоторые методы
documents.batchUpdate
предоставляют тело ответа с информацией о примененных запросах, тогда как другие выдают пустой ответ.
Рабочий процесс обновления документа
Обновление существующего документа является более сложным. Прежде чем вы сможете совершать осмысленные вызовы для обновления документа, вы должны знать его текущее состояние: из каких элементов он состоит, какое содержимое находится в этих элементах и порядок элементов в документе. Следующая диаграмма последовательности показывает, как это работает:
На рисунке 2 пользователь, взаимодействующий с ресурсом documents
, имеет следующий поток информации:
- Приложение вызывает метод
documents.get
на веб-сервере, используяdocumentId
файла, который нужно найти. - Веб-сервер отправляет HTTP-ответ, содержащий экземпляр указанного документа в качестве ресурса
documents
. Возвращенный JSON содержит содержимое документа, форматирование и другие функции. - Приложение анализирует JSON, чтобы пользователь мог определить, какой контент или формат обновить.
- Приложение вызывает метод
documents.batchUpdate
для атомарного выполнения набора запросов на редактирование для обновления документа. - Веб-сервер отправляет HTTP-ответ. Некоторые методы
documents.batchUpdate
предоставляют тело ответа с информацией о примененных запросах, тогда как другие выдают пустой ответ.
На этой схеме не рассматриваются рабочие процессы, в которых другие соавторы одновременно вносят обновления в один и тот же документ. Дополнительные сведения см. в разделе «Рекомендации по планированию сотрудничества» .
похожие темы
- Структура документа Google Docs
- Запросы и ответы
- Правила и поведение структурного редактирования
- Лучшие практики для достижения наилучших результатов