通过

使用 Microsoft Graph SDK 对请求进行批处理

  • 项目

批处理 是一种将多个请求合并为单个 HTTP 请求的方法。 请求合并到单个 JSON 有效负载中，该有效负载通过 POST 发送到 \$batch 终结点。 Microsoft Graph SDK 具有一组类来简化创建批处理有效负载和分析批处理响应有效负载的方式。

重要

有关 Microsoft Graph 中 JSON 批处理的当前限制，请参阅 已知问题。

创建批处理请求

Microsoft Graph SDK 提供三个类来处理批处理请求和响应。

  • BatchRequestStep - 表示单个请求 (，例如 GET /me 批处理中的) 。 它允许向请求分配唯一标识符，并指定请求之间的依赖关系。
  • BatchRequestContent - 简化了批处理请求有效负载的创建。 它包含多个 BatchRequestStep 对象。
  • BatchResponseContent - 简化了分析来自批处理请求的响应。 它使你能够获取所有响应、按 ID 获取特定响应以及获取 @odata.nextLink 属性（如果存在）。

请求限制的自动批处理

Microsoft Graph SDK 自动处理批处理请求，限制为每个批 20 个请求。 这意味着，如果代码超过此限制，SDK 会将请求拆分为后台的单独批处理。 这可确保每个批都符合限制。 不再需要手动实现逻辑来处理此批处理限制，从而使代码更简洁且更易于管理。

简单批处理示例

此示例演示如何在一个批中发送多个彼此不依赖的请求。 服务可以按任何顺序运行请求。 此示例获取用户并获取当前日期的用户日历视图。

// Use the request builder to generate a regular
// request to /me
var userRequest = graphClient.Me.ToGetRequestInformation();

var today = DateTime.Now.Date;

// Use the request builder to generate a regular
// request to /me/calendarview?startDateTime="start"&endDateTime="end"
var eventsRequest = graphClient.Me.CalendarView
    .ToGetRequestInformation(requestConfiguration =>
        {
            requestConfiguration.QueryParameters.StartDateTime =
                today.ToString("yyyy-MM-ddTHH:mm:ssK");
            requestConfiguration.QueryParameters.EndDateTime =
                today.AddDays(1).ToString("yyyy-MM-ddTHH:mm:ssK");
        });

// Build the batch
var batchRequestContent = new BatchRequestContentCollection(graphClient);

// Using AddBatchRequestStepAsync adds each request as a step
// with no specified order of execution
var userRequestId = await batchRequestContent
    .AddBatchRequestStepAsync(userRequest);
var eventsRequestId = await batchRequestContent
    .AddBatchRequestStepAsync(eventsRequest);

var returnedResponse = await graphClient.Batch.PostAsync(batchRequestContent);

// De-serialize response based on known return type
try
{
    var user = await returnedResponse
        .GetResponseByIdAsync<User>(userRequestId);
    Console.WriteLine($"Hello {user.DisplayName}!");
}
catch (Exception ex)
{
    Console.WriteLine($"Get user failed: {ex.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<EventCollectionResponse>(eventsRequestId);
    Console.WriteLine(
        $"You have {events.Value?.Count} events on your calendar today.");
}
catch (Exception ex)
{
    Console.WriteLine($"Get calendar view failed: {ex.Message}");
}

包含依赖请求的批处理

此示例演示如何在一个批中发送多个彼此依赖的请求。 服务按依赖项指定的顺序运行请求。 本示例将一个在当天开始时间的事件添加到用户的日历中，并获取该用户的日历视图。 为了确保返回的日历审阅包括创建的新事件，日历视图的请求配置为依赖于添加新事件的请求。 这可确保首先运行添加事件请求。

注意

如果添加事件请求失败，则获取日历视图请求失败并显示 424 Failed Dependency 错误。

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,
    },
};

// Use the request builder to generate a regular
// POST request to /me/events
var addEventRequest = graphClient.Me.Events
    .ToPostRequestInformation(newEvent);

// Use the request builder to generate a regular
// request to /me/calendarview?startDateTime="start"&endDateTime="end"
var calendarViewRequest = graphClient.Me.CalendarView.ToGetRequestInformation(
    requestConfiguration =>
    {
        requestConfiguration.QueryParameters.StartDateTime =
            today.ToString("yyyy-MM-ddTHH:mm:ssK");
        requestConfiguration.QueryParameters.EndDateTime =
            today.AddDays(1).ToString("yyyy-MM-ddTHH:mm:ssK");
    });

// Build the batch
var batchRequestContent = new BatchRequestContentCollection(graphClient);

// 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 = await batchRequestContent
    .AddBatchRequestStepAsync(addEventRequest);

// Second request, depends on addEventRequestId
var eventsRequestId = Guid.NewGuid().ToString();
var eventsRequestMessage = await graphClient.RequestAdapter
    .ConvertToNativeRequestAsync<HttpRequestMessage>(calendarViewRequest);
batchRequestContent.AddBatchRequestStep(new BatchRequestStep(
    eventsRequestId,
    eventsRequestMessage,
    [addEventRequestId]));

var returnedResponse = await graphClient.Batch.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 (Exception ex)
{
    Console.WriteLine($"Add event failed: {ex.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<EventCollectionResponse>(eventsRequestId);
    Console.WriteLine(
        $"You have {events.Value?.Count} events on your calendar today.");
}
catch (Exception ex)
{
    Console.WriteLine($"Get calendar view failed: {ex.Message}");
}