Azure AD ディレクトリオブジェクトの詳細クエリ機能

[アーティクル]
07/01/2022

Azure AD が安定性、可用性、パフォーマンスにおいてより多くの機能と改善を提供し続けるにつれて、Microsoft Graph も進化と拡張を続け、データに効率的にアクセスできるようになります。 1 つの方法は、さまざまな Azure AD オブジェクトとそのプロパティでの詳細クエリ機能に対する Microsoft Graph のサポートを増加することにより実現します。たとえば、 not (not)、not equals (ne)、ends with (endsWith) 演算子を$filter クエリパラメーターに追加します。

Microsoft Graph クエリエンジンは、インデックスストアを使用してクエリ要求を実行します。一部のプロパティでクエリ機能のサポートを追加するために、これらのプロパティは別のストアでインデックス付けされるようになりました。この個別のインデックス作成により、Azure AD はサポートを強化し、クエリ要求のパフォーマンスを向上させることができます。ただし、これらの高度なクエリ機能は既定では使用できませんが、要求者は ConsistencyLevel ヘッダーを eventual に設定する必要があります。ただし、$search を除いて、$count クエリパラメーターを使用します。 ConsistencyLevel ヘッダーと $count は、詳細クエリパラメーター と呼ばれます。

たとえば、非アクティブなユーザーアカウントのみを取得する場合は、$filter クエリパラメーターを使用するこれらのクエリのいずれかを実行できます。

オプション 1: eq 演算子で $filter クエリパラメーターを使用します。この要求は既定で機能します。つまり、要求は詳細クエリパラメーターを必要としません。

GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled eq false

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=CS
var user = await graphClient.Users.Request()
    .Filter("accountEnabled eq false")
    .GetAsync();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Javascript
let users = await client.api('/users')
  .filter('accountEnabled eq false')
  .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Objective-C
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users?$filter=accountEnabled eq false"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *usersDataTask = [httpClient dataTaskWithRequest:urlRequest
completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

  NSError *jsonError = nil;
  MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
  MSGraphUser *user = [[MSGraphUser alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[usersDataTask execute];

// See https://docs.microsoft.com/en-us/graph/sdks/create-client?tabs=Java
UserCollectionPage users = graphClient.users()
    .buildRequest()
    .filter("accountEnabled eq false")
    .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Go
requestParameters := &msgraphsdk.UsersRequestBuilderGetQueryParameters{
    Filter: "accountEnabled eq false",
}

options := &msgraphsdk.UsersRequestBuilderGetOptions{
    Q: requestParameters,
}

result, err := client.Users().Get(options)

Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "accountEnabled eq false"

オプション 2: ne 演算子で $filter クエリパラメーターを使用します。 ne 演算子は詳細クエリでのみサポートされているため、この要求は既定ではサポートされていません。したがって、ConsistencyLevel ヘッダーセットを eventual に追加して、** $count=true クエリ文字列を使用する必要があります。

GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled ne true&$count=true
ConsistencyLevel: eventual

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=CS
var user = await graphClient.Users.Request()
    .Request(new Option[] { new QueryOption("$count", "true")})
    .Header("ConsistencyLevel", "eventual")
    .Filter("accountEnabled ne true")
    .GetAsync();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Javascript
let users = await client.api('/users')
  .header('ConsistencyLevel','eventual')
  .filter('accountEnabled ne true')
  .count(true)
  .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Objective-C
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users?$filter=accountEnabled ne true&$count=true"]]];
[urlRequest setHTTPMethod:@"GET"];
[urlRequest setValue:@"eventual" forHTTPHeaderField:@"ConsistencyLevel"];

MSURLSessionDataTask *usersDataTask = [httpClient dataTaskWithRequest:urlRequest
completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

  NSError *jsonError = nil;
  MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
  MSGraphUser *user = [[MSGraphUser alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[usersDataTask execute];

// See https://docs.microsoft.com/en-us/graph/sdks/create-client?tabs=Java
LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("ConsistencyLevel", "eventual"));
requestOptions.add(new QueryOption("$count", "true"))

UserCollectionPage users = graphClient.users()
    .buildRequest(requestOptions)
    .filter("accountEnabled ne true")
    .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Go
requestParameters := &msgraphsdk.UsersRequestBuilderGetQueryParameters{
    Filter: "accountEnabled ne true",
    Count: true,
}

headers := map[string]string{
    "ConsistencyLevel": "eventual"
}

options := &msgraphsdk.UsersRequestBuilderGetOptions{
    Q: requestParameters,
    H: headers,
}

result, err := client.Users().Get(options)

Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "accountEnabled ne true" -CountVariable CountVar -ConsistencyLevel eventual

これらの高度なクエリ機能は、Azure AD ディレクトリオブジェクトと、以下の頻繁に使用されるオブジェクトを含む、そのリレーションシップのサブセットでのみサポートされます。

オブジェクト	リレーションシップ
administrativeUnit	members
application	所有者
appRoleAssignment	-
device	memberOf transitiveMemberOf registeredUsers registeredOwners
group	members transitiveMembers memberOf transitiveMemberOf 所有者 appRoleAssignments
oAuth2PermissionGrant (委任されたアクセス許可の付与)	-
orgContact	memberOf transitiveMemberOf
servicePrincipal	memberOf transitiveMemberOf appRoleAssignments appRoleAssignmentsTo oAuth2PermissionGrant
user	memberOf transitiveMemberOf ownedObjects registeredDevices ownedDevices transitiveManagers directReports transitiveReports appRoleAssignments oAuth2PermissionGrant

次の表に、詳細クエリでのみサポートされるディレクトリオブジェクトのクエリシナリオを示します。

説明	例
URL セグメントとしての `$count` の使用	GET `../groups/$count`
クエリ文字列パラメーターとしての `$count` の使用	GET `../servicePrincipals?$count=true`
`$filter`式での`$count`の使用	GET `../users?$filter=assignedLicenses/$count eq 0&$count=true`
`$search` の使用	GET `../applications?$search="displayName:Browser"`
一部のプロパティでの `$orderby` の使用	GET `../applications?$orderby=displayName&$count=true`
`endsWith` 演算子での `$filter` の使用	GET `../users?$count=true&$filter=endsWith(mail,'@outlook.com')`
同じクエリでの `$filter` と `$orderby` の使用	GET `../applications?$orderby=displayName&$filter=startsWith(displayName, 'Box')&$count=true`
特定のプロパティの `startsWith` 演算子での `$filter` の使用。	GET `../users?$filter=startsWith(mobilePhone, '25478') OR startsWith(mobilePhone, '25473')&$count=true`
`ne` および `not` 演算子と `$filter` の使用
GET `../users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true`
`not` および `startsWith` 演算子と `$filter` の使用
GET `../users?$filter=NOT startsWith(displayName, 'Conf')&$count=true`
`endsWith` 演算子を使用したコレクションにおける `$filter` の使用	GET `../users?$count=true&$filter=proxyAddresses/any(p:endsWith(p,+'OnMicrosoft.com'))&select=id,displayName,proxyaddresses`
遷移的なメンバーリストでの OData キャストの使用	GET `../me/transitiveMemberOf/microsoft.graph.group?$count=true`

注意

$filterと$orderByの併用は、高度なクエリでのみサポートされます。
$expand は、現在、高度なクエリではサポートされていません。
現在、高度なクエリ機能は、Azure AD B2C テナントでは使用できません。
バッチ要求で高度なクエリ機能を使用するには、POST 要求の JSON 本文で ConsistencyLevel ヘッダーを指定します。

Azure AD ディレクトリオブジェクトのプロパティでのフィルターのサポート

ディレクトリオブジェクトのプロパティは、クエリパラメーターのサポートにおいて異なる動作をします。ディレクトリオブジェクトの一般的なシナリオは次のとおりです。

既定でサポートされているクエリは高度なクエリでも機能しますが、最終的には応答が一貫したものになります。
in演算子は、eq演算子が既定でサポートされる場合はいつでも、既定でサポートされます。
endsWith 演算子は、 メール、 otherMails、 userPrincipalName、 proxyAddresses プロパティに対する高度なクエリでのみサポートされます。
not演算子とne否定演算子は、高度なクエリでのみサポートされます。
- eq 演算子をサポートするすべてのプロパティは、ne または not 演算子もサポートします。
- any ラムダ演算子を使用するクエリの場合は、not 演算子を使用します。「ラムダ演算子を使用したフィルター」を参照してください。

次の表は、高度なクエリ機能でサポートされているディレクトリオブジェクトのプロパティによる $filter 演算子のサポートについてまとめたものです。

凡例

$filter演算子は、そのプロパティに対して既定で機能します。
$filter演算子 には、以下の 高度なクエリパラメーター が必要です。
- ConsistencyLevel=eventual ヘッダー
- $count=true クエリ文字列
$filter演算子は、そのプロパティではサポートされていません。 [フィードバックを送信] して、このプロパティがシナリオに $filter をサポートすることを要求します。
空白のセルは、クエリがそのプロパティに対して無効であることを示します。
null 値 列は、プロパティが null 許容であり、nullを使用してフィルター可能であることを示します。
ここに記載されていないプロパティは、 $filter をまったくサポートしていません。

管理単位のプロパティ

プロパティ名	eq	startsWith	ge	le	Null 値
description
displayName
isMemberManagementRestricted

アプリケーションのプロパティ

プロパティ名	eq	startsWith	ge	le	Null 値
appId
createdDateTime
createdOnBehalfOf/deletedDateTime
createdOnBehalfOf/id
description
disabledByMicrosoftStatus
displayName
identifierUris/any(p:p)
info/logoUrl
info/termsOfServiceUrl
publicClient/redirectUris/any(p:p)
publisherDomain
requiredResourceAccess/any(r:r/resourceAppId)
serviceManagementReference
signInAudience
spa/redirectUris/any(p:p)
tags/any(p:p)
uniqueName
verifiedPublisher/displayName
web/homePageUrl
web/redirectUris/any(p:p)

デバイスプロパティ

プロパティ名	eq	startsWith	ge	le	Null 値
accountEnabled
alternativeSecurityIds/any(a:a/identityProvider)
alternativeSecurityIds/any(a:a/type)
approximateLastSignInDateTime
deviceId
displayName
extensionAttributes1-15
hostnames/any(p:p)
isCompliant
isManaged
mdmAppId
onPremisesLastSyncDateTime
onPremisesSyncEnabled
operatingSystem
operatingSystemVersion
physicalIds/any(p:p)
registrationDateTime

グループのプロパティ

プロパティ名	eq	startsWith	ge	le	Null 値
assignedLicenses/any(a:a/skuId)
classification
createdByAppId
createdOnBehalfOf/deletedDateTime
createdOnBehalfOf/id
description
displayName
expirationDateTime
hasMembersWithLicenseErrors
infoCatalogs/any(p:p)
isAssignableToRole
mail
mailEnabled
mailNickname
membershipRule
onPremisesLastSyncDateTime
onPremisesProvisioningErrors/any(o:o/category)
onPremisesProvisioningErrors/any(o:o/propertyCausingError)
onPremisesSamAccountName
onPremisesSecurityIdentifier
onPremisesSyncEnabled
preferredLanguage
proxyAddresses/any(p:p)
renewedDateTime
resourceBehaviorOptions/any(p:p)
resourceProvisioningOptions/any(p:p)
securityEnabled

組織の連絡先のプロパティ

プロパティ名	eq	startsWith	ge	le	Null 値
CompanyName
department
displayName
givenName
jobTitle
mail
mailNickname
manager/id
onPremisesLastSyncDateTime
onPremisesProvisioningErrors/any(o:o/category)
onPremisesProvisioningErrors/any(o:o/propertyCausingError)
onPremisesSyncEnabled
proxyAddresses/any(p:p)
surname

サービスプリンシパルのプロパティ

プロパティ名	eq	startsWith	ge	le	Null 値
accountEnabled
alternativeNames/any(p:p)
appId
appOwnerOrganizationId
appRoleAssignmentRequired
applicationTemplateId
createdObjects/any(c:c/id)
description
displayName
HomePage
info/logoUrl
info/termsOfServiceUrl
preferredTokenSigningKeyEndDateTime
publisherName
servicePrincipalNames/any(p:p)
tags/any(p:p)

ユーザーのプロパティ

プロパティ名	eq	startsWith	ge	le	Null 値
accountEnabled
ageGroup
assignedLicenses/any(a:a/skuId)
assignedPlans/any(a:a/capabilityStatus)
assignedPlans/any(a:a/service)
assignedPlans/any(a:a/servicePlanId)
businessPhones/any(p:p)
city
CompanyName
consentProvidedForMinor
country
createdDateTime
createdObjects/any(c:c/id)
creationType
department
displayName
employeeHireDate
employeeId
employeeOrgData/costCenter
employeeOrgData/division
employeeType
externalUserState
faxNumber
givenName
ids/any(i:i/issuer)
imAddresses/any(p:p)
infoCatalogs/any(p:p)
isResourceAccount
jobTitle
mail
mailNickname
manager/deletedDateTime
manager/id
mobilePhone
officeLocation
onPremisesExtensionAttributes/extensionAttribute1-15
onPremisesImmutableId
onPremisesLastSyncDateTime
onPremisesProvisioningErrors/any(o:o/category)
onPremisesProvisioningErrors/any(o:o/propertyCausingError)
onPremisesSamAccountName
onPremisesSecurityIdentifier
onPremisesSyncEnabled
onPremisesUserPrincipalName
otherMails/any(p:p)
passwordPolicies
passwordProfile/forceChangePasswordNextSignIn
passwordProfile/forceChangePasswordNextSignInWithMfa
postalCode
preferredLanguage
provisionedPlans/any(p:p/provisioningStatus)
provisionedPlans/any(p:p/service)
proxyAddresses/any(p:p)
showInAddressList
state
streetAddress
surname
usageLocation
userPrincipalName
userType

ディレクトリオブジェクトの詳細クエリに対するエラー処理

ディレクトリオブジェクトのカウントは、詳細クエリパラメーターの使用でのみサポートされます。ConsistencyLevel=eventual ヘッダーが指定されていない場合、要求は、$count URL セグメントが使用されているときエラーを返し、$count クエリパラメーター (?$count=true) が使用されているときサイレントに無視します。

https://graph.microsoft.com/v1.0/users/$count

{
    "error": {
        "code": "Request_BadRequest",
        "message": "$count is not currently supported.",
        "innerError": {
            "date": "2021-05-18T19:03:10",
            "request-id": "d9bbd4d8-bb2d-44e6-99a1-71a9516da744",
            "client-request-id": "539da3bd-942f-25db-636b-27f6f6e8eae4"
        }
    }
}

ディレクトリオブジェクトの場合、 $search は高度なクエリでのみ機能します。 ConsistencyLevel ヘッダーが指定されていない場合、要求はエラーを返します。

https://graph.microsoft.com/v1.0/applications?$search="displayName:Browser"

{
    "error": {
        "code": "Request_UnsupportedQuery",
        "message": "Request with $search query parameter only works through MSGraph with a special request header: 'ConsistencyLevel: eventual'",
        "innerError": {
            "date": "2021-05-27T14:26:47",
            "request-id": "9b600954-ba11-4899-8ce9-6abad341f299",
            "client-request-id": "7964ef27-13a3-6ca4-ed7b-73c271110867"
        }
    }
}

URL のプロパティまたはクエリパラメーターが詳細クエリでのみサポートされているが、ConsistencyLevel ヘッダーまたは $count=true クエリ文字列のいずれかが欠落している場合、要求はエラーを返します。

https://graph.microsoft.com/v1.0/users?$filter=endsWith(mail,'@outlook.com')

{
    "error": {
        "code": "Request_UnsupportedQuery",
        "message": "Unsupported Query.",
        "innerError": {
            "date": "2021-05-18T19:12:36",
            "request-id": "63f2093c-399c-4350-9609-3ce9b62abe3c",
            "client-request-id": "e60ed0ba-df5d-e190-f056-f9c0318456d7"
        }
    }
}

クエリパラメーターをサポートするようにプロパティにインデックスが付けられていない場合、詳細クエリパラメーターが指定されていても、要求はエラーを返します。

https://graph.microsoft.com/beta/groups?$filter=createdDateTime ge 2021-11-01&$count=true
ConsistencyLevel: eventual

{
    "error": {
        "code": "Request_UnsupportedQuery",
        "message": "The request uses a filter property that is not indexed",
        "innerError": {
            "date": "2021-06-10T19:32:01",
            "request-id": "5625ba13-0c9f-4fce-a853-4b52f3e0bd09",
            "client-request-id": "76fe4cd8-df3a-f8c3-659b-594274b6bb31"
        }
    }
}

ただし、要求で指定されたクエリパラメーターが警告なしで失敗する可能性があるため、注意が必要です。これは、クエリパラメーターがサポートされていない場合や、クエリパラメーターの組み合わせがサポートされていない場合に起こり得ます。その場合、要求によって返されたデータを調べ、指定したクエリパラメーターに期待どおりの効果があったかどうかを確認する必要があります。たとえば、次の例では、クエリが成功の場合でも @odata.count パラメーターが欠落しています。

https://graph.microsoft.com/v1.0/users?$count=true

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "value":[
    {
      "displayName":"Oscar Ward",
      "mail":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"
    },
  ]
}

Azure AD ディレクトリ オブジェクトの詳細クエリ機能

Azure AD ディレクトリ オブジェクトのプロパティでのフィルターのサポート

凡例

管理単位のプロパティ

アプリケーションのプロパティ

デバイス プロパティ

グループのプロパティ

組織の連絡先のプロパティ

サービス プリンシパルのプロパティ

ユーザーのプロパティ

ディレクトリ オブジェクトの詳細クエリに対するエラー処理

関連項目

フィードバック

Azure AD ディレクトリオブジェクトの詳細クエリ機能

Azure AD ディレクトリオブジェクトのプロパティでのフィルターのサポート

デバイスプロパティ

サービスプリンシパルのプロパティ

ディレクトリオブジェクトの詳細クエリに対するエラー処理