请求和响应

本指南介绍了构成 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.batchUpdate 方法接受一个 request 对象列表，每个对象都指定要执行的单个请求。例如，设置段落格式，然后添加内嵌图片。每个请求都会在应用之前进行验证，并且请求会按照其在批量请求中的显示顺序进行处理。

批量更新中的所有请求均以原子方式应用。也就是说，如果任何请求无效，则整个更新都将失败，并且系统不会应用任何（可能依赖的）更改。

某些 documents.batchUpdate 方法会在响应中提供有关已应用请求的信息。这些方法会返回一个包含 response 对象列表的响应正文。其他请求无需返回信息，只需显示空回复即可。响应列表中的对象与相应请求具有相同的索引顺序。

一种常见的批量请求模式如下所示：

requests = []
requests.append(first request)
requests.append(second request)
...

body = ... & requests & ...

...batchUpdate(body)

如需详细了解如何批量处理文档 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

相关主题

• Google 文档的结构
• 结构编辑规则和行为
• 批量请求