Microsoft Entra ID オブジェクトの高度なクエリ機能
Microsoft Graph では、データへの効率的なアクセスに役立つ、ディレクトリ オブジェクトとも呼ばれるさまざまなMicrosoft Entra ID オブジェクトに対する高度なクエリ機能がサポートされています。 たとえば、 not (not
)、not equals (ne
)、ends with (endsWith
) 演算子を$filter
クエリ パラメーターに追加します。
Microsoft Graph クエリ エンジンは、インデックス ストアを使用してクエリ要求を実行します。 一部のプロパティに対する追加のクエリ機能のサポートを追加するために、これらのプロパティは別のストアでインデックスが作成される場合があります。 この個別のインデックス作成により、クエリのパフォーマンスが向上します。 ただし、これらの高度なクエリ機能は既定では使用できませんが、リクエスタは ConsistencyLevel ヘッダーを eventual
に設定する必要があります。ただし、$search
を除き、$count
クエリ パラメーターを使用します。
ConsistencyLevel ヘッダーと $count
は、詳細クエリ パラメーターと呼ばれます。
たとえば、非アクティブなユーザー アカウントのみを取得する場合は、$filter
クエリ パラメーターを使用するこれらのクエリのいずれかを実行できます。
オプション 1:eq
演算子で $filter
クエリ パラメーターを使用します。 この要求は既定で機能し、高度なクエリ パラメーターは必要ありません。
GET https://graph.microsoft.com/v1.0/users?$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
高度なクエリ機能をサポートする Microsoft Entra ID (ディレクトリ) オブジェクト
高度なクエリ機能は、ディレクトリ オブジェクトとそのリレーションシップ (次のオブジェクトを含む) でのみサポートされます。
高度なクエリ機能を必要とするクエリ シナリオ
次の表に、詳細クエリでのみサポートされるディレクトリ オブジェクトのクエリ シナリオを示します。
説明 | 例 |
---|---|
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, 'contoso.com'))&$select=id,displayName,proxyaddresses |
遷移的なメンバーリストでの OData キャストの使用 |
GET~/me/transitiveMemberOf/microsoft.graph.group?$count=true |
注:
-
$filter
と$orderby
の併用は、高度なクエリでのみサポートされます。 -
$expand
は、現在、高度なクエリではサポートされていません。 - 現在、高度なクエリ機能は、Azure AD B2C テナントでは使用できません。
-
バッチ要求で高度なクエリ機能を使用するには、
POST
要求の JSON 本文で ConsistencyLevel ヘッダーを指定します。
Microsoft Entra ID (ディレクトリ) オブジェクトのプロパティによるフィルターのサポート
ディレクトリ オブジェクトのプロパティは、クエリ パラメーターのサポートにおいて異なる動作をします。 ディレクトリ オブジェクトの一般的なシナリオは次のとおりです。
-
in
演算子は、eq
演算子が既定でサポートされる場合はいつでも、既定でサポートされます。 -
endswith
演算子は、高度なクエリ パラメーターでのみサポートされ、メール、otherMails、userPrincipalName、proxyAddresses プロパティでのみサポートされます。 - 空のコレクション (
/$count eq 0
、/$count ne 0
) と 1 つ未満のオブジェクトを持つコレクション (/$count eq 1
、/$count ne 1
) の取得は、高度なクエリ パラメーターでのみサポートされます。 -
not
およびne
否定演算子は、高度なクエリ パラメーターでのみサポートされます。-
eq
演算子をサポートするすべてのプロパティは、ne
またはnot
演算子もサポートします。 -
any
ラムダ演算子を使用するクエリの場合は、not
演算子を使用します。 「ラムダ演算子を使用したフィルター」を参照してください。
-
次の表は、ディレクトリ オブジェクトのプロパティによる $filter
演算子のサポートをまとめたものであり、高度なクエリ機能を使用したクエリがサポートされる場所を示しています。
凡例
-
$filter
演算子は、そのプロパティに対して既定で機能します。 -
$filter
演算子は、高度なクエリ パラメーターなしでのみ機能します。 -
$filter
演算子には、次の高度なクエリ パラメーターが必要です。-
ConsistencyLevel=eventual
ヘッダー -
$count=true
クエリ文字列
-
-
$filter
演算子は、そのプロパティではサポートされません。 [フィードバックを送信] して、このプロパティがシナリオに$filter
をサポートすることを要求します。 - 空白のセルは、クエリがそのプロパティに対して無効であることを示します。
-
null 値列は、プロパティが null 許容であり、
null
を使用してフィルター可能であることを示します。 - ここに記載されていないプロパティは、
$filter
を一切サポートしました。
管理単位のプロパティ
プロパティ | eq | startsWith | eq Null |
---|---|---|---|
説明 |
|
|
|
displayName |
|
|
|
isMemberManagementRestricted |
|
||
membershipRule |
|
|
|
membershipRuleProcessingState |
|
アプリケーションのプロパティ
プロパティ | eq | startsWith | ge/le | eq Null |
---|---|---|---|---|
appId |
|
|||
createdDateTime |
|
|
||
説明 |
|
|
|
|
disabledByMicrosoftStatus |
|
|||
displayName |
|
|
|
|
federatedIdentityCredentials/any(f:f/issuer) |
|
|
||
federatedIdentityCredentials/any(f:f/name) |
|
|
||
federatedIdentityCredentials/any(f:f/subject) |
|
|
||
identifierUris/any(p:p) |
|
|
||
info/logoUrl |
|
|||
info/termsOfServiceUrl |
|
|
||
notes |
|
|
|
|
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) |
|
|
アプリケーション エンティティの次のプロパティは、フィルター式でのコレクションの $count
をサポートしています。
プロパティ | eq Count 0 | eq Count 1 |
---|---|---|
extensionProperties/$count |
|
|
federatedIdentityCredentials/$count |
|
|
コントラクト プロパティ
プロパティ | eq | startsWith |
---|---|---|
customerId |
|
|
defaultDomainName |
|
|
displayName |
|
|
デバイス プロパティ
プロパティ | eq | startsWith | ge/le | eq Null |
---|---|---|---|---|
accountEnabled |
|
|||
alternativeSecurityIds/any(a:a/identityProvider) |
|
|
||
alternativeSecurityIds/any(a:a/type) |
|
|||
approximateLastSignInDateTime |
|
|
||
deviceCategory |
|
|
|
|
deviceId |
|
|||
deviceOwnership |
|
|
||
displayName |
|
|
|
|
enrollmentProfileName |
|
|
|
|
extensionAttributes/extensionAttribute1-15 |
|
|
|
|
hostnames/any(p:p) |
|
|
||
isCompliant |
|
|||
isManaged |
|
|||
isRooted |
|
|
||
managementType |
|
|
||
manufacturer |
|
|
|
|
mdmAppId |
|
|
||
model |
|
|
|
|
onPremisesLastSyncDateTime |
|
|||
onPremisesSecurityIdentifier |
|
|
||
onPremisesSyncEnabled |
|
|
||
operatingSystem |
|
|
|
|
operatingSystemVersion |
|
|
|
|
physicalIds/any(p:p) |
|
|||
profileType |
|
|||
registrationDateTime |
|
|
||
trustType |
|
device エンティティの次のプロパティは、フィルター式でのコレクションの $count
をサポートしています。
プロパティ | eq Count 0 | eq Count 1 |
---|---|---|
physicalIds/$count |
|
|
systemLabels/$count |
|
|
ディレクトリ ロールのプロパティ
プロパティ | eq | startsWith | eq Null |
---|---|---|---|
説明 |
|
|
|
displayName |
|
|
|
roleTemplateId |
|
|
グループのプロパティ
プロパティ | eq | startsWith | ge/le | eq Null |
---|---|---|---|---|
assignedLicenses/any(a:a/skuId) |
|
|||
classification |
|
|
||
createdByAppId |
|
|||
createdDateTime |
|
|
||
説明 |
|
|
|
|
displayName |
|
|
|
|
expirationDateTime |
|
|||
groupTypes/any(p:p) |
|
|||
hasMembersWithLicenseErrors |
|
|
||
infoCatalogs/any(p:p) |
|
|
||
isAssignableToRole |
|
|||
|
|
|
||
mailEnabled |
|
|||
mailNickname |
|
|
|
|
membershipRule |
|
|
||
membershipRuleProcessingState |
|
|||
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 |
|
|||
uniqueName |
|
|
group エンティティの次のプロパティは、フィルター式でのコレクションの $count
をサポートしています。
プロパティ | eq Count 0 | eq Count 1 |
---|---|---|
assignedLicenses/$count |
|
|
onPremisesProvisioningErrors/$count |
|
|
proxyAddresses/$count |
|
|
組織の連絡先のプロパティ
プロパティ | eq | startsWith | ge/le | eq Null |
---|---|---|---|---|
CompanyName |
|
|
|
|
department |
|
|
|
|
displayName |
|
|
|
|
givenName |
|
|
|
|
jobTitle |
|
|
|
|
|
|
|
||
mailNickname |
|
|
|
|
manager/id |
|
|||
onPremisesLastSyncDateTime |
|
|||
onPremisesProvisioningErrors/any(o:o/category) |
|
|||
onPremisesProvisioningErrors/any(o:o/propertyCausingError) |
|
|||
onPremisesSyncEnabled |
|
|
||
proxyAddresses/any(p:p) |
|
|
||
surname |
|
|
|
orgContact エンティティの次のプロパティは、フィルター式でのコレクションの $count
をサポートしています。
プロパティ | eq Count 0 | eq Count 1 |
---|---|---|
onPremisesProvisioningErrors/$count |
|
|
proxyAddresses/$count |
|
|
サービス プリンシパルのプロパティ
プロパティ | eq | startsWith | ge/le | eq Null |
---|---|---|---|---|
accountEnabled |
|
|||
alternativeNames/any(p:p) |
|
|
||
appId |
|
|||
appOwnerOrganizationId |
|
|||
appRoleAssignmentRequired |
|
|||
applicationTemplateId |
|
|||
claimsPolicy/id |
|
|||
createdObjects/any(c:c/id) |
|
|||
説明 |
|
|
|
|
displayName |
|
|
|
|
federatedIdentityCredentials/any(f:f/issuer) |
|
|
||
federatedIdentityCredentials/any(f:f/name) |
|
|
||
federatedIdentityCredentials/any(f:f/subject) |
|
|
||
HomePage |
|
|
|
|
info/logoUrl |
|
|||
info/termsOfServiceUrl |
|
|
||
notes |
|
|
|
|
preferredSingleSignOnMode |
|
|||
preferredTokenSigningKeyEndDateTime |
|
|||
publisherName |
|
|
||
remoteDesktopSecurityConfiguration/id |
|
|||
servicePrincipalNames/any(p:p) |
|
|
||
servicePrincipalType |
|
|||
tags/any(p:p) |
|
|
||
verifiedPublisher/displayName |
|
|
|
servicePrincipal エンティティの次のプロパティは、フィルター式でのコレクションの $count
をサポートしています。
プロパティ | eq Count 0 | eq Count 1 |
---|---|---|
federatedIdentityCredentials/$count |
|
|
ユーザーのプロパティ
プロパティ | eq | startsWith | ge/le | eq Null |
---|---|---|---|---|
accountEnabled |
|
|||
ageGroup |
|
|||
assignedLicenses/any(a:a/skuId) |
|
|||
assignedPlans/any(a:a/capabilityStatus) |
|
|||
assignedPlans/any(a:a/service) |
|
|
||
assignedPlans/any(a:a/servicePlanId) |
|
|||
authorizationInfo/certificateUserIds/any(p:p) |
|
|||
businessPhones/any(p:p) |
|
|
||
city |
|
|
|
|
cloudRealtimeCommunicationInfo/isSipEnabled |
|
|||
CompanyName |
|
|
|
|
consentProvidedForMinor |
|
|||
country |
|
|
|
|
createdDateTime |
|
|
||
createdObjects/any(c:c/id) |
|
|||
creationType |
|
|||
department |
|
|
|
|
displayName |
|
|
|
|
employeeHireDate |
|
|||
employeeId |
|
|
||
employeeOrgData/costCenter |
|
|
||
employeeOrgData/division |
|
|
||
employeeType |
|
|||
externalUserState |
|
|||
faxNumber |
|
|
|
|
givenName |
|
|
|
|
identities/any(i:i/issuer) |
|
|
||
imAddresses/any(p:p) |
|
|
||
infoCatalogs/any(p:p) |
|
|
||
isLicenseReconciliationNeeded |
|
|||
isResourceAccount |
|
|||
jobTitle |
|
|
|
|
|
|
|
||
mailNickname |
|
|
|
|
mobilePhone |
|
|
|
|
officeLocation |
|
|
|
|
onPremisesDistinguishedName |
|
|
|
|
onPremisesExtensionAttributes/extensionAttribute1-15 |
|
|
|
|
onPremisesImmutableId |
|
|||
onPremisesLastSyncDateTime |
|
|||
onPremisesProvisioningErrors/any(o:o/category) |
|
|||
onPremisesProvisioningErrors/any(o:o/propertyCausingError) |
|
|||
onPremisesSamAccountName |
|
|
||
onPremisesSecurityIdentifier |
|
|
||
onPremisesSipInfo/isSipEnabled |
|
|||
onPremisesSyncEnabled |
|
|
||
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) |
|
|
||
state |
|
|
||
streetAddress |
|
|
|
|
surname |
|
|
|
|
usageLocation |
|
|
|
|
userPrincipalName |
|
|
||
userType |
|
|
user エンティティの次のプロパティは、フィルター式でのコレクションの $count
をサポートしています。
プロパティ | eq Count 0 | eq Count 1 |
---|---|---|
assignedLicenses/$count |
|
|
onPremisesProvisioningErrors/$count |
|
|
otherMails/$count |
|
|
ownedObjects/$count |
|
|
proxyAddresses/$count |
|
|
次の表は、user オブジェクトの他の拡張プロパティによる $filter
のサポートを示しています。
拡張機能の種類 | eq | startsWith | eq null |
---|---|---|---|
スキーマ拡張機能 |
|
|
|
Open extensions |
|
|
|
ディレクトリ拡張機能 |
|
|
|
Microsoft Entra ID (ディレクトリ) オブジェクトのプロパティによる並べ替えのサポート
次の表は、ディレクトリ オブジェクトのプロパティによる $orderby
のサポートをまとめたものであり、高度なクエリ機能を使用した並べ替えがサポートされる場所を示しています。
凡例
-
$orderby
演算子は、そのプロパティに対して既定で機能します。 -
$orderby
演算子には、次の高度なクエリ パラメーターが必要です。-
ConsistencyLevel=eventual
ヘッダー -
$count=true
クエリ文字列
-
- ディレクトリ オブジェクトに対する同じクエリで
$filter
と$orderby
を使用するには、常に高度なクエリ パラメーターが必要です。 詳細については、「高度なクエリ機能を必要とするクエリ シナリオ」を参照してください。
ディレクトリ オブジェクト | プロパティ名 | $orderby |
---|---|---|
administrativeUnit | createdDateTime |
|
administrativeUnit | deletedDateTime |
|
administrativeUnit | displayName |
|
アプリケーション | createdDateTime |
|
アプリケーション | deletedDateTime |
|
アプリケーション | displayName |
|
orgContact | createdDateTime |
|
orgContact | displayName |
|
デバイス | approximateLastSignInDateTime |
|
デバイス | createdDateTime |
|
デバイス | deletedDateTime |
|
デバイス | displayName |
|
グループ | createdDateTime |
|
グループ | deletedDateTime |
|
グループ | displayName |
|
servicePrincipal | createdDateTime |
|
servicePrincipal | deletedDateTime |
|
servicePrincipal | displayName |
|
ユーザー | createdDateTime |
|
ユーザー | deletedDateTime |
|
ユーザー | displayName |
|
ユーザー | userPrincipalName |
|
[その他] | [その他] |
|
ディレクトリ オブジェクトの詳細クエリに対するエラー処理
次のセクションでは、必要に応じて高度なクエリ パラメーターを使用しない場合の一般的なエラー シナリオの例を示します。
ディレクトリ オブジェクトのカウントは、詳細クエリ パラメーターの使用でのみサポートされます。
ConsistencyLevel=eventual
ヘッダーが指定されていない場合、要求は、$count
URL セグメント (/$count
) が使用されている場合にエラーを返すか、使用されている場合は$count
クエリ パラメーター (?$count=true
) を自動的に無視します。
GET 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 ヘッダーが指定されていない場合、要求はエラーを返します。
GET 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
クエリ文字列のいずれかが欠落している場合、要求はエラーを返します。
GET https://graph.microsoft.com/beta/users?$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')
{
"error": {
"code": "Request_UnsupportedQuery",
"message": "Operator 'endsWith' is not supported because the required parameters might be missing. Try adding $count=true query parameter and ConsistencyLevel:eventual header. Refer to https://aka.ms/graph-docs/advanced-queries for more information",
"innerError": {
"date": "2023-07-14T08:43:39",
"request-id": "b3731da7-5c46-4c37-a8e5-b190124d2531",
"client-request-id": "a1556ddf-4794-929d-0105-b753a78b4c68"
}
}
}
クエリ パラメーターをサポートするためにプロパティのインデックスが作成されていない場合、高度なクエリ パラメーターが指定されている場合でも、要求はエラーを返します。 たとえば、グループ リソースの createdDateTime プロパティにはクエリ機能のインデックスが作成されません。
GET https://graph.microsoft.com/beta/groups?$filter=createdDateTime ge 2021-11-01&$count=true
ConsistencyLevel: eventual
{
"error": {
"code": "Request_UnsupportedQuery",
"message": "Unsupported or invalid query filter clause specified for property 'createdDateTime' of resource 'Group'.",
"innerError": {
"date": "2023-07-14T08:42:44",
"request-id": "b6a5f998-94c8-430d-846d-2eaae3031492",
"client-request-id": "2be83e05-649e-2508-bcd9-62e666168fc8"
}
}
}
ただし、クエリ パラメーターを含む要求は、サイレントに失敗する可能性があります。 たとえば、クエリ パラメーターがサポートされていない場合や、クエリ パラメーターの組み合わせがサポートされていない場合です。 その場合、要求によって返されたデータを調べ、指定したクエリ パラメーターに期待どおりの効果があったかどうかを確認してください。 たとえば、次の例では、クエリが成功の場合でも @odata.count
パラメーターが欠落しています。
GET 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"
}
]
}