使用 Microsoft Graph SDK 进行 API 调用

  • 项目

Microsoft Graph SDK 服务库提供一个客户端类，用作创建所有 API 请求的起点。 客户端类有两种样式：一种使用 fluent 接口创建请求 (例如， client.Users["user-id"].Manager) ，另一种使用路径字符串 (例如 api("/users/user-id/manager")) 。 当具有请求对象时，可以指定各种选项（例如筛选和排序），最后，选择要执行的操作类型。

还有 Microsoft Graph PowerShell SDK，它没有客户端类。 相反，所有请求都表示为 PowerShell 命令。 例如，若要获取用户的经理，命令为 Get-MgUserManager。 有关查找 API 调用的命令的详细信息，请参阅 导航 Microsoft Graph PowerShell SDK。

从 Microsoft Graph 读取信息

若要从 Microsoft Graph 读取信息，首先需要创建一个请求对象， GET 然后在请求上运行 方法。

// GET https://graph.microsoft.com/v1.0/me
var user = await graphClient.Me
    .GetAsync();

使用$select控制返回的属性

检索实体时，并非所有属性都会自动检索;有时，需要显式选择它们。 此外，在某些情况下，不需要返回默认的属性集。 仅选择所需的属性可以提高请求的性能。 可以自定义请求，以包含 $select 具有属性列表的查询参数。

// GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle
var user = await graphClient.Me
    .GetAsync(requestConfiguration =>
    {
        requestConfiguration.QueryParameters.Select =
            ["displayName", "jobTitle"];
    });

检索实体列表

检索实体列表类似于检索单个实体，但存在用于配置请求的其他选项。 查询 $filter 参数可以将结果集减少到仅那些与所提供的条件匹配的行。 查询 $orderby 参数请求服务器提供按指定属性排序的实体列表。

注意

Microsoft Entra资源的一些请求需要使用高级查询功能。 如果收到指示错误请求、不支持的查询或包含意外结果的响应（包括 $count 查询参数和 ConsistencyLevel 标头）的响应，则请求可能会成功。 有关详细信息和示例，请参阅 目录对象的高级查询功能。

// GET https://graph.microsoft.com/v1.0/me/messages?
// $select=subject,sender&$filter=subject eq 'Hello world'
var messages = await graphClient.Me.Messages
    .GetAsync(requestConfig =>
    {
        requestConfig.QueryParameters.Select =
            ["subject", "sender"];
        requestConfig.QueryParameters.Filter =
            "subject eq 'Hello world'";
    });

检索实体列表时返回的对象可能是分页集合。 有关如何获取实体的完整列表的详细信息，请参阅 对集合进行分页。

访问集合的项

对于支持流畅样式的 SDK，可以使用数组索引访问实体集合。 对于基于模板的 SDK，将项标识符嵌入集合后的路径段就足够了。 对于 PowerShell，标识符作为参数传递。

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
var message = await graphClient.Me.Messages[messageId]
    .GetAsync();

在请求main实体的同时，可以使用$expand筛选器请求相关实体或实体集合。

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments
// messageId is a string containing the id property of the message
var message = await graphClient.Me.Messages[messageId]
    .GetAsync(requestConfig =>
        requestConfig.QueryParameters.Expand =
            ["attachments"]);

删除实体

删除请求的构造方式与检索实体的请求相同，但使用 DELETE 请求而不是 GET。

// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
await graphClient.Me.Messages[messageId]
    .DeleteAsync();

发出 POST 请求以创建新实体

对于支持流畅样式的 SDK，可以使用 方法将新项添加到集合 Add 中。 对于基于模板的 SDK，请求对象公开方法 post 。 对于 PowerShell， New-* 命令接受映射到要添加的实体的参数。 从调用返回创建的实体。

// POST https://graph.microsoft.com/v1.0/me/calendars
var calendar = new Calendar
{
    Name = "Volunteer",
};

var newCalendar = await graphClient.Me.Calendars
    .PostAsync(calendar);

使用 PATCH 更新现有实体

Microsoft Graph 中的大多数更新都是使用 PATCH 方法执行的;因此，只需在传递的对象中包含要更改的属性。

// PATCH https://graph.microsoft.com/v1.0/teams/{team-id}
var team = new Team
{
    FunSettings = new TeamFunSettings
    {
        AllowGiphy = true,
        GiphyContentRating = GiphyRatingType.Strict,
    },
};

// teamId is a string containing the id property of the team
await graphClient.Teams[teamId]
    .PatchAsync(team);

使用 HTTP 标头控制请求行为

可以使用 函数将自定义标头附加到请求 Header() 。 对于 PowerShell，只能通过 Invoke-GraphRequest 方法添加标头。 某些 Microsoft Graph 方案使用自定义标头来调整请求的行为。

// GET https://graph.microsoft.com/v1.0/me/events
var events = await graphClient.Me.Events
    .GetAsync(requestConfig =>
    {
        requestConfig.Headers.Add(
            "Prefer", @"outlook.timezone=""Pacific Standard Time""");
    });

提供自定义查询参数

对于支持流畅样式的 SDK，可以使用对象列表 QueryOptions 提供自定义查询参数值。 对于基于模板的 SDK，参数经过 URL 编码并添加到请求 URI。 对于 PowerShell 和 Go，给定 API 的已定义查询参数将作为参数公开给相应的命令。

// GET https://graph.microsoft.com/v1.0/me/calendarView?
// startDateTime=2023-06-14T00:00:00Z&endDateTime=2023-06-15T00:00:00Z
var events = await graphClient.Me.CalendarView
    .GetAsync(requestConfiguration =>
    {
        requestConfiguration.QueryParameters.StartDateTime =
            "2023-06-14T00:00:00Z";
        requestConfiguration.QueryParameters.EndDateTime =
            "2023-06-15T00:00:00Z";
    });