Table of contents

支持的查询、筛选和分页选项 | Graph API 概念Supported queries, filters, and paging options | Graph API concepts

Jimaco Brannian|上次更新日期: 2018/6/19
2 参与人员

本主题列出了可以与 Azure AD Graph API 搭配使用的查询选项、筛选器和分页操作。This topic lists query options, filters, and paging operations that you can use with the Azure Active Directory (AD) Graph API.最后一节提供了可以使用 Azure AD Graph API 执行的常用查询的几个示例。The final section gives some examples of common queries that you can perform with the Azure AD Graph API.


强烈建议使用 Microsoft Graph 代替 Azure AD Graph API 来访问 Azure Active Directory 资源。We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.现在我们的开发工作将重点集中在 Microsoft Graph 上,没有计划对 Azure AD Graph API 进行进一步的改进。Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.Azure AD Graph API 仍适用的方案数量非常有限;有关详细信息,请参阅 Office 开发人员中心中的博客文章 Microsoft Graph 或 Azure AD GraphThere are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

寻址 Addressing

下面的所有查询全都使用某一域名对租户进行寻址。The queries below all address the tenant using a domain name.你可以使用租户已注册的域名称的其中之一,使用租户 ID (GUID),或使用 MyOrganization 别名(用于委托访问)替换 contoso.comYou can replace with one of your tenant’s registered domain names, with your tenant's ID (GUID), or with the MyOrganization alias (for delegated access).在某些情况下,也可以使用 me 别名。In some cases, you may be able to use the me alias.有关对租户进行寻址的方式的信息,请参阅操作概述For information about ways of addressing the tenant, see Operations overview.

支持的查询选项 Supported query options

Graph 支持以下查询选项:$filter$orderby$expand$top$formatThe Graph supports the following query options: $filter, $orderby, $expand, $top, and $format.目前暂不支持以下查询选项:$count$inlinecount and $skipThe following query options are not currently supported: $count, $inlinecount, and $skip.


以下一般性限制适用于包含筛选器的查询:The following general restrictions apply to queries that contain a filter:

  • $filter 不能与 $orderby 表达式组合。$filter cannot be combined with $orderby expressions.

  • DirectoryRoleSubscribedSku 目录对象上的查询不支持筛选。Filtering is not supported for queries on DirectoryRole or SubscribedSku directory objects.

  • 不是支持的目录对象的所有属性都可以在筛选表达式中使用。Not all properties of supported directory objects can be used in a filter expression.有关支持类型的可筛选属性的信息,请参阅 UserGroupContactFor information about filterable properties of supported types, see User, Group, and Contact.

以下限制适用于筛选表达式:The following restrictions apply to filter expressions:

  • 逻辑运算符:支持 andorLogical operators: and and or are supported.例如:$filter=accountEnabled eq true and (userPrincipalName eq '' or mail eq '')For example:$filter=accountEnabled eq true and (userPrincipalName eq '' or mail eq '')

  • 比较运算符:eq(等于)、ge(大于或等于)和 le(小于或等于)。Comparison operators: eq (equal to), ge (greater than or equal to), and le (less than or equal to) are supported.

  • 支持 startswithstartswith is supported.例如:$filter=startswith(displayName,'Mary')For example:$filter=startswith(displayName,'Mary')

  • 查询多值属性时,支持 anyany is supported when querying multi-valued properties.例如:$filter=userPrincipalName eq '' or proxyAddresses/any(c:c eq '')For example:$filter=userPrincipalName eq '' or proxyAddresses/any(c:c eq '')

  • 算术运算符:不支持。Arithmetic operators: not supported.

  • 函数:不支持。Functions: not supported.

  • 在筛选器表达式中不支持 null 值作为操作数。null values are not supported as an operand in filter expressions.例如,不能指定 null 值来筛选取消设置的属性。For example, you cannot specify a null value to filter for unset properties.

  • 要对“userIdentities”中的“issuerUserId”等二进制属性进行筛选,必须先对值进行 Base64 编码,然后才能将值用于 $filter 字符串中。To filter on a binary property such as the issuerUserId in userIdentities, the value must first be base64 encoded before it can be used in the $filter string.


$orderby 将按指定的参数对返回的对象进行排序。$orderby will sort the returned objects by the specified parameter.使用 $orderby 选项的示例请求:Example requests using the $orderby option:

请求Request描述Description$orderby=displayName&api-version=1.6返回按用户的显示名称排序的用户列表。Returns a list of users ordered by their display name.$orderby=displayName&$top=50&api-version=1.6返回按用户的显示名称排序的前 50 名用户的列表。Returns a list of the first 50 users ordered by their display name.

以下限制适用于 $orderby 表达式:The following restrictions apply to $orderby expressions:

  • 目前支持两种排序顺序:UserGroup 对象的 DisplayName,以及 User 对象的 UserPrincipalNameTwo sort orders are currently supported: DisplayName for User and Group objects, and UserPrincipalName for User objects.用户的默认排序顺序是按 UserPrincipalName 排序。The default sort order for users is by UserPrincipalName.

  • $orderby 不能与 $filter 表达式组合。$orderby cannot be combined with $filter expressions.


$expand 将返回一个对象及其链接的对象。$expand will return an object and its linked objects.使用 $expand 选项的示例请求:Example requests using the $expand option:

请求Request描述Description$expand=members&api-version=1.6返回组对象及其成员。Returns both the group object as well as its members.$expand=directReports&api-version=1.6返回用户对象及其直接下属。Returns both the user object as well as its direct reports.$expand=manager&api-version=1.6返回用户对象及其经理。Returns both the user object as well as its manager.

以下限制适用于 $expand 表达式:The following restrictions apply to $expand expressions:

  • 请求返回的对象的最大数目是 20。The maximum number of returned objects for a request is 20.


DirectoryRoleSubscribedSku 目录对象上的查询不支持 $top。$top is not supported for queries on DirectoryRole or SubscribedSku directory objects.

分页支持 Paging support

可以在 Graph 中页向前和向后翻页。You can page forward and backward in the Graph.包含分页结果的响应将包括一个允许你获取下一页结果的跳过标记 (odata.nextLink)。A response that contains paged results will include a skip token (odata.nextLink) that allows you to get the next page of results.此跳过标记可以与 previous-page=true 查询参数组合以向后翻页。This skip token can be combined with a previous-page=true query argument to page backwards.

以下示例请求演示向前翻页:The follow example request demonstrates paging forward:

请求Request描述Description$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000'包括之前响应的 $skiptoken 参数,并且能够获取结果的下一页。The $skiptoken parameter from the previous response is included, and allows you to get the next page of results.

以下示例请求演示向后翻页:The following example request demonstrates paging backward:

请求Request描述Description$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true包括之前响应的 $skiptoken 参数。The $skiptoken parameter from the previous response is included.当该参数与 &previous-page=true 参数组合时,将检索结果的前一页。When this is combined with the &previous-page=true parameter, the previous page of results will be retrieved.

以下步骤演示向前和向后翻页的请求/响应流程:The following steps demonstrate the request/response flow to page forward and backward:

  1. 发出请求以获取 15 名用户中前 10 名的用户列表。A request is made to get a list of the first 10 users out of 15.响应包含跳过标记以指示 10 名用户的最后一页。The response contains a skip token to indicate the final page of 10 users.
  2. 若要获取最后 5 名用户,请发出另一个请求,其中包含前一响应返回的跳过标记。To get the final 5 users, another request is made that contains the skip token returned from the previous response.
  3. 若要向后翻页,请使用步骤 1 中返回的跳过标记发出请求,并将参数 &previous-page=true 添加到该请求。To page backward, a request is made using the skip token returned in step 1 and the parameter &previous-page=true is added to the request.
  4. 响应中包含前一(第一)页的 10 名用户。The response contains the previous (first) page of 10 users.在剩下更多页的不同方案中,将返回一个新的跳过标记。In a different scenario where more pages are left, a new skip token would be returned.这个新的跳过标记可以与 &previous-page=true 一起添加到请求以再次向后翻页。This new skip token can be added to the request along with &previous-page=true to page backward again.

以下限制适用于分页请求:The following restrictions apply to paged requests:

  • 默认页大小为 100。The default page size is 100.最大页大小为 999。The maximum page size is 999.
  • 针对角色的查询不支持分页。Queries against roles do not support paging.这包括读取角色对象本身以及角色成员。This includes reading role objects themselves as well as role members.
  • 资源列表,如租户中所有用户的搜索 (/users),查询的确支持分页。Resource listing, such as a search for all users in a tenant (/users), queries do support paging.例如: example:但是,在应用某一筛选器时,不支持跨所有类型的分页并且仅返回结果的第一页。However, across all types when a filter is applied, paging is not supported and only the first page of results is returned.
  • 不支持对链接搜索(例如,查询组成员)的分页。Paging is not supported for link searches, such as for querying group members.例如:$links/members?api-version=1.6For example:$links/members?api-version=1.6.

排序顺序 Sort order

  • 所有用户的查询结果集将按 UserPrincipalName 属性进行排序。The result set of a query for all users is ordered by the UserPrincipalName property.例如: example:
  • 所有其他顶级资源(例如,组、联系人等)的查询结果集将按 objectId 属性进行排序。The result set of a query for all other top-level resources, such as Groups, Contacts, etc. is ordered by the objectId property.例如: example:
  • 并非顶层资源的查询结果的顺序是不确定的。The order of the results of queries other than for top-level resources is indeterminate.

常见查询 Common queries

以下部分介绍了可以使用 Graph API 执行的常见查询的一些示例。The following sections show some examples of common queries you can perform with the Graph API.

查询顶层资源Querying top-level resources

以下查询使用 作为示例租户,演示了如何使用 Graph API 访问顶层资源。The following queries demonstrate how to access top-level resources with the Graph API using as the example tenant.请注意,要运行针对租户的查询,将需要授权标头,该标头包含接收自 Azure AD 的有效持有者令牌。Note that an Authorization header containing a valid bearer token received from Azure AD will be required to run queries against a tenant.

顶层资源Top-Level Resource查询结果Query ResultsURI(对于 (for
顶层资源Top-level resources为目录服务返回顶层资源的 URI 列表(也在下面列出)Returns URI list of the top-level resources for directory services (also listed below)
公司信息Company information返回公司信息Returns company information
联系人Contacts返回组织联系人信息Returns organizational contact information
UsersUsers返回用户信息Returns user information
Groups返回组数据Returns group data
目录角色Directory Roles返回租户中所有已激活的目录角色Returns all activated directory roles in the tenant
SubscribedSkusSubscribedSkus返回租户的订阅Returns the tenant's subscriptions
目录元数据Directory metadata返回描述数据模型的服务元数据文档(即,目录资源的结构和组织)Returns a Service Metadata Document that describes the data model (that is, structure and organization of directory resources)$metadata?api-version=1.6

其他查询操作Other query operations

下表介绍了一些使用 作为示例租户的其他示例性 Graph API 查询。The following table shows some additional example Graph API queries using as the example tenant.

查询操作Query OperationURI(对于 (for
列出所有用户和组List all Users and Groups
通过指定 objectId 或 userPrincipalName 检索单独用户Retrieve individual User by specifying the objectId or userPrincipalName
请求并筛选 displayName 等于“Jon Doe”的用户Request and Filter for a user with displayName equal to “Jon Doe”$filter=displayName eq 'Jon Doe'&api-version=1.6
请求并筛选 firstName 等于“Jon”的特定用户Request and Filter for specific users with firstName equal to “Jon”$filter=givenName eq 'Jon'&api-version=1.6
筛选 givenName 和 surname 值。Filter for givenName and surname values.$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6
通过指定 objectId 检索单个组Retrieve individual group by specifying the objectId
检索用户的经理Retrieve a user’s manager
检索用户的直接下属列表Retrieve a user’s direct reports list
检索到用户的直接下属的链接列表Retrieve a list of links to a user’s direct reports$links/directReports?api-version=1.6
检索某一组的成员身份列表Retrieve membership list of a group
检索到某一组的成员的链接列表。Retrieve a list of links to the members of a group.$links/members?api-version=1.6
检索用户的组成员身份(不可传递)Retrieve a user’s group membership (not transitive)
检索该用户是其成员的组的列表(不可传递)Retrieve a list of the groups that the user is a member of (not transitive)$links/memberOf?api-version=1.6
请求并筛选 displayName >= "az" 和 <= "dz" 的组Request and filter for groups with displayName >= "az" and <= "dz"$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6
返回 Azure Active Directory B2C 租户中的所有本地帐户用户Return all local account users in an Azure Active Directory B2C tenant eq 'LocalAccount'&api-version=1.6
返回登录名称为来自 Azure Active Directory B2C 租户中的 "" 的本地帐户用户Return local account user with the sign-in name "" from an Azure Active Directory B2C tenant$filter=signInNames/any(x:x/value eq '')&api-version=1.6

注意:查询字符串中的空格应先进行 URL 编码,然而才能发送请求。Note: White space in the query string should be URL-encoded before sending a request.例如,对下列查询字符串$filter=displayName eq 'Jon Doe'&api-version=1.6 进行 URL 编码后应为:$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6For example, the following query string,$filter=displayName eq 'Jon Doe'&api-version=1.6, should be URL encoded as:$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.

其他资源 Additional resources

© 2018 Microsoft