简介

您可以使用 Google Docs 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 文档文档的结构概念指南。

文档更新工作流

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

更新现有文档更为复杂。您需要先了解文档的当前状态：哪些元素构成了该文档、这些元素中的内容是什么，以及所有这些项在文档中的位置，然后才能进行有意义的更新文档。以下序列图展示了其工作原理：

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