支援的查詢、篩選和分頁選項 | Graph API 概念
本主題列出可以與 Azure Active Directory (AD) Graph API 搭配使用的查詢選項、篩選和分頁作業。 最後一節提供一些您可以使用 Azure AD Graph API 執行的常用查詢範例。
重要
我們強烈建議您使用 Microsoft Graph 來存取 Azure Active Directory 資源，而不是使用 Azure AD Graph API。我們目前致力於開發 Microsoft Graph，對於 Azure AD Graph API 則沒有進一步增強的計劃。Azure AD Graph API 仍適用於非常少數的案例；如需詳細資訊，請參閱 Office 開發人員中心的 Microsoft Graph 或 Azure AD Graph (英文) 部落格文章。
定址
下列所有查詢皆使用網域名稱定址租用戶。 您可以使用其中一個租用戶的已註冊網域名稱、您的租用戶識別碼 (GUID)，或 MyOrganization 別名 (適用於委派存取) 來取代 contoso.com。 在某些情況下，您可以使用 me 別名。 如需租用戶其他定址方式的資訊，請參閱作業概觀.。
支援的查詢選項
圖形支援下列查詢選項︰$filter、$orderby、$expand、$top，和 $format。 目前不支援下列查詢選項：$count、$inlinecount，和 $skip。
$filter
下列一般限制適用於包含篩選的查詢：
$filter 不能與 $orderby 運算式合併使用。
篩選不受 DirectoryRole 或 SubscribedSku 目錄物件的查詢所支援。
並非所有支援目錄物件的屬性都能夠用於篩選運算式。 如需支援類型之可篩選屬性的資訊，請參閱 User、Group以及Contact。
下列限制適用於篩選運算式：
邏輯運算子：支援 ** 和 ** 以及 ** 或 ** 。 例如：
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 的 DisplayName 和 Group 物件，和 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
$top 不支援 DirectoryRole 或 SubscribedSku 目錄物件上的查詢。
分頁支援
您可以在 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 |
| 使用者 | 傳回使用者資訊 | 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 |
| 要求並篩選具有與 “Jon Doe” 相符之 displayName 的使用者 | https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| 要求並篩選具有與“Jon”相符之 firstName 的特定使用者 | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| 篩選 givenName 和姓氏值。 | 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。