简介

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

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

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

API 简介

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

API 方法

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

getbatchUpdate 方法需要使用 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,您会发现 documentIdFile 资源的 ID 相对应。

文档中的位置:索引

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

文件更新工作流程

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

创建和填充新文档的工作流程。

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

更新文档的工作流。

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