Google Docs API 介绍

本文由 @西西爸de札记 翻译，更新时间：2020-02-06

https://developers.google.com/docs/api/how-tos/overview

介绍

The Google Docs API lets you create and modify documents.

Google Docs Api 可以让你创建和修改文档。

应用程序可以与 Google Docs Api 集成，从用户和系统提供的数据中创建完善的文档。API允许你执行以下任务：

• 自动化流程
• 批量创建
• 生成发票和合同

API 总览

documents 说明文档提供了用于调用 Google Docs Api 的方法。

API 方法

使用以下方法可以创建、读取和更新 Google Docs 文档：

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

get  和 batchUpdate 方法要求提供 Document ID 来作为参数，以便指定目标 。

create 方法返回一个被创建文档的实例 ，你可以从文档中获取到 Document ID

批量更新

batchUpdate  方法获取请求对象的列表，并根据这些请求在列表中出现的顺序进行更新。所有更新都是以原子方式执行的：如果批处理中的任何请求失败，则该批处理中的所有更新都不会应用于文档，然后文档保持不变。

batchUpdate 方法返回响应对象的列表。此列表中的对象与调用中提供的请求列表的比例为1:1

你可以并且应用 batchUpdate 在可能的情况下，将多个请求分组到一个调用中。这样可以节省配额并提高性能

查看 batchUpdate  有关请求和响应类型的详细信息，请参阅文档。

Document ID

文档由其ID引用。文档的ID可以从URL推导获取：

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

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

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

如果你熟悉 Google Drive 的 API 文档，这个 documentId 类比 File 资源的 ID

文档中的位置：indexes(索引)

对文档内容进行更新时，每次更新都发生在文档中的某个位置或某个范围内。使用索引指定这些位置和范围，索引表示包含文档段内的偏移量。要了解有关索引以及如何使用索引的更多信息，请参阅Structure of a Google Docs document 概念指南。

文档更新工作流

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

 

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