本指南介绍了一些概念,例如构成 Google 文档 API、如何访问文档,以及创建 文档。
API 方法
documents
资源提供了
方法。通过以下方法
创建、阅读和更新 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
以下正则表达式可用于从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 中,用户与
documents
资源具有以下特征
信息流:
- 应用调用
documents.create
方法已开启 Web 服务器。 - 网络服务器发送 HTTP 响应,其中包含
已将文档创建为
documents
资源。 - (可选)应用调用
documents.batchUpdate
以原子方式执行一组编辑请求来填充文档的方法 数据。 - 网络服务器发送 HTTP 响应。某些
documents.batchUpdate
方法 在响应正文中提供关于已应用请求的信息,而 其他进程则显示空响应。
文档更新工作流
更新现有文档要复杂一些。做出有意义的 调用来更新文档时,您必须知道其当前状态: 这些元素包含哪些内容 文档。以下序列图显示了工作原理:
在图 2 中,与 documents
资源互动的用户获得
信息流:
- 应用调用
documents.get
方法(网页版) 服务器,包含要查找的文件的documentId
。 - 网络服务器发送 HTTP 响应,其中包含
指定为
documents
资源的文档。返回的 JSON 包含 文档内容、格式和其他功能。 - 应用解析 JSON,以便用户确定需要什么内容或格式 更新。
- 应用调用
documents.batchUpdate
方法来以原子方式执行一组 来更新文档。 - 网络服务器发送 HTTP 响应。某些
documents.batchUpdate
方法 在响应正文中提供关于已应用请求的信息,而 其他进程则显示空响应。
此图未考虑由其他组织进行并发更新的工作流 在同一文档中建立协作者。如需了解更多信息,请查看最佳 做法部分为 协作。