文档

本指南介绍了一些概念，例如构成 Google 文档 API、如何访问文档，以及创建 文档。

API 方法

documents 资源提供了 方法。通过以下方法 创建、阅读和更新 Google 文档文档：

documents.get 和 documents.batchUpdate 方法需要 documentId 以指定目标文档。documents.create 方法 返回所创建文档的实例，您可以从中读取 documentId。有关 Google 文档 API 请求和 请参阅请求和 响应。

文档 ID

documentId 是文档的唯一标识符，可以派生 。它是一个包含字母、数字和 一些特殊字符。文档 ID 是稳定的，即使文档名称也是如此 更改。

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

以下正则表达式可用于从documentId Google 文档网址：

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

如果您熟悉 Google Drive API，就会发现 documentId 对应于 id （位于 files 资源中）。

管理 Google 云端硬盘中的文档

Google 文档文件存储在 Google 云端硬盘（我们的云端存储空间）中 服务。虽然文档 API 有自己的独立方法， 也有必要使用 Google Drive API 方法与用户的 文档文件。例如，要复制 Google 文档文件，请使用 Drive API 的 files.copy 方法。有关详情，请参阅复制现有 文档。

默认情况下，使用 Google 文档 API 时，新文档会保存到 用户的根文件夹。有多个用于保存文件的选项 到云端硬盘文件夹中。有关详情，请参阅适用于 Google 云端硬盘文件夹。

使用 Google 文档文件

如要从用户的“我的云端硬盘”中检索文档， 首次使用云端硬盘的 files.list 方法检索 文件的 ID。调用不带任何参数的方法时，系统将返回 所有文件和文件夹，包括 ID。

文档的 MIME 类型表示数据类型和格式。MIME 类型格式 适用于 Google 文档的价格是 application/vnd.google-apps.document。有关 MIME 类型，请参阅 Google Workspace 和 Google 云端硬盘支持的 MIME 类型。

要按 MIME 类型搜索“我的” 云端硬盘，请附加以下查询字符串过滤条件：

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

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

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

如要导出 Google Workspace 文档字节内容，请使用云端硬盘的 files.export 方法， 要导出的文件的 documentId 以及正确的导出 MIME 类型。有关详情，请参阅导出 Google Workspace 文档 内容。

比较 Get 和 List 方法

下表介绍了云端硬盘之间的区别 和 Google 文档方法，以及使用每种方法返回的数据：

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

文档创建工作流

创建和填充新文档非常简单 而没有协作者可以更改 文档状态。从概念上讲，其工作原理如下 图表：

用于创建和 填充一个新文档。
图 1. 创建和填充新文档的工作流程。

在图 1 中，用户与 documents 资源具有以下特征 信息流：

  1. 应用调用 documents.create 方法已开启 Web 服务器。
  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 方法 在响应正文中提供关于已应用请求的信息，而 其他进程则显示空响应。

此图未考虑由其他组织进行并发更新的工作流 在同一文档中建立协作者。如需了解更多信息，请查看最佳 做法部分为 协作。