文档

本指南介绍了 Google 文档 API 的主要方法等概念、如何访问文档以及创建文档时的工作流。

API 方法

documents 资源 提供了一些方法，供您调用 Google 文档 API。您可以使用以下方法创建、读取和更新 Google 文档：

documents.get 和 documents.batchUpdate 方法需要 documentId 作为参数来指定目标文档。documents.create 方法会返回所创建文档的实例，您可以从中读取 documentId。如需详细了解 Google 文档 API 请求和 响应方法，请参阅请求和 响应。

文档 ID

documentId 是文档的唯一标识符，可以从文档的网址派生而来。它是一个包含字母、数字和一些特殊字符的特定字符串。即使文档名称发生更改，文档 ID 也会保持不变。

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

您可以使用以下正则表达式从 Google 文档网址中提取 documentId：

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

如果您熟悉 Google Drive API，则 documentId 对应于 id 资源中的 files。

管理 Google 云端硬盘中的文档

Google 文档文件存储在 Google 云端硬盘（我们的云端存储服务）中。虽然 Google 文档 API 有自己的独立方法，但通常还需要使用 Google Drive API 方法与用户的 Google 文档文件进行交互。例如，如需复制 Google 文档文件，请使用 Drive API 的 files.copy 方法。如需了解详情，请参阅复制现有 文档。

默认情况下，使用 Google 文档 API 时，新文档会保存到用户在云端硬盘上的根文件夹中。您可以选择将文件保存到云端硬盘文件夹中。如需了解详情，请参阅使用 Google 云端硬盘文件夹。

使用 Google 文档文件

如需从用户的“我的云端硬盘”中检索文档，通常 需要先使用 Drive 的 files.list 方法来 检索文件的 ID。调用该方法时不带任何参数，会返回用户的所有文件和文件夹的列表，包括 ID。

文档的 MIME 类型表示数据类型和格式。Google 文档的 MIME 类型格式为 application/vnd.google-apps.document。如需查看 MIME 类型列表，请参阅 Google Workspace 和 Google 云端硬盘支持的 MIME 类型。

如需仅按 MIME 类型搜索“我的云端硬盘”中的 Google 文档文件，请添加以下查询字符串过滤条件：

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

如需详细了解查询字符串过滤条件，请参阅搜索文件和 文件夹。

知道 documentId 后，您可以使用 documents.get 方法 检索指定文档的完整实例。如需了解详情， 请参阅请求和响应。

如需导出 Google Workspace 文档字节内容，请使用 Drive 的 files.export 方法，并提供要导出的文件的 documentId 和正确的 导出 MIME 类型。如需了解详情，请参阅 导出 Google Workspace 文档内容。

比较 Get 和 List 方法

下表介绍了 Drive 和 Google 文档方法之间的区别，以及每种方法返回的数据：

运算符 说明 用法
drive.files.get 按 ID 获取文件的元数据。返回 files 资源的实例。 获取特定文件的元数据。
drive.files.list 获取用户的文件。返回文件列表。 当您不确定必须修改哪个文件时，获取用户文件列表。
docs.documents.get 获取指定文档的最新版本，包括所有格式和文本。返回 documents 资源的实例。 获取具有特定文档 ID 的文档。

文档创建工作流

创建和填充新文档非常简单，因为无需担心现有内容，也没有协作者可以更改文档状态。从概念上讲，此过程的工作原理如下图所示：

创建和填充新文档的工作流。
图 1.创建和填充新文档的工作流。

在图 1 中，与 documents 资源交互的用户具有以下信息流：

  1. 应用在 Web 服务器上调用 documents.create 方法。
  2. Web 服务器发送 HTTP 响应，其中包含所创建文档的实例作为 documents 资源。
  3. （可选）应用调用 documents.batchUpdate 方法，以原子性地执行一组修改请求，从而使用数据填充文档 。
  4. Web 服务器发送 HTTP 响应。某些 documents.batchUpdate 方法会提供包含有关已应用请求的信息的响应正文，而其他方法则会显示空响应。

文档更新工作流

更新现有文档比较复杂。在进行有意义的调用来更新文档之前，您必须了解文档的当前状态：构成文档的元素、这些元素中的内容以及文档中元素的顺序。下图展示了其工作原理：

用于更新文档的工作流。
图 2.更新文档的工作流。

在图 2 中，与 documents 资源交互的用户具有以下信息流：

  1. 应用在 Web 服务器上调用 documents.get 方法，并提供要查找文件的 documentId。
  2. Web 服务器发送 HTTP 响应，其中包含指定文档的实例作为 documents 资源。返回的 JSON 包含文档内容、格式和其他功能。
  3. 应用解析 JSON，以便用户确定要更新的内容或格式。
  4. 应用调用 documents.batchUpdate 方法，以原子性地执行一组修改请求，从而更新文档。
  5. Web 服务器发送 HTTP 响应。某些 documents.batchUpdate 方法会提供包含有关已应用请求的信息的响应正文，而其他方法则会显示空响应。

此图未考虑其他协作者在同一文档中进行并发更新的工作流。如需了解详情，请参阅最佳 实践部分中的规划 协作。