Table of contents

支援的查詢、篩選和分頁選項 | Graph API 概念Supported queries, filters, and paging options | Graph API concepts

Jimaco Brannian|上次更新日期: 2018/6/19
2 貢獻者

本主題列出可以與 Azure Active Directory (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 Active Directory 資源,而不是使用 Azure AD Graph API。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 Graph (英文) 部落格文章。There 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.您可以使用其中一個租用戶的已註冊網域名稱、您的租用戶識別碼 (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

圖形支援下列查詢選項︰$filter$orderby$expand$top,和 $formatThe Graph supports the following query options: $filter, $orderby, $expand, $top, and $format.目前不支援下列查詢選項:$count$inlinecount,和 $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:

  • 邏輯運算子:支援 以及 Logical 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.使用者的預設排序順序是依 UserPrincipalNameThe 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=trueTo 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
使用者Users傳回使用者資訊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
要求並篩選具有與 “Jon Doe” 相符之 displayName 的使用者Request and Filter for a user with displayName equal to “Jon Doe”$filter=displayName eq 'Jon Doe'&api-version=1.6
要求並篩選具有與“Jon”相符之 firstName 的特定使用者Request and Filter for specific users with firstName equal to “Jon”$filter=givenName eq 'Jon'&api-version=1.6
篩選 givenName 和姓氏值。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