本指南介绍了一些概念,例如构成 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 云端硬盘(我们的云端存储服务)中。虽然 Document API 有自己的独立方法,但通常还需要使用 Google Drive API 方法与用户的文档文件进行交互。例如,如需复制文档文件,请使用 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 类型搜索“我的云端硬盘”中的 Google 文档文件,请附加以下查询字符串过滤条件:
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 中,与 documents
资源互动的用户具有以下信息流:
- 应用调用 Web 服务器上的
documents.create
方法。 - 网络服务器发送一个 HTTP 响应,其中包含所创建文档的实例作为
documents
资源。 - (可选)应用调用
documents.batchUpdate
方法,以原子方式执行一组编辑请求,为文档填充数据。 - 网络服务器发送 HTTP 响应。有些
documents.batchUpdate
方法在响应正文中提供已应用请求的相关信息,而其他方法则显示空响应。
文档更新工作流
更新现有文档要复杂一些。在进行有意义的调用以更新文档之前,您必须知道文档的当前状态:文档包含哪些元素、这些元素中包含哪些内容,以及文档中各元素的顺序。以下序列图显示了工作原理:
在图 2 中,与 documents
资源互动的用户具有以下信息流:
- 应用在 Web 服务器上调用
documents.get
方法,并使用文件的documentId
进行查找。 - Web 服务器会发送一个 HTTP 响应,其中包含指定文档的实例作为
documents
资源。返回的 JSON 包含文档内容、格式设置和其他特征。 - 应用解析 JSON,以便用户确定要更新的内容或格式。
- 应用调用
documents.batchUpdate
方法,以原子方式执行一组编辑请求以更新文档。 - 网络服务器发送 HTTP 响应。有些
documents.batchUpdate
方法在响应正文中提供已应用请求的相关信息,而其他方法则显示空响应。
此图未考虑其他协作者在同一文档中进行并发更新的工作流。如需了解详情,请参阅最佳实践部分为协作做好规划。