此页面由 Cloud Translation API 翻译。

文档

本指南介绍了一些概念，例如构成 Google 文档 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 Drive API，则 documentId 对应于 files 资源中的 id。

管理 Google 云端硬盘中的文档

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

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

使用 Google 文档文件

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

文档的 MIME 类型表示数据类型和格式。Google 文档的 MIME 类型格式为 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` 方法

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

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

文档创建工作流

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

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

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

文档更新工作流

更新现有文档要复杂一些。在进行有意义的调用以更新文档之前，您必须知道文档的当前状态：文档包含哪些元素、这些元素中包含哪些内容，以及文档中各元素的顺序。下图序列图展示了其工作原理：

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

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

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