支持的查询、筛选和分页选项 | Graph API 概念
本主题列出了可以与 Azure AD Graph API 搭配使用的查询选项、筛选器和分页操作。 最后一节提供了可以使用 Azure AD Graph API 执行的常用查询的几个示例。
重要
强烈建议使用 Microsoft Graph 代替 Azure AD Graph API 来访问 Azure Active Directory 资源。现在我们的开发工作将重点集中在 Microsoft Graph 上，没有计划对 Azure AD Graph API 进行进一步的改进。Azure AD Graph API 仍适用的方案数量非常有限；有关详细信息，请参阅 Office 开发人员中心中的博客文章 Microsoft Graph 或 Azure AD Graph。
寻址
下面的所有查询全都使用某一域名对租户进行寻址。 你可以使用租户已注册的域名称的其中之一，使用租户 ID (GUID)，或使用 MyOrganization 别名（用于委托访问）替换 contoso.com。 在某些情况下，也可以使用 me 别名。 有关对租户进行寻址的方式的信息，请参阅操作概述。
支持的查询选项
Graph 支持以下查询选项: $filter、$orderby、$expand、$top 和 $format。 目前暂不支持以下查询选项: $count、$inlinecount and $skip。
$filter
以下一般性限制适用于包含筛选器的查询：
$filter 不能与 $orderby 表达式组合。
对于 DirectoryRole 或 SubscribedSku 目录对象上的查询不支持筛选。
不是支持的目录对象的所有属性都可以在筛选表达式中使用。 有关支持类型的可筛选属性信息，请参见 User、Group 和 Contact。
以下限制适用于筛选表达式：
逻辑运算符: 支持 and 和 or。 例如:
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 表达式：
目前支持两种排序顺序: User 和 Group 对象的 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
对于 DirectoryRole 或 SubscribedSku 对象目录上的查询不支持 $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 参数组合时，将检索结果的前一页。 |
以下步骤演示向前和向后翻页的请求/响应流程：
- 发出请求以获取 15 名用户中前 10 名的用户列表。 响应包含跳过标记以指示 10 名用户的最后一页。
- 若要获取最后 5 名用户，请发出另一个请求，其中包含前一响应返回的跳过标记。
- 若要向后翻页，请使用步骤 1 中返回的跳过标记发出请求，并将参数 &previous-page=true 添加到该请求。
- 响应中包含前一（第一）页的 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。