文档

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

API 方法

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

• 使用 documents.create 方法创建文档。
• 使用 documents.get 方法检索指定文档的内容。
• 使用 documents.batchUpdate 方法以原子方式对指定文档执行一组更新。

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

文档 ID

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

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

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

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

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

管理 Google 云端硬盘中的文档

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

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

处理 Google 文档文件

如需从用户的“我的云端硬盘”中检索文档，通常需要先使用云端硬盘的 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 方法与 Docs 方法之间的区别，以及每种方法返回的数据：

文档创建工作流程

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

在图 1 中，用户与 documents 资源互动时，信息流如下：

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

文档更新工作流

更新现有文档则更为复杂。在有意义地调用来更新文档之前，您必须了解文档的当前状态：它由哪些元素组成、这些元素中包含哪些内容，以及元素在文档中的顺序。以下序列图展示了其工作原理：

在图 2 中，与 documents 资源互动的用户的信息流如下：

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

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

相关主题

• Google 文档的结构
• 请求和响应
• 结构化编辑规则和行为
• 有关取得最佳效果的最佳实践