本文档介绍了如何对 API 调用进行批处理以减少客户端必须建立的连接数。批处理可以通过减少网络往返次数和增加吞吐量来提高应用的效率。
概览
客户端建立的每个连接都会产生一定的开销。 Google 幻灯片 API 支持批处理,让您的客户端可以将多个请求对象(每个对象指定要执行的单一类型请求)放入单个批处理请求中。批量请求可以将多个子请求合并到对服务器的单个调用中,然后检索单个响应,从而提高性能。
我们建议用户始终批量处理多个请求。以下是使用批处理的一些示例:
- 您刚开始使用该 API,需要上传大量数据。
- 您需要更新多个对象的元数据或属性,例如格式设置。
- 您需要删除许多对象。
限制、授权和依赖项注意事项
下面列出了采用批量更新时需要注意的其他事项:
- 每个批量请求(包括所有子请求)均计为一个 API 请求,计入您的用量限额。
- 一个批量请求需经过一次身份验证。这项身份验证适用于请求中的所有批量更新对象。
- 服务器会按照子请求在批量请求中出现的顺序来处理这些子请求。后面的子请求可以依赖于在较早的子请求期间执行的操作。例如,在同一批量请求中,用户可以将文本插入现有文档,然后设置其样式。
批量详情
批量请求包含一个 batchUpdate
方法调用和多个子请求,例如添加演示文稿和设置演示文稿格式。
每个请求都会经过验证,然后才能应用。批量更新中的所有子请求均以原子方式应用。也就是说,如果任何请求无效,则整个更新都会失败,并且不会应用任何(潜在相关的)更改。
一些请求会在响应中提供已应用请求的相关信息。例如,所有用于添加对象的批量更新请求都会返回响应,以便您可以访问新添加对象的元数据(例如 ID 或标题)。
通过这种方法,您可以使用一个包含多个子请求的 API 批量更新请求来构建整个 Google 文档。
批量请求的格式
“请求”是一个 JSON 请求,包含多个嵌套子请求,且具有一个必需属性:requests
。这些请求以单个请求数组的形式进行构建。每个请求都使用 JSON 来表示请求对象并包含其属性。
批量响应的格式
批量请求的 response 格式与请求格式类似。服务器的响应包含单个响应对象的完整回复。
主 JSON 对象的属性名为 replies
。这些响应以数组的形式返回,其中一个请求的每个响应与相应请求的索引顺序相同。某些请求没有响应,该数组索引处的响应为空。
示例
以下代码示例展示了如何使用 Slides API 进行批处理。
请求
此示例批量请求演示了如何执行以下操作:
使用
CreateSlideRequest
方法将presentations.pages
资源添加到现有演示文稿中,并将insertionIndex
设置为1
。使用
CreateShapeRequest
方法将类型为TEXT_BOX
的shapeType
添加到新幻灯片中。使用
InsertTextRequest
方法将“Hello World”文本插入新字段。
{ "requests":[ { "createSlide":{ "insertionIndex":1, "objectId":"newSlide" } }, { "createShape":{ "elementProperties":{ "pageObjectId":"newSlide", "size":{ "height":{ "magnitude":50, "unit":"PT" }, "width":{ "magnitude":200, "unit":"PT" } } }, "shapeType":"TEXT_BOX", "objectId":"newTextBox" } }, { "insertText":{ "objectId":"newTextBox", "text":"Hello World" } } ] }
响应
此示例批量响应显示有关如何应用批量请求中的每个子请求的信息。请注意,InsertTextRequest
方法不包含响应,因此位于 [2] 的数组的索引值由空花括号组成。批量请求会显示 WriteControl
属性,该属性会显示写入请求的执行方式。
{ "requiredRevisionId": ID "presentationId": "", "replies":[ { "createSlide":{ "objectId":"newSlide" } }, { "createShape":{ "objectId":"newTextBox" } }, { } ], "writeControl":{ "requiredRevisionId": REVISION_ID } }