Table of contents

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

Jimaco Brannian|最終更新日: 2018/04/05
|
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.

重要

Azure Active Directory のリソースにアクセスするには、Azure AD Graph API ではなく Microsoft Graph を使用することを強くお勧めします。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 Dev Center の 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.contoso.com は、テナントの登録済みのドメイン名のいずれか、テナントの ID (GUID)、または MyOrganization エイリアス (委任アクセスの場合) に置換できます。You can replace contoso.com 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$format をサポートします。The Graph supports the following query options: $filter, $orderby, $expand, $top, and $format.$count$inlinecount$skip は現在のところサポートされていません。The following query options are not currently supported: $count, $inlinecount, and $skip.

$filter$filter

フィルターを含むクエリには、次の一般的な制限が適用されます。The following general restrictions apply to queries that contain a filter:

  • $filter を $orderby 式と組み合わせることはできません。$filter cannot be combined with $orderby expressions.

  • DirectoryRole または SubscribedSku ディレクトリ オブジェクトを対象にするクエリでは、フィルターはサポートされていません。Filtering is not supported for queries on DirectoryRole or SubscribedSku directory objects.

  • サポートされているディレクトリ オブジェクトのすべてのプロパティを、1 つのフィルター式で使用できるわけではありません。Not all properties of supported directory objects can be used in a filter expression.サポートされている型のプロパティのうち、フィルターの適用が可能なプロパティの詳細については、UserGroup、および Contact を参照してください。For information about filterable properties of supported types, see User, Group, and Contact.

フィルター式には次の制限が適用されます。The following restrictions apply to filter expressions:

  • 論理演算子: andor がサポートされています。Logical operators: and and or are supported.例: 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')For example: 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 (以下) がサポートされています。Comparison operators: eq (equal to), ge (greater than or equal to), and le (less than or equal to) are supported.

  • startswith がサポートされています。startswith is supported.例: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')For example: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')

  • 複数の値を持つプロパティに対してクエリを実行する際には any がサポートされます。any is supported when querying multi-valued properties.例: 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')For example: 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')

  • 算術演算子: サポートされていません。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.

  • userIdentitiesissuerUserId のようなバイナリ プロパティにフィルターを適用する場合は、最初に値を 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

$orderby は、返されたオブジェクトを指定されたパラメーターに基づいて並び替えます。$orderby will sort the returned objects by the specified parameter.たとえば、$orderby オプションを使用する要求を次に示します。Example requests using the $orderby option:

要求Request説明Description
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6表示名の順に並べられたユーザーの一覧を返します。Returns a list of users ordered by their display name.
https://graph.windows.net/contoso.com/users?$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:

  • 現在のところ、2 つの並べ替え順序がサポートされています。User オブジェクトと Group オブジェクトでは DisplayName が、User オブジェクトでは UserPrincipalName がサポートされています。Two 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

$expand はオブジェクトとそれにリンクされたオブジェクトを返します。$expand will return an object and its linked objects.たとえば、$expand オプションを使用する要求を次に示します。Example requests using the $expand option:

要求Request説明Description
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6グループ オブジェクトとそのメンバーを両方とも返します。Returns both the group object as well as its members.
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6ユーザー オブジェクトとその直属の部下を両方とも返します。Returns both the user object as well as its direct reports.
https://graph.windows.net/contoso.com/users/adam@contoso.com?$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.

$top$top

DirectoryRole または SubscribedSku ディレクトリ オブジェクトを対象にするクエリでは、$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.ページング結果を含む応答には、結果の次のページの取得を可能にする skip トークン (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.この skip トークンを 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
https://graph.windows.net/contoso.com/users?$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
https://graph.windows.net/contoso.com/users?$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 ユーザーの最後のページを示す skip トークンが含まれます。The response contains a skip token to indicate the final page of 10 users.
  2. 最後の 5 つのユーザーを取得するために、前の応答から返された skip トークンを含む別の要求が作成されます。To get the final 5 users, another request is made that contains the skip token returned from the previous response.
  3. 後方にページングするために、手順 1. で返された skip トークンを使用して要求が作成され、パラメーター &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.より多くのページが残る異なるシナリオでは、新しい skip トークンが返されます。In a different scenario where more pages are left, a new skip token would be returned.この新しい skip トークンを、&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.たとえば、https://graph.windows.net/contoso.com/users?api-version=1.6 と指定します。For example: https://graph.windows.net/contoso.com/users?api-version=1.6.ただし、すべての型を対象にしてフィルターを適用する場合は、ページングはサポートされず、結果の最初のページのみが返されます。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.たとえば、https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 と指定します。For example: https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.

並べ替え順序 Sort order

  • すべてのユーザーに対するクエリの結果セットは、UserPrincipalName プロパティに基づいて並べられます。The result set of a query for all users is ordered by the UserPrincipalName property.たとえば、https://graph.windows.net/contoso.com/users?api-version=1.6 と指定します。For example: https://graph.windows.net/contoso.com/users?api-version=1.6.
  • その他のすべてのトップ レベル リソースに対するクエリの結果セット (Groups、Contacts など) は、objectId プロパティに基づいて並べられます。The result set of a query for all other top-level resources, such as Groups, Contacts, etc. is ordered by the objectId property.たとえば、https://graph.windows.net/contoso.com/groups?api-version=1.6 と指定します。For example: https://graph.windows.net/contoso.com/groups?api-version=1.6.
  • トップレベル リソース以外を対象にするクエリの結果では、順序が不定になります。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

次のクエリでは、contoso.com をサンプル テナントとして使用して Graph API でトップ レベル リソースにアクセスする方法を示します。The following queries demonstrate how to access top-level resources with the Graph API using contoso.com as the example tenant.テナントに対してクエリを実行するには、Azure AD から受信した有効なベアラー トークンを含む Authorization ヘッダーが必要になります。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 (contoso.com の場合)URI (for contoso.com)
トップ レベル リソースTop-level resourcesディレクトリ サービスに対応するトップ レベル リソースの URI リストを返します (同じものを下にも記載してあります)Returns URI list of the top-level resources for directory services (also listed below)https://graph.windows.net/contoso.com?api-version=1.6
会社情報Company information会社情報を返しますReturns company informationhttps://graph.windows.net/contoso.com/tenantDetails?api-version=1.6
連絡先Contacts組織の連絡先情報を返しますReturns organizational contact informationhttps://graph.windows.net/contoso.com/contacts?api-version=1.6
UsersUsersユーザー情報を返しますReturns user informationhttps://graph.windows.net/contoso.com/users?api-version=1.6
[グループ]Groupsグループ データを返しますReturns group datahttps://graph.windows.net/contoso.com/groups?api-version=1.6
ディレクトリ ロールDirectory Rolesテナント内のアクティブ化されたディレクトリ ロールをすべて返しますReturns all activated directory roles in the tenanthttps://graph.windows.net/contoso.com/directoryRoles?api-version=1.6
SubscribedSkusSubscribedSkusテナントのサブスクリプションを返しますReturns the tenant's subscriptionshttps://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6
ディレクトリのメタデータDirectory metadataデータ モデルを記述したサービス メタデータ ドキュメント (つまり、ディレクトリ リソースの構造と編成) を返しますReturns a Service Metadata Document that describes the data model (that is, structure and organization of directory resources)https://graph.windows.net/contoso.com/$metadata?api-version=1.6

その他のクエリ操作Other query operations

次の表では、contoso.com をテナントとして使用した Graph API クエリの例をいくつか紹介します。The following table shows some additional example Graph API queries using contoso.com as the example tenant.

クエリ操作: Query OperationURI (contoso.com の場合)URI (for contoso.com)
ユーザーとグループをすべてリストしますList all Users and Groupshttps://graph.windows.net/contoso.com/users?api-version=1.6

https://graph.windows.net/contoso.com/groups?api-version=1.6
objectId または userPrincipalName を指定して、個々のユーザーを取得しますRetrieve individual User by specifying the objectId or userPrincipalNamehttps://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" に等しいユーザーを要求してフィルター処理しますRequest and Filter for a user with displayName equal to “Jon Doe”https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6
firstName が "Jon" に等しい特定のユーザーを要求してフィルター処理しますRequest and Filter for specific users with firstName equal to “Jon”https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6
givenName と surname の値を対象にしてフィルター処理します。Filter for givenName and surname values.https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6
objectId を指定して、個々のグループを取得しますRetrieve individual group by specifying the objectIdhttps://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6
ユーザーを指定し、そのユーザーの管理者を取得しますRetrieve a user’s managerhttps://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6
ユーザーの直属の部下一覧を取得します。Retrieve a user’s direct reports listhttps://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6
ユーザーの直属の部下に対応するリンクの一覧を取得しますRetrieve a list of links to a user’s direct reportshttps://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6
グループのメンバーシップの一覧を取得しますRetrieve membership list of a grouphttps://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6
グループのメンバーに対応するリンクの一覧を取得します。Retrieve a list of links to the members of a group.https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6
ユーザーのグループ メンバーシップを取得します (推移なし)Retrieve a user’s group membership (not transitive)https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6
ユーザーがメンバーになっているグループの一覧を取得します (推移なし)Retrieve a list of the groups that the user is a member of (not transitive)https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6
displayName >= "az" かつ <= "dz" というグループを要求してフィルター処理しますRequest and filter for groups with displayName >= "az" and <= "dz"https://graph.windows.net/contoso.com/groups?$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 tenanthttps://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6
Azure Active Directory B2C テナントから、サインイン名が "joe@example.com" のローカル アカウント ユーザーを返しますReturn local account user with the sign-in name "joe@example.com" from an Azure Active Directory B2C tenanthttps://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6

: クエリ文字列内の空白は、要求を送信する前に URL エンコードする必要があります。Note: White space in the query string should be URL-encoded before sending a request.たとえば、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 にエンコードされます。For example, the following query string, https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, should be URL encoded as: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.

その他のリソースAdditional resources

© 2018 Microsoft