批处理 是一种将多个请求合并到单个 HTTP 请求中的方法。 请求组合在单个 JSON 有效负载中,该负载通过 POST 发送到 \$batch 终结点。 Microsoft Graph SDK 具有一组类,用于简化如何创建批处理有效负载和分析批处理响应有效负载。
Important: 有关 Microsoft Graph JSON 批处理的当前限制,请参阅已知问题。
创建批处理请求
Microsoft Graph SDK 提供了三个类,用于处理批处理请求和响应。
- BatchRequestStep - 表示单个请求 (,)
GET /me批处理中的请求。 它支持为请求分配唯一标识符并指定请求之间的依赖关系。 - BatchRequestContent - 简化批处理请求有效负载的创建。 它包含多个 BatchRequestStep 对象。
- BatchResponseContent - 简化了分析来自批处理请求的响应。 它提供获取所有响应、按 ID 获取特定响应以及获取
@odata.nextLink属性(如果存在)的能力。
简单批处理示例
此示例演示如何在一个批处理中发送多个不彼此依赖的请求。 服务可以按任意顺序运行请求。 此示例获取用户并获取当前日期的用户日历视图。
C#
// Use the request builder to generate a regular
// request to /me
var userRequest = graphClient.Me.Request();
var today = DateTime.Now.Date;
var start = today.ToString("yyyy-MM-ddTHH:mm:ssK");
var end = today.AddDays(1).ToString("yyyy-MM-ddTHH:mm:ssK");
var queryOptions = new List<QueryOption>
{
new QueryOption("startDateTime", start),
new QueryOption("endDateTime", end)
};
// Use the request builder to generate a regular
// request to /me/calendarview?startDateTime="start"&endDateTime="end"
var eventsRequest = graphClient.Me.CalendarView.Request(queryOptions);
// Build the batch
var batchRequestContent = new BatchRequestContent();
// Using AddBatchRequestStep adds each request as a step
// with no specified order of execution
var userRequestId = batchRequestContent.AddBatchRequestStep(userRequest);
var eventsRequestId = batchRequestContent.AddBatchRequestStep(eventsRequest);
var returnedResponse = await graphClient.Batch.Request().PostAsync(batchRequestContent);
// De-serialize response based on known return type
try
{
var user = await returnedResponse
.GetResponseByIdAsync<User>(userRequestId);
Console.WriteLine($"Hello {user.DisplayName}!");
}
catch (ServiceException ex)
{
Console.WriteLine($"Get user failed: {ex.Error.Message}");
}
// For collections, must use the *CollectionResponse class to deserialize
// The .Value property will contain the *CollectionPage type that the Graph client
// returns from GetAsync().
try
{
var events = await returnedResponse
.GetResponseByIdAsync<UserCalendarViewCollectionResponse>(eventsRequestId);
Console.WriteLine($"You have {events.Value.CurrentPage.Count} events on your calendar today.");
}
catch (ServiceException ex)
{
Console.WriteLine($"Get calendar view failed: {ex.Error.Message}");
}
TypeScript
// Create a batch request step to GET /me
let userRequestStep: MicrosoftGraph.BatchRequestStep = {
id: "1",
request: new Request("/me", {
method: "GET"
})
}
let today = moment({hour: 0, minute: 0, seconds: 0});
let start = today.format();
let end = today.add(1, "day").format();
// Create a batch request step to GET
// /me/calendarview?startDateTime="start"&endDateTime="end"
let calendarViewRequestStep: MicrosoftGraph.BatchRequestStep = {
id: "2",
request: new Request(`/me/calendarview?startDateTime=${start}&endDateTime=${end}`, {
method: "GET"
})
}
// Create the batch request content with the steps created
// above
let batchRequestContent = new MicrosoftGraph.BatchRequestContent([
userRequestStep,
calendarViewRequestStep
]);
let content = await batchRequestContent.getContent();
// POST the batch request content to the /$batch endpoint
let batchResponse = await client
.api('/$batch')
.post(content);
// Create a BatchResponseContent object to parse the response
let batchResponseContent = new MicrosoftGraph.BatchResponseContent(batchResponse);
// Get the user response using the id assigned to the request
let userResponse = batchResponseContent.getResponseById("1");
// For a single entity, the JSON payload can be deserialized
// into the expected type
// Types supplied by @microsoft/microsoft-graph-types
if (userResponse.ok) {
let user: User = await userResponse.json();
console.log(`Hello ${user.displayName}!`);
} else {
console.log(`Get user failed with status ${userResponse.status}`);
}
// Get the calendar view response by id
let calendarResponse = batchResponseContent.getResponseById("2");
// For a collection of entities, the "value" property of
// the JSON payload can be deserialized into an array of
// the expected type
if (calendarResponse.ok) {
let rawResponse = await calendarResponse.json();
let events: [Event] = rawResponse.value;
console.log(`You have ${events.length} events on your calendar today.`);
} else {
console.log(`Get calendar view failed with status ${calendarResponse.status}`);
}
Java
// Create the batch request content with the steps
final BatchRequestContent batchRequestContent = new BatchRequestContent();
// Use the Graph client to generate the request for GET /me
final String meGetId = batchRequestContent
.addBatchRequestStep(graphClient
.me()
.buildRequest());
final ZoneOffset localTimeZone = OffsetDateTime.now().getOffset();
final OffsetDateTime today = OffsetDateTime.of(LocalDate.now(), LocalTime.MIDNIGHT, localTimeZone);
final OffsetDateTime tomorrow = today.plusDays(1);
// Use the Graph client to generate the request URL for
// GET /me/calendarview?startDateTime="start"&endDateTime="end"
final List<Option> calendarViewOptions = Arrays.asList(new QueryOption("startDateTime", today.toString()),
new QueryOption("endDateTime", tomorrow.toString()));
final String calendarViewRequestStepId = batchRequestContent
.addBatchRequestStep(graphClient
.me()
.calendarView()
.buildRequest(calendarViewOptions));
// Send the batch request content to the /$batch endpoint
final BatchResponseContent batchResponseContent = graphClient.batch().buildRequest().post(batchRequestContent);
// Get the user response using the id assigned to the request
final User user = batchResponseContent.getResponseById(meGetId).getDeserializedBody(User.class);
System.out.println(String.format("Hello %s!", user.displayName));
// Get the calendar view response by id
final EventCollectionResponse events = batchResponseContent.getResponseById(calendarViewRequestStepId).getDeserializedBody(EventCollectionResponse.class);
System.out.println(String.format("You have %d events on your calendar today", events.value.size()));
具有相关请求的批处理
此示例演示如何在批处理中发送多个相互依赖的请求。 请求将按依赖项指定的顺序由服务运行。 本示例向用户的日历添加一个事件,其开始时间为当前日期,并获取当前日期的用户日历视图。 若要确保返回的日历审阅包含创建的新事件,日历视图的请求将配置为依赖于添加新事件的请求。 这将确保首先执行添加事件请求。
Note: 如果添加事件请求失败,则获取日历视图请求将失败并出现错误
424 Failed Dependency。
C#
var today = DateTime.Now.Date;
var newEvent = new Event
{
Subject = "File end-of-day report",
Start = new DateTimeTimeZone
{
// 5:00 PM
DateTime = today.AddHours(17).ToString("yyyy-MM-ddTHH:mm:ss"),
TimeZone = TimeZoneInfo.Local.StandardName
},
End = new DateTimeTimeZone
{
// 5:30 PM
DateTime = today.AddHours(17).AddMinutes(30).ToString("yyyy-MM-ddTHH:mm:ss"),
TimeZone = TimeZoneInfo.Local.StandardName
}
};
// POST requests are handled a bit differently
// The SDK request builders generate GET requests, so
// you must get the HttpRequestMessage and convert to a POST
var jsonEvent = graphClient.HttpProvider.Serializer.SerializeAsJsonContent(newEvent);
var addEventRequest = graphClient.Me.Events.Request().GetHttpRequestMessage();
addEventRequest.Method = HttpMethod.Post;
addEventRequest.Content = jsonEvent;
var start = today.ToString("yyyy-MM-ddTHH:mm:ssK");
var end = today.AddDays(1).ToString("yyyy-MM-ddTHH:mm:ssK");
var queryOptions = new List<QueryOption>
{
new QueryOption("startDateTime", start),
new QueryOption("endDateTime", end)
};
// Use the request builder to generate a regular
// request to /me/calendarview?startDateTime="start"&endDateTime="end"
var calendarViewRequest = graphClient.Me.CalendarView.Request(queryOptions);
// Build the batch
var batchRequestContent = new BatchRequestContent();
// Force the requests to execute in order, so that the request for
// today's events will include the new event created.
// First request, no dependency
var addEventRequestId = batchRequestContent.AddBatchRequestStep(addEventRequest);
// Second request, depends on addEventRequestId
var eventsRequestId = Guid.NewGuid().ToString();
batchRequestContent.AddBatchRequestStep(new BatchRequestStep(
eventsRequestId,
calendarViewRequest.GetHttpRequestMessage(),
new List<string> { addEventRequestId }
));
var returnedResponse = await graphClient.Batch.Request().PostAsync(batchRequestContent);
// De-serialize response based on known return type
try
{
var createdEvent = await returnedResponse
.GetResponseByIdAsync<Event>(addEventRequestId);
Console.WriteLine($"New event created with ID: {createdEvent.Id}");
}
catch (ServiceException ex)
{
Console.WriteLine($"Add event failed: {ex.Error.Message}");
}
// For collections, must use the *CollectionResponse class to deserialize
// The .Value property will contain the *CollectionPage type that the Graph client
// returns from GetAsync().
try
{
var events = await returnedResponse
.GetResponseByIdAsync<UserCalendarViewCollectionResponse>(eventsRequestId);
Console.WriteLine($"You have {events.Value.CurrentPage.Count} events on your calendar today.");
}
catch (ServiceException ex)
{
Console.WriteLine($"Get calendar view failed: {ex.Error.Message}");
}
TypeScript
// 5:00 PM
let eventStart = moment({hour: 17, minute: 0, seconds: 0});
// Create a batch request step to add an event
let newEvent: Event = {
subject: "File end-of-day report",
start: {
dateTime: eventStart
.format("YYYY-MM-DDTHH:mm:ss"),
timeZone: moment.tz.guess()
},
end: {
// 5:30 PM
dateTime: eventStart.add(30, "minutes")
.format("YYYY-MM-DDTHH:mm:ss"),
timeZone: moment.tz.guess()
}
}
console.log(JSON.stringify(newEvent));
let addEventRequestStep: MicrosoftGraph.BatchRequestStep = {
id: "1",
request: new Request("/me/events", {
method: "POST",
body: JSON.stringify(newEvent),
headers: {
"Content-Type": "application/json"
}
})
}
let today = moment({hour: 0, minute: 0, seconds: 0});
let start = today.format();
let end = today.add(1, "day").format();
console.log(`/me/calendarview?startDateTime=${start}&endDateTime=${end}`);
// Create a batch request step to GET
// /me/calendarview?startDateTime="start"&endDateTime="end"
let calendarViewRequestStep: MicrosoftGraph.BatchRequestStep = {
id: "2",
// This step will happen after step 1
dependsOn: [ "1" ],
request: new Request(`/me/calendarview?startDateTime=${start}&endDateTime=${end}`, {
method: "GET"
})
}
// Create the batch request content with the steps created
// above
let batchRequestContent = new MicrosoftGraph.BatchRequestContent([
addEventRequestStep,
calendarViewRequestStep
]);
let content = await batchRequestContent.getContent();
// POST the batch request content to the /$batch endpoint
let batchResponse = await client
.api('/$batch')
.post(content);
// Create a BatchResponseContent object to parse the response
let batchResponseContent = new MicrosoftGraph.BatchResponseContent(batchResponse);
// Get the create event response by id
let newEventResponse = batchResponseContent.getResponseById("1");
if (newEventResponse.ok) {
let event: Event = await newEventResponse.json();
console.log(`New event created with ID: ${event.id}`);
} else {
console.log(`Create event failed with status ${newEventResponse.status}`);
}
// Get the calendar view response by id
let calendarResponse = batchResponseContent.getResponseById("2");
if (calendarResponse.ok)
{
// For a collection of entities, the "value" property of
// the JSON payload can be deserialized into an array of
// the expected type
let rawResponse = await calendarResponse.json();
let events: [Event] = rawResponse.value;
console.log(`You have ${events.length} events on your calendar today.`);
} else {
console.log(`Get calendar view failed with status ${calendarResponse.status}`);
}
Java
// Create the batch request content with the steps
final BatchRequestContent batchRequestContent = new BatchRequestContent(batchSteps);
final ZoneOffset localTimeZone = OffsetDateTime.now().getOffset();
final OffsetDateTime today = OffsetDateTime.of(LocalDate.now(), LocalTime.MIDNIGHT, localTimeZone);
final OffsetDateTime tomorrow = today.plusDays(1);
// Use the Graph client to generate the request URL for POST /me/events
final Event newEvent = new Event();
newEvent.subject = "File end-of-day report";
newEvent.start = new DateTimeTimeZone();
// 5:00 PM
newEvent.start.dateTime = today.plusHours(17)
.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
newEvent.start.timeZone = ZoneOffset.systemDefault().getId();
newEvent.end = new DateTimeTimeZone();
// 5:30 PM
newEvent.end.dateTime = today.plusHours(17).plusMinutes(30)
.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
newEvent.end.timeZone = ZoneOffset.systemDefault().getId();
final String addEventRequestId = batchRequestContent
.addBatchRequestStep(graphClient
.me()
.events()
.buildRequest(), HttpMethod.POST, newEvent);
// Use the Graph client to generate the request URL for
// GET /me/calendarview?startDateTime="start"&endDateTime="end"
final List<Option> calendarViewOptions = Arrays.asList(new QueryOption("startDateTime", today.toString()),
new QueryOption("endDateTime", tomorrow.toString()));
final String calendarViewRequestStepId = batchRequestContent
.addBatchRequestStep(graphClient
.me()
.calendarView()
.buildRequest(calendarViewOptions),
HttpMethod.GET,
null,
addEventRequestId);
// Send the batch request content to the /$batch endpoint
final BatchResponseContent batchResponseContent = client.batch().buildRequest().post(batchRequestContent);
// Get the user response using the id assigned to the request
final Event event = batchResponseContent.getResponseById(addEventRequestId).getDeserializedBody(Event.class);
System.out.println(String.format("New event created with ID: %s", event.id));
// Get the calendar view response by id
final EventCollectionResponse events = batchResponseContent.getResponseById(calendarViewRequestStepId).getDeserializedBody(EventCollectionResponse.class);
System.out.println(String.format("You have %d events on your calendar today", events.value.size()));
使用 BatchRequestContent、BatchRequestStep 和 HttpRequestMessage 实现批处理
以下示例演示如何使用 、 和 在批处理中发送多个请求,以及如何使用 Microsoft Graph API 请求处理 BatchRequestContent BatchRequestStep HttpRequestMessage 20 的限制。 此示例使用指定用户 ID 的 onlineMeetings/createOrGet 终结点创建会议链接。 也可以将此示例与其他 Microsoft Graph终结点一同使用。
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Microsoft.Graph;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
public async void GenerateBatchedMeetingLink(List<ItemCollections> meetingLinksToBeGenerated)
{
List<string> _joinWebUrls = new List<string>();
//Total number of items per batch supported is 20
int maxNoBatchItems = 20;
try
{
//valid GraphAccessToken is required to execute the call
var graphClient = GetAuthenticatedClient(GraphAccessToken);
var events = new List<OnlineMeetingCreateOrGetRequestBody>();
foreach (var item in meetingLinksToBeGenerated)
{
var externalId = Guid.NewGuid().ToString();
var @event = new OnlineMeetingCreateOrGetRequestBody
{
StartDateTime = item.StartTime,
EndDateTime = item.EndTime,
Subject = "Test Meeting",
ExternalId = externalId,
};
events.Add(@event);
}
// if the requests are more than 20 limit, we need to create multiple batches of the BatchRequestContent
List<BatchRequestContent> batches = new List<BatchRequestContent>();
var batchRequestContent = new BatchRequestContent();
foreach (OnlineMeetingCreateOrGetRequestBody e in events)
{
//create online meeting for particular user or we can use /me as well
var httpRequestMessage = new HttpRequestMessage(HttpMethod.Post, $"https://graph.microsoft.com/v1.0/users/{userID}/onlineMeetings/createOrGet")
{
Content = new StringContent(JsonConvert.SerializeObject(e), Encoding.UTF8, "application/json")
};
BatchRequestStep requestStep = new BatchRequestStep(events.IndexOf(e).ToString(), httpRequestMessage, null);
batchRequestContent.AddBatchRequestStep(requestStep);
if (events.IndexOf(e) > 0 && ((events.IndexOf(e) + 1) % maxNoBatchItems == 0))
{
batches.Add(batchRequestContent);
batchRequestContent = new BatchRequestContent();
}
}
if (batchRequestContent.BatchRequestSteps.Count < maxNoBatchItems)
{
batches.Add(batchRequestContent);
}
if (batches.Count == 0 && batchRequestContent != null)
{
batches.Add(batchRequestContent);
}
foreach (BatchRequestContent batch in batches)
{
BatchResponseContent response = null;
response = await graphClient.Batch.Request().PostAsync(batch);
Dictionary<string, HttpResponseMessage> responses = await response.GetResponsesAsync();
foreach (string key in responses.Keys)
{
HttpResponseMessage httpResponse = await response.GetResponseByIdAsync(key);
var responseContent = await httpResponse.Content.ReadAsStringAsync();
JObject eventResponse = JObject.Parse(responseContent);
//do something below
Console.writeline(eventResponse["joinWebUrl"].ToString());
}
}
}
catch (Exception ex)
{
Console.Writeline(ex.Message + ex.StackTrace);
}
}
历史资料。此文对应 2023-02-03 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 DarrelMiller)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
