此页面由 Cloud Translation API 翻译。

文档

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

API 方法

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

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

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 对应于 files 资源中的 id。

管理 Google 云端硬盘中的文档

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

默认情况下，使用 Google 文档 API 时，新文档会保存到用户在 Google 云端硬盘上的根文件夹中。将文件保存到云端硬盘文件夹的选项如需了解详情，请参阅使用 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 文档字节内容，请使用云端硬盘的 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。
Web 服务器会发送 HTTP 响应，其中包含指定文档的实例作为 documents 资源。返回的 JSON 包含文档内容、格式和其他功能。
应用会解析 JSON，以便用户可以确定要更新的内容或格式。
应用会调用 documents.batchUpdate 方法，以原子方式执行一组修改请求以更新文档。
网络服务器发送 HTTP 响应。有些 documents.batchUpdate 方法会在响应正文中提供已应用请求的相关信息，而其他方法则会显示空响应。

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