简介

使用 Google 文档 API，您可以创建和修改文档。

应用可以与 Docs API 集成，以利用用户和系统提供的数据创建精致的文档。借助该 API，您可以：

• 自动执行流程
• 批量创建文档
• 生成账单或合同

API 简介

documents 资源提供了用于调用 Docs API 的方法。

API 方法

以下方法可让您创建、读取和更新 Google 文档文档：

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

get 和 batchUpdate 方法需要使用 documentId（见下文）作为参数，以指定目标文档。create 方法会返回所创建文档的实例，您可以从中读取 ID。

批量更新

batchUpdate 方法接受请求对象列表，并根据它们在批量请求中出现的相同顺序进行更新。批量更新中的更新以原子方式应用。也就是说，如果任何请求无效，则整个更新都会失败，且不会应用任何（可能相关的）更改。

batchUpdate 方法会返回响应对象的列表。此列表中的对象具有与相应请求相同的索引顺序。

如需了解如何一起批量处理 API 调用，请参阅批量请求最佳做法，以及有关请求和响应类型的 batchUpdate 参考文档。

文档 ID

文档 ID 会引用文档，可以通过以下网址推导得出：

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

documentId 是一个包含字母、数字和一些特殊字符的唯一字符串。以下正则表达式可用于从 Google 文档网址中提取文档 ID：

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

如果您熟悉 Google Drive API，您会发现 documentId 与 File 资源的 ID 相对应。

文档中的位置：索引

当您对文档的内容进行更新时，每次更新都发生在文档中的某个位置或某个范围内。这些位置和范围使用索引指定，索引表示包含的文档段内的偏移量。如需详细了解索引及其使用方法，请参阅 Google 文档文档的结构概念指南。

文件更新工作流程

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

更新现有文档的过程会更为复杂。在可以进行有意义的调用来更新文档之前，您需要知道文档的当前状态：它由哪些元素构成、这些元素中包含什么内容，以及所有这些项在文档中的位置。以下序列图显示了其工作原理：

此图没有考虑其他协作者在同一文档中进行并发更新的工作流。如需了解关于此主题的讨论，请参阅规划协作。