请求和响应

本指南介绍了构成 Google Docs API 的主要请求和响应方法,以及如何批量更新文档。

您可以使用 HTTP 请求调用 Google Docs API,也可以通过特定于语言的客户端库中的方法调用来调用该 API。这两者大致相当。

Google Docs API 会返回 HTTP 响应,其中通常包含请求调用的结果。使用客户端库发出请求时,系统会以特定语言返回响应。

请求方法

Docs API 支持以下方法:

  • documents.create:创建空白 Google 文档。

  • documents.get: 返回指定文档的完整实例。您可以解析返回的 JSON,以提取文档内容、格式和其他功能。

  • documents.batchUpdate: 提交一系列编辑请求,以原子方式应用于文档,并返回结果列表。

documents.getdocuments.batchUpdate 方法需要将 documentId 作为参数来指定目标文档。documents.create 方法会返回所创建文档的实例,您可以从中读取 documentId。如需详细了解 documentId,请参阅文档 ID

请注意,您无法使用 documents.get 方法检索已发布的文档。发布后,公开文档会使用不同的网址格式。尝试使用网址的新 documentIddocuments.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)

如需详细了解如何批量处理 Docs API 调用,以及请求和响应类型的 documents.batchUpdate 参考文档,请参阅批量请求最佳实践

批量更新操作

批量更新请求有多种类型。以下是请求类型的细分,按不同类别分组。

对象 添加 / 插入 更新 / 替换 删除
文本 InsertTextRequest ReplaceAllTextRequest
样式 CreateParagraphBulletsRequest UpdateTextStyleRequest
UpdateParagraphStyleRequest
UpdateTableCellStyleRequest
UpdateTableRowStyleRequest
UpdateDocumentStyleRequest
UpdateSectionStyleRequest
DeleteParagraphBulletsRequest
命名范围 CreateNamedRangeRequest ReplaceNamedRangeContentRequest DeleteNamedRangeRequest
DeleteContentRangeRequest
图片 InsertInlineImageRequest ReplaceImageRequest
InsertTableRequest
InsertTableRowRequest
InsertTableColumnRequest
UpdateTableColumnPropertiesRequest
MergeTableCellsRequest
UnmergeTableCellsRequest
PinTableHeaderRowsRequest
DeleteTableRowRequest
DeleteTableColumnRequest
页面对象(包括页眉页脚 InsertPageBreakRequest
CreateHeaderRequest
CreateFooterRequest
CreateFootnoteRequest
InsertSectionBreakRequest
DeletePositionedObjectRequest
DeleteHeaderRequest
DeleteFooterRequest