使用查询参数自定义响应

Microsoft Graph 提供可选的查询参数,可用于指定和控制响应中返回的数据量。支持以下查询参数。

名称 说明 示例(单击示例可在 Graph 浏览器中试调用)
$filter 筛选结果(行)。 /users?$filter=startswith(givenName,'J')
$select 筛选属性(列)。 /users?$select=givenName,surname
$expand 检索相关资源。 /groups/{id}?$expand=members
$orderby 对结果进行排序。 /users?$orderby=displayName,userPrincipalName desc
$top 限制结果。通常与 $skipToken 配合使用。 /users?$top=2
$skipToken $top 配合使用可以检索结果页。 有关示例,请参阅 $top 查询中的 nextLink
$count 检索匹配资源的总数。 /me/messages?$top=2&$count=true

这些参数与 OData V4 查询语言兼容。

注意:beta 终结点上,$ 前缀是可选的。例如,可使用 filter 来代替 $filter。有关更多详细信息和示例,请参阅 Microsoft Graph 中支持不含 $ 前缀的查询参数

编码查询参数:

应对查询参数的值进行百分比编码。许多 HTTP 客户端、浏览器和工具(例如,Graph 浏览器)都可以帮助你完成此操作。如果查询失败,可能原因之一是未正确编码查询参数的值。

未编码的 URL 如下所示:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName, 'J')

正确解码的 URL 如下所示:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName%2C+'J')

filter

$filter 可用于仅检索集合的一部分内容。例如,若要查找显示名称以 J 开头的用户,请使用 startswith

在 Graph 浏览器中试调用

请求:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'J')

响应:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
    "value": [
        {
            "id": "e013b9f3-a1ab-48d1-907b-e716c39d6363",
            "businessPhones": [
                "4255550100"
            ],
            "displayName": "Jan Madden",
            "givenName": "Jan",
            "jobTitle": null,
            "mail": "demo32@a830edad9050849NDA1.onmicrosoft.com",
            "mobilePhone": null,
            "officeLocation": null,
            "preferredLanguage": null,
            "surname": "Madden",
            "userPrincipalName": "demo32@a830edad9050849NDA1.onmicrosoft.com"
        },
        {
            "id": "89efe8ed-d141-4151-a3e4-570a70022dff",
            "businessPhones": [
                "+1 425 555 0109"
            ],
            "displayName": "Janet Schorr",
            "givenName": "Janet",
            "jobTitle": "Product Marketing Manager",
            "mail": "janets@a830edad9050849NDA1.onmicrosoft.com",
            "mobilePhone": null,
            "officeLocation": "18/2111",
            "preferredLanguage": null,
            "surname": "Schorr",
            "userPrincipalName": "janets@a830edad9050849NDA1.onmicrosoft.com"
        },
        ...
    ]
}

$filter 的语法非常丰富且富于表现力,其中可内置许多运算符。逻辑运算符包括等于 (eq)、不等于 (ne)、大于 (gt)、大于或等于 (gte)、且 (and)、或 (or)、非 (not) 等。算术运算符包括加 (add)、减 (sub) 等。字符串运算符包括包含 (contains),开头为 (startswith) 等。lambda 运算符包括任意 (any) 和所有 (all)。有关 $filter 语法的其他详细信息,请参阅 OData 协议

select

在集合或单个实体中,若要指定返回不同于默认集的属性集,请使用 $select 查询参数。使用 $select 参数,可以选择返回的默认集的子集或超集。例如,检索邮件时,不妨选择仅返回邮件的 fromsubject 属性。

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

expand

在 Microsoft Graph API 请求中,对参考项目的对象或集合的导航不会自动扩展。这是有意为之,因为这样可以减少网络流量以及从服务生成响应所需的时间。不过,在某些情况下,您可能希望在响应中添加这些结果。

$expand 查询字符串参数可用于指示 API 扩展子对象或集合,并添加这些结果。

例如,若要检索根驱动器信息和驱动器中的顶级子项,请使用 $expand 参数。此示例还使用 $select 声明,以便仅返回子项的 idname 属性。

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children($select=id,name)

注意:最多可为请求扩展 20 个对象。此外,如果查询 user 资源,可以使用 $expand,一次仅获取一个子对象或集合的属性。下面的示例便是获取 user 对象,每个请求在 directReports 集合中最多扩展 20 个 directReport 对象:

GET https://graph.microsoft.com/v1.0/users?$expand=directReports

其他一些资源可能也有限制,因此,请务必检查是否可能有错。

orderby

若要指定从 Microsoft Graph API 返回的项的排序顺序,请使用 $orderby 查询参数。

例如,若要返回组织中的用户,并按显示名称进行排序,请使用以下语法:

GET https://graph.microsoft.com/v1.0/users?$orderby=displayName

还可以按复杂类型实体进行排序。下面的示例获取邮件,然后按 from 属性的 address 字段(属于复杂类型 emailAddress)对这些邮件进行排序:

GET https://graph.microsoft.com/v1.0/me/messages?$orderby=from/emailAddress/address

若要以升序或降序对结果进行排序,请向字段名称追加 ascdesc,并用空格隔开。例如,?$orderby=name%20desc

注意:如果查询 user 资源,不能将 $orderby 与 filter 表达式结合使用。

top

若要指定结果集中返回的项数上限,请使用 $top 查询参数。$top 查询参数可确定集合的子集。这个子集是通过仅选择集合的前 N 项而形成,其中 N 是此查询参数指定的正整数。例如,若要返回用户邮箱中的前 5 封邮件,请使用以下语法:

GET https://graph.microsoft.com/v1.0/me/messages?$top=5

skip

若要设置在检索集合中的项之前要跳过的项数,请使用 $skip 查询参数。例如,若要返回按创建日期排序的事件,并从第 21 个事件开始返回,请使用以下语法。

GET  https://graph.microsoft.com/v1.0/me/events?$orderby=createdDateTime&$skip=20

skipToken

若要请求第二个和后续 Graph 数据页,请使用 $skipToken 查询参数。当 Graph 返回部分结果时(通常是由于服务器端分页所致),Graph 返回的 URL 中会提供 $skipToken 查询参数。它在集合中标识了服务器发送完结果的点,并会传递回 Graph 以指明应从哪里继续发送结果。例如,$skipToken 查询参数的值可以标识集合中的第 10 项,也可以标识包含 50 项的集合中的第 20 项,亦可标识集合中的其他任何位置。

一些响应中会有 @odata.nextLink 值。其中一些包括 $skipToken 值。$skipToken 值就像是一个标记,用于指示服务从哪里继续返回下一组结果。下面的示例展示了用户请求按 displayName 进行排序的响应中的 @odata.nextLink 值:

"@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$orderby=displayName&$skiptoken=X%2783630372100000000000000000000%27"

若要返回下一页的组织用户,请使用以下语法。

GET  https://graph.microsoft.com/v1.0/users?$orderby=displayName&$skiptoken=X%2783630372100000000000000000000%27

count

$count 查询参数可用于添加集合中的项总数,以及从 Graph 返回的数据值页,如下面的示例所示:

GET  https://graph.microsoft.com/v1.0/me/contacts?$count=true

这将同时返回 contacts 集合和 @odata.count 属性中 contacts 集合中的项数。

注意:directoryObject 集合不支持此查询参数。

若要限制与搜索条件匹配的请求结果,请使用 $search 查询参数。

注意:目前能搜索 messageperson 集合。$search 请求最多可返回 250 个结果。不能在搜索请求中使用 $filter$orderby

搜索条件使用高级查询语法 (AQS) 进行表示。结果按邮件发送日期和时间进行排序。

可以在 $search 条件中对 message 指定下列属性:attachmentsbccRecipientsbodycategoryccRecipientscontentfromhasAttachmentsparticipantsreceivedDateTimesendersubjecttoRecipients

如果要搜索邮件并且仅指定了一个值,那么会根据默认搜索属性 fromsubjectbody 进行搜索。

下面的示例返回登录用户收件箱中在三个默认搜索属性的任意一个中包含“pizza”的的所有邮件:

GET https://graph.microsoft.com/v1.0/me/messages?$search="pizza"

下一个示例在用户收件箱中搜索从指定电子邮件地址发送的所有邮件:

GET https://graph.microsoft.com/v1.0/me/messages?$search="from:help@contoso.com"