Microsoft Entra ID オブジェクトの高度なクエリ機能

  • [アーティクル]

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

Microsoft Graph クエリ エンジンは、インデックス ストアを使用してクエリ要求を実行します。 一部のプロパティでクエリ機能のサポートを追加するために、これらのプロパティは別のストアでインデックス付けされるようになりました。 この個別のインデックス作成により、Microsoft Entra ID はサポートを強化し、クエリ要求のパフォーマンスを向上させることができます。 ただし、これらの高度なクエリ機能は既定では使用できませんが、要求者は 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 (ディレクトリ) オブジェクト

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

オブジェクト リレーションシップ
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, '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 演算子は、 mail、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 演算子には、次の高度なクエリ パラメーターが必要です。
      • ConsistencyLevel=eventual ヘッダー
      • $count=true クエリ文字列
    • サポートされていません。$filter 演算子は、そのプロパティではサポートされません。 [フィードバックを送信] して、このプロパティがシナリオに $filter をサポートすることを要求します。
    • 空白のセルは、クエリがそのプロパティに対して無効であることを示します。
    • null 値列は、プロパティが null 許容であり、nullを使用してフィルター可能であることを示します。
    • ここに記載されていないプロパティは、$filter を一切サポートしました。

    管理単位のプロパティ

    プロパティ eq startsWith eq Null
    説明
    displayName
    isMemberManagementRestricted
    membershipRule
    membershipRuleProcessingState
    scopedRoleMembers/any(s:s/id)

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

    プロパティ eq startsWith ge/le eq Null
    appId
    createdDateTime
    createdOnBehalfOf/id
    説明
    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
    appRoleAssignments/any(a:a/id)
    assignedLicenses/any(a:a/skuId)
    classification
    createdByAppId
    createdOnBehalfOf/id
    説明
    displayName
    expirationDateTime
    hasMembersWithLicenseErrors
    infoCatalogs/any(p:p)
    isAssignableToRole
    mail
    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
    settings/any(s:s/displayName)
    settings/any(s:s/id)
    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
    mail
    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
    appRoleAssignedTo/any(a:a/id)
    appRoleAssignmentRequired
    appRoleAssignments/any(a:a/id)
    applicationTemplateId
    createdObjects/any(c:c/id)
    delegatedPermissionClassifications/any(d:d/id)
    説明
    displayName
    federatedIdentityCredentials/any(f:f/issuer)
    federatedIdentityCredentials/any(f:f/name)
    federatedIdentityCredentials/any(f:f/subject)
    HomePage
    info/logoUrl
    info/termsOfServiceUrl
    notes
    oauth2PermissionGrants/any(o:o/id)
    preferredSingleSignOnMode
    preferredTokenSigningKeyEndDateTime
    publisherName
    remoteDesktopSecurityConfiguration/id
    remoteDesktopSecurityConfiguration/targetDeviceGroups/any(t:t/displayName)
    remoteDesktopSecurityConfiguration/targetDeviceGroups/any(t:t/id)
    servicePrincipalNames/any(p:p)
    servicePrincipalType
    tags/any(p:p)
    verifiedPublisher/displayName

    servicePrincipal エンティティの次のプロパティは、フィルター式でのコレクションの $count をサポートしています。

    プロパティ eq Count 0 eq Count 1
    federatedIdentityCredentials/$count
    ownedObjects/$count

    ユーザーのプロパティ

    プロパティ eq startsWith ge/le eq Null
    accountEnabled
    ageGroup
    appRoleAssignments/any(a:a/id)
    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
    licenseDetails/any(l:l/id)
    mail
    mailNickname
    manager/id
    mobilePhone
    oauth2PermissionGrants/any(o:o/id)
    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)
    scopedRoleMemberOf/any(s:s/id)
    showInAddressList
    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
    グループ deletedDateTime
    グループ displayName
    servicePrincipal createdDateTime
    servicePrincipal deletedDateTime
    servicePrincipal displayName
    ユーザー createdDateTime
    ユーザー deletedDateTime
    ユーザー displayName
    ユーザー userPrincipalName
    [その他] [その他]

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

    ディレクトリ オブジェクトのカウントは、詳細クエリ パラメーターの使用でのみサポートされます。 ConsistencyLevel=eventual ヘッダーが指定されていない場合、要求は、$count URL セグメントが使用されているときエラーを返し、$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"
        }
    }
}

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

    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"
    }
  ]
}

    関連コンテンツ