サポートされているクエリ、フィルター、およびページング オプション | Graph API 概念
このトピックでは、Azure Active Directory (AD) Graph API で使用できるクエリ オプション、フィルター、ページング操作の一覧を示します。 最後のセクションでは、Azure AD Graph API で実行できる一般クエリの例をいくつか紹介します。
重要
Azure Active Directory のリソースにアクセスするには、Azure AD Graph API ではなく Microsoft Graph を使用することを強くお勧めします。現在は Microsoft Graph を中心にして開発が進められており、Azure AD Graph API の今後の機能強化は予定されていません。Azure AD Graph API の使用が適切である場合もありますが、非常にまれです。詳細については、Office Dev Center の Microsoft Graph または Azure AD Graph ブログの記事をご覧ください。
アドレス指定
次のクエリはいずれも、ドメイン名を使用してテナントのアドレスを指定しています。 contoso.com は、テナントの登録済みのドメイン名のいずれか、テナントの ID (GUID)、または MyOrganization エイリアス (委任アクセスの場合) に置換できます。 場合によっては、me エイリアスを利用できます。 テナントのアドレス指定方法の詳細については、「操作の概要」を参照してください。
サポートされるクエリ オプション
Graph はクエリ オプションとして $filter、$orderby、$expand、$top、$format をサポートします。 $count、$inlinecount、$skip は現在のところサポートされていません。
$filter
フィルターを含むクエリには、次の一般的な制限が適用されます。
$filter を $orderby 式と組み合わせることはできません。
DirectoryRole または SubscribedSku ディレクトリ オブジェクトを対象にするクエリでは、フィルターはサポートされていません。
サポートされているディレクトリ オブジェクトのすべてのプロパティを、1 つのフィルター式で使用できるわけではありません。 サポートされている型のプロパティのうち、フィルターの適用が可能なプロパティの詳細については、「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 式には次の制限が適用されます。
現在のところ、2 つの並べ替え順序がサポートされています。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 では、前後にページングすることができます。 ページング結果を含む応答には、結果の次のページの取得を可能にする skip トークン (odata.nextLink) が含まれます。 この skip トークンを 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 ユーザーの最後のページを示す skip トークンが含まれます。
- 最後の 5 つのユーザーを取得するために、前の応答から返された skip トークンを含む別の要求が作成されます。
- 後方にページングするために、手順 1. で返された skip トークンを使用して要求が作成され、パラメーター &previous-page=true が要求に追加されます。
- 応答には、10 のユーザーの前の (最初の) ページが含まれます。 より多くのページが残る異なるシナリオでは、新しい skip トークンが返されます。 この新しい skip トークンを、&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と指定します。 - その他のすべてのトップ レベル リソースに対するクエリの結果セット (Groups、Contacts など) は、objectId プロパティに基づいて並べられます。 たとえば、
https://graph.windows.net/contoso.com/groups?api-version=1.6と指定します。 - トップレベル リソース以外を対象にするクエリの結果では、順序が不定になります。
一般的なクエリ
次のセクションでは、Graph API で実行できる一般クエリの例をいくつか紹介します。
トップ レベル リソースに対するクエリ
次のクエリでは、contoso.com をサンプル テナントとして使用して Graph API でトップ レベル リソースにアクセスする方法を示します。 テナントに対してクエリを実行するには、Azure AD から受信した有効なベアラー トークンを含む Authorization ヘッダーが必要になります。
| トップ レベル リソース | クエリ結果 | 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 というクエリ文字列は、https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6 という URL にエンコードされます。