サポートされているクエリ、フィルター、およびページング オプション | Graph API 概念

このトピックでは、Azure Active Directory (AD) Graph API で使用できるクエリ オプション、フィルター、ページング操作の一覧を示します。 最後のセクションでは、Azure AD Graph API で実行できる一般クエリの例をいくつか紹介します。

アドレス指定

次のクエリはいずれも、ドメイン名を使用してテナントのアドレスを指定しています。 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 オプションを使用する要求を次に示します。

$orderby 式には次の制限が適用されます。

• 現在のところ、2 つの並べ替え順序がサポートされています。User オブジェクトと Group オブジェクトには DisplayName が、User オブジェクトには UserPrincipalName がサポートされています。 ユーザーの既定の並べ替え順序は、UserPrincipalName によって決まります。

• $orderby を $filter 式と組み合わせることはできません。

$expand

$expand はオブジェクトとそれにリンクされたオブジェクトを返します。 たとえば、$expand オプションを使用する要求を次に示します。

$expand 式には次の制限が適用されます。

• 要求に対して返されるオブジェクトの個数は最大で 20 です。

$top

DirectoryRole または SubscribedSku ディレクトリ オブジェクトを対象にするクエリでは、$top はサポートされていません。

ページングのサポート

Graph では、前後にページングすることができます。 ページング結果を含む応答には、結果の次のページの取得を可能にする skip トークン (odata.nextLink) が含まれます。 この skip トークンを previous-page=true クエリ引数と組み合わせると、後方にページングできます。

次の要求の例では、前方へのページングを示します。

次の要求の例では、後方へのページングを示します。

次の手順では、前方および後方にページングするための要求/応答フローを示します。

1. 15 ユーザーのうち、最初の 10 ユーザーの一覧を取得するための要求が発行されます。 応答には、10 ユーザーの最後のページを示す skip トークンが含まれます。
2. 最後の 5 つのユーザーを取得するために、前の応答から返された skip トークンを含む別の要求が作成されます。
3. 後方にページングするために、手順 1. で返された skip トークンを使用して要求が作成され、パラメーター &previous-page=true が要求に追加されます。
4. 応答には、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 ヘッダーが必要になります。

その他のクエリ操作

次の表では、contoso.com をテナントとして使用した Graph API クエリの例をいくつか紹介します。

注: クエリ文字列内の空白は、要求を送信する前に 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 にエンコードされます。

その他のリソース

• Azure AD Graph API の差分クエリ
• Azure AD Graph API リファレンス