本指南介绍了构成 Google 文档 API 的主要请求和响应方法,以及如何批量更新文档。
您可以使用 HTTP 请求调用 Google 文档 API,也可以在特定于语言的客户端库中使用方法调用来调用该 API。这些大致等同。
Google 文档 API 会返回 HTTP 响应,其中通常包含请求调用的结果。使用客户端库发出请求时,系统会以特定于语言的方式返回响应。
请求方法
Docs API 支持以下方法:
documents.create
:创建一个空白的 Google 文档。documents.get
:返回指定文档的完整实例。您可以解析返回的 JSON 以提取文档内容、格式设置和其他功能。documents.batchUpdate
:提交要原子地应用于文档的编辑请求列表,并返回结果列表。
documents.get
和 documents.batchUpdate
方法需要将 documentId
作为参数来指定目标文档。documents.create
方法会返回创建的文档的实例,您可以从中读取 documentId
。如需详细了解 documentId
,请参阅文档 ID。
请注意,您无法使用 documents.get
方法检索已发布的文档。发布后,公开文档将使用不同的网址格式。尝试使用网址的新 documentId
与 documents.get
方法搭配使用时,会返回 404
HTTP 状态代码响应。没有任何方法可以从已发布的网址检索原始 documentId
。如需解决此问题,您可以使用 Drive API 将已发布的文档复制到共享文档,然后改为访问此文件。如需了解详情,请参阅公开 Google 文档、表格、幻灯片和表单。
批量更新
documents.batchUpdate
方法接受一个 request
对象列表,每个对象都指定要执行的单个请求。例如,设置段落格式,然后添加内嵌图片。每个请求都会在应用之前进行验证,并且请求会按照其在批量请求中的显示顺序进行处理。
批量更新中的所有请求均以原子方式应用。也就是说,如果任何请求无效,则整个更新都将失败,并且系统不会应用任何(可能依赖的)更改。
某些 documents.batchUpdate
方法会在响应中提供有关已应用请求的信息。这些方法会返回一个包含 response
对象列表的响应正文。其他请求无需返回信息,只需显示空回复即可。响应列表中的对象与相应请求具有相同的索引顺序。
发出批量请求的常用模式如下所示:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
如需详细了解如何批量处理文档 API 调用,请参阅批量请求最佳实践;如需了解请求和响应类型,请参阅 documents.batchUpdate
参考文档。
批量更新操作
批量更新请求有多种类型。下面详细介绍了要求类型,并将其分为不同的类别。