培训
模块
通过使用批处理作业,可以避免在正常工作时间内降低计算机或服务器的速度。 您可以在财务和运营应用中将许多任务作为批处理作业的一部分运行。 例如,批处理作业可以包括有关打印报表、执行维护或发送电子文档的任务。
使用 JSON 批处理可将多个请求 (最多 20) 合并到单个 JSON 对象中来优化应用程序。
请考虑一个客户端,该客户端希望撰写以下不相关数据的视图:
将三个单独请求合并到一个单独的批处理请求中可以使应用程序不受重大网络延迟的影响。
Microsoft Graph 实现 $batch
OData URL 路径段 以支持 JSON 批处理。
首先,为示例方案构造 JSON 批处理请求。 在此方案中,各个请求不相互依赖,因此可以按任意顺序放入批处理请求中。
POST https://graph.microsoft.com/v1.0/$batch
Accept: application/json
Content-Type: application/json
{
"requests": [
{
"id": "1",
"method": "GET",
"url": "/me/drive/root:/{file}:/content"
},
{
"id": "2",
"method": "GET",
"url": "/me/planner/tasks"
},
{
"id": "3",
"method": "GET",
"url": "/groups/{id}/events"
},
{
"id": "4",
"url": "/me",
"method": "PATCH",
"body": {
"city" : "Redmond"
},
"headers": {
"Content-Type": "application/json"
}
},
{
"id": "5",
"url": "users?$select=id,displayName,userPrincipalName&$filter=city eq null&$count=true",
"method": "GET",
"headers": {
"ConsistencyLevel": "eventual"
}
}
]
}
批处理请求始终使用 POST 发送到 /$batch
终结点。
JSON 批处理请求正文由具有一个必需属性的单个 JSON 对象组成: 请求。 requests 属性是单个请求的集合。 对于每个单独的请求,可以传递以下属性。
属性 | 说明 |
---|---|
id | 必填。 字符串。 一个关联值,用于将单个响应与请求相关联。 此值允许服务器以最有效的顺序处理批处理中的请求。 不区分大小写。 在批处理中必须唯一。 |
方法 | 必需项。 HTTP 方法。 |
url | 必需项。 单个请求的相对资源 URL。 因此,尽管绝对 URL 为 https://graph.microsoft.com/v1.0/users ,但此 URL 为 /users 。 |
标头 | 可选,但在指定 正文 时是必填的。 具有标头的键/值对的 JSON 对象。 例如,当 需要 ConsistencyLevel 标头时,此属性表示为 "headers": {"ConsistencyLevel": "eventual"} 。 提供 正文 时,必须包含 Content-Type 标头。 |
body | 可选。 可以是 JSON 对象或 base64 URL 编码值,例如,当正文是图像时。 当请求中包含 正文 时,标头 对象必须包含 Content-Type 的值。 |
对批处理的请求的响应可能会以不同的顺序显示。 id 属性可用于关联各个请求和响应。
HTTP/1.1 200 OK
Content-Type: application/json
{
"responses": [
{
"id": "1",
"status": 302,
"headers": {
"location": "https://b0mpua-by3301.files.1drv.com/y23vmagahszhxzlcvhasdhasghasodfi"
}
},
{
"id": "3",
"status": 401,
"body": {
"error": {
"code": "Forbidden",
"message": "..."
}
}
},
{
"id": "5",
"status": 200,
"headers": {
"Cache-Control": "no-cache",
"x-ms-resource-unit": "1",
"OData-Version": "4.0",
"Content-Type": "application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8"
},
"body": {
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,userPrincipalName)",
"@odata.count": 12,
"value": [
{
"id": "071cc716-8147-4397-a5ba-b2105951cc0b",
"displayName": "Adele Vance",
"userPrincipalName": "AdeleV@Contoso.com"
}
]
}
},
{
"id": "2",
"status": 200,
"body": {
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.plannerTask)",
"value": []
}
},
{
"id": "4",
"status": 204,
"body": null
}
]
}
JSON 批处理请求的响应格式不同于请求格式,如下所示:
批处理响应中的状态代码通常为 200
或 400
。 如果批处理请求本身格式不正确,则状态代码为 400
。 如果批处理请求可解析,则状态代码为 200
。
200
批处理响应标头上的状态代码并不指示批处理中的单个请求已成功。 这就是 responses 属性中的每个单个响应都有状态代码的原因。
可以使用 dependsOn 属性指定要按指定顺序执行的批处理中的请求。 此属性是引用不同单个请求的 ID 的字符串数组。 例如,在以下请求中,客户端指定应按请求 1、请求 2、请求 4、请求 3 的顺序运行请求。
{
"requests": [
{
"id": "1",
"method": "GET",
"url": "..."
},
{
"id": "2",
"dependsOn": [ "1" ],
"method": "GET",
"url": "..."
},
{
"id": "4",
"dependsOn": [ "2" ],
"method": "GET",
"url": "..."
},
{
"id": "3",
"dependsOn": [ "4" ],
"method": "GET",
"url": "..."
}
]
}
如果单独请求失败,任何依赖此请求的请求都会失败,且状态代码为 424
(依赖项失败)。
提示
批处理应是完全有序的或完全并行的。
JSON 批处理的另一个用例是绕过 URL 长度限制。 如果 filter 子句很复杂,URL 长度可能会超过浏览器或其他 HTTP 客户端内置的限制。 可以使用 JSON 批处理作为运行这些请求的解决方法,因为冗长的 URL 只是请求有效负载的一部分。
429
为 。有关详细信息,请参阅 限制和批处理。
有关与批处理相关的当前限制列表,请参阅已知问题。
培训
模块
通过使用批处理作业,可以避免在正常工作时间内降低计算机或服务器的速度。 您可以在财务和运营应用中将许多任务作为批处理作业的一部分运行。 例如,批处理作业可以包括有关打印报表、执行维护或发送电子文档的任务。