使用 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 = new string[] { "displayName", "jobTitle"};
    });

检索实体列表

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

注意

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

// GET https://graph.microsoft.com/v1.0/me/messages?$select=subject,sender&$filter=<some condition>&orderBy=receivedDateTime

var messages = await graphClient.Me.Messages
    .GetAsync( requestConfig => 
                {
                    requestConfig.QueryParameters.Select = new string[] { "subject", "sender"};
                    requestConfig.QueryParameters.Filter = "<filter condition>";
                    requestConfig.QueryParameters.Orderby = new string[] { "receivedDateTime" };
                });

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

访问集合的项

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

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}

string messageId = "AQMkAGUy..";
var message = await graphClient.Me.Messages[messageId]
    .GetAsync();

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

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments

string messageId = "AQMkAGUy...";
var message = await graphClient.Me.Messages[messageId]
    .GetAsync( requestConfig => requestConfig.QueryParameters.Select = new string[] { "attachments" });

删除实体

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

// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}

string messageId = "AQMkAGUy...";
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
    }
};

var teamId = "71766077-aacc-470a-be5e-ba47db3b2e88";

await graphClient.Teams[teamId]
    .PatchAsync(team);

使用 HTTP 标头控制请求行为

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

//  GET https://graph.microsoft.com/v1.0/users/{user-id}/events

var events = await graphClient.Me.Events
    .GetAsync( requestConfig => 
                {
                    requestConfig.Headers.Add("Prefer", @"outlook.timezone=""Pacific Standard Time""");
                    requestConfig.QueryParameters.Select = new string[] {"subject", "body", "bodyPreview"};
                });

提供自定义查询参数

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

//GET https://graph.microsoft.com/v1.0/me/calendarView

var calendar = await graphClient.Me.CalendarView
    .GetAsync(requestConfiguration => 
    {
        requestConfiguration.QueryParameters.StartDateTime = "2020-12-01T00:00:00Z";
        requestConfiguration.QueryParameters.EndDateTime = "2020-12-30T00:00:00Z";
    });