Table of contents

支持的查询、筛选和分页选项 | Graph API 概念

Jimaco Brannian|上次更新日期: 2016/9/5
|
1 参与者

本主题列出了可以与 Azure AD Graph API 搭配使用的查询选项、筛选器和分页操作。 最后一节提供了可以使用 Azure AD Graph API 执行的常用查询的几个示例。

重要事项

Azure AD Graph API 功能也可通过 Microsoft Graph 使用。Microsoft Graph 是一个统一的 API,它还包括其他 Microsoft 服务(如 Outlook、OneDrive、OneNote、Planner 和 Office Graph)的 API,这些都可以使用单个访问令牌通过单个终结点进行访问。

寻址

下面的所有查询全都使用某一域名对租户进行寻址。 你可以使用租户已注册的域名称的其中之一,使用租户 ID (GUID),或使用 MyOrganization 别名(用于委托访问)替换 contoso.com。 在某些情况下,也可以使用 me 别名。 有关对租户进行寻址的方式的信息,请参阅操作概述

支持的查询选项

Graph 支持以下查询选项:$filter$orderby$expand$top$format。 目前暂不支持以下查询选项:$count$inlinecount and $skip

$filter

以下一般性限制适用于包含筛选器的查询:

  • $filter 不能与 $orderby 表达式组合。

  • DirectoryRoleSubscribedSku 目录对象上的查询不支持筛选。

  • 不是支持的目录对象的所有属性都可以在筛选表达式中使用。 有关支持类型的可筛选属性的信息,请参阅 UserGroupContact

以下限制适用于筛选表达式:

  • 逻辑运算符:支持 andor。 例如: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=accountEnabled eq true and (userPrincipalName eq 'jonlawr@contoso.com' or mail eq 'jonlawr@contoso.com')

  • 比较运算符:eq(等于)、ge(大于或等于)和 le(小于或等于)。

  • 支持 startswith。 例如: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')

  • 查询多值属性时,支持 any。 例如: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=userPrincipalName eq 'Mary@Contoso.com' or proxyAddresses/any(c:c eq 'smtp:Mary@Contoso.com')

  • 算术运算符:不支持。

  • 函数:不支持。

  • 在筛选器表达式中不支持 null 值作为操作数。 例如,不能指定 null 值来筛选取消设置的属性。

$orderby

$orderby 将按指定的参数对返回的对象进行排序。 使用 $orderby 选项的示例请求:

请求描述
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6返回按用户的显示名称排序的用户列表。
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6返回按用户的显示名称排序的前 50 名用户的列表。

以下限制适用于 $orderby 表达式:

  • 目前支持两种排序顺序:UserGroup 对象的 DisplayName,以及 User 对象的 UserPrincipalName。 用户的默认排序顺序是按 UserPrincipalName 排序。

  • $orderby 不能与 $filter 表达式组合。

$expand

$expand 将返回一个对象及其链接的对象。 使用 $expand 选项的示例请求:

请求描述
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6返回组对象及其成员。
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6返回用户对象及其直接下属。
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6返回用户对象及其经理。

以下限制适用于 $expand 表达式:

  • 请求返回的对象的最大数目是 20。

$top

DirectoryRoleSubscribedSku 目录对象上的查询不支持 $top。

分页支持

可以在 Graph 中页向前和向后翻页。 包含分页结果的响应将包括一个允许你获取下一页结果的跳过标记 (odata.nextLink)。 此跳过标记可以与 previous-page=true 查询参数组合以向后翻页。

以下示例请求演示向前翻页:

请求描述
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000'包括之前响应的 $skiptoken 参数,并且能够获取结果的下一页。

以下示例请求演示向后翻页:

请求描述
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true包括之前响应的 $skiptoken 参数。 当该参数与 &previous-page=true 参数组合时,将检索结果的前一页。

以下步骤演示向前和向后翻页的请求/响应流程:

  1. 发出请求以获取 15 名用户中前 10 名的用户列表。 响应包含跳过标记以指示 10 名用户的最后一页。
  2. 若要获取最后 5 名用户,请发出另一个请求,其中包含前一响应返回的跳过标记。
  3. 若要向后翻页,请使用步骤 1 中返回的跳过标记发出请求,并将参数 &previous-page=true 添加到该请求。
  4. 响应中包含前一(第一)页的 10 名用户。 在剩下更多页的不同方案中,将返回一个新的跳过标记。 这个新的跳过标记可以与 &previous-page=true 一起添加到请求以再次向后翻页。

以下限制适用于分页请求:

  • 默认页大小为 100。 最大页大小为 999。
  • 针对角色的查询不支持分页。 这包括读取角色对象本身以及角色成员。
  • 资源列表,如租户中所有用户的搜索 (/users),查询的确支持分页。 例如:https://graph.windows.net/contoso.com/users?api-version=1.6。 但是,在应用某一筛选器时,不支持跨所有类型的分页并且仅返回结果的第一页。
  • 不支持对链接搜索(例如,查询组成员)的分页。 例如:https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6

排序顺序

  • 所有用户的查询结果集将按 UserPrincipalName 属性进行排序。 例如:https://graph.windows.net/contoso.com/users?api-version=1.6
  • 所有其他顶级资源(例如,组、联系人等)的查询结果集将按 objectId 属性进行排序。 例如:https://graph.windows.net/contoso.com/groups?api-version=1.6
  • 并非顶层资源的查询结果的顺序是不确定的。

常见查询

以下部分介绍了可以使用 Graph API 执行的常见查询的一些示例。

查询顶层资源

以下查询使用 contoso.com 作为示例租户,演示了如何使用 Graph API 访问顶层资源。 请注意,要运行针对租户的查询,将需要授权标头,该标头包含接收自 Azure AD 的有效持有者令牌。

顶层资源查询结果URI(对于 contoso.com)
顶层资源为目录服务返回顶层资源的 URI 列表(也在下面列出)https://graph.windows.net/contoso.com?api-version=1.6
公司信息返回公司信息https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6
联系人返回组织联系人信息https://graph.windows.net/contoso.com/contacts?api-version=1.6
Users返回用户信息https://graph.windows.net/contoso.com/users?api-version=1.6
返回组数据https://graph.windows.net/contoso.com/groups?api-version=1.6
目录角色返回租户中所有已激活的目录角色https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6
SubscribedSkus返回租户的订阅https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6
目录元数据返回描述数据模型的服务元数据文档(即,目录资源的结构和组织)https://graph.windows.net/contoso.com/$metadata?api-version=1.6

其他查询操作

下表介绍了一些使用 contoso.com 作为示例租户的其他示例性 Graph API 查询。

查询操作URI(对于 contoso.com)
列出所有用户和组https://graph.windows.net/contoso.com/users?api-version=1.6

https://graph.windows.net/contoso.com/groups?api-version=1.6
通过指定 objectId 或 userPrincipalName 检索单独用户https://graph.windows.net/contoso.com/users/d1f67a6c-02c9-4fe5-81fb-58160ce24fe5?api-version=1.6

https://graph.windows.net/contoso.com/users/admin@contoso.com?api-version=1.6
请求并筛选 displayName 等于“Jon Doe”的用户https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6
请求并筛选 firstName 等于“Jon”的特定用户https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6
筛选 givenName 和 surname 值。https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6
通过指定 objectId 检索单个组https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6
检索用户的经理https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6
检索用户的直接下属列表https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6
检索到用户的直接下属的链接列表https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6
检索某一组的成员身份列表https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6
检索到某一组的成员的链接列表。https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6
检索用户的组成员身份(不可传递)https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6
检索该用户是其成员的组的列表(不可传递)https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6
请求并筛选 displayName >= "az" 和 <= "dz" 的组https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6
返回 Azure Active Directory B2C 租户中的所有本地帐户用户https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6
返回登录名称为来自 Azure Active Directory B2C 租户中的 "joe@example.com" 的本地帐户用户https://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6

注意:查询字符串中的空格应先进行 URL 编码,然而才能发送请求。 例如,对下列查询字符串 https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 进行 URL 编码后应为:https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6

其他资源

© 2017 Microsoft