使用 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 文档文档的结构概念指南。
文件更新工作流程
创建和填充新文档非常简单,因为无需担心现有内容,也没有协作者可以更改文档状态。从概念上讲,其工作原理如下所示:
更新现有文档的过程会更为复杂。在可以进行有意义的调用来更新文档之前,您需要知道文档的当前状态:它由哪些元素构成、这些元素中包含什么内容,以及所有这些项在文档中的位置。以下序列图显示了其工作原理:
此图没有考虑其他协作者在同一文档中进行并发更新的工作流。如需了解关于此主题的讨论,请参阅规划协作。