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

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

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

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

  • eq 演算子で $filter クエリ パラメーターを使用します。 この要求は既定で機能します。つまり、要求は詳細クエリ パラメーターを必要としません。
GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled eq false
  • ne 演算子で $filter クエリ パラメーターを使用します。 ne 演算子は詳細クエリでのみサポートされているため、この要求は既定ではサポートされていません。 したがって、ConsistencyLevel ヘッダー セットを eventual に追加して、** $count=true クエリ文字列を使用する必要があります。
GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled ne true&$count=true
ConsistencyLevel: eventual

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

API/オブジェクト リレーションシップ
管理単位
  • members
  • アプリケーション
  • 所有者
  • 連絡先
  • memberOf
  • transitiveMemberOf
  • Devices
  • memberOf
  • transitiveMemberOf
  • registeredUsers
  • registeredOwners
  • グループ
  • members
  • transitiveMembers
  • memberOf
  • transitiveMemberOf
  • 所有者
  • appRoleAssignments
  • サービス プリンシパル
  • memberOf
  • transitiveMemberOf
  • appRoleAssignments
  • appRoleAssignmentsTo
  • oAuth2PermissionGrant
  • ユーザー
  • memberOf
  • transitiveMemberOf
  • ownedObjects
  • registeredDevices
  • ownedDevices
  • transitiveManagers
  • directReports
  • transitiveReports
  • appRoleAssignments
  • oAuth2PermissionGrant
  • 次の表に、詳細クエリでのみサポートされるディレクトリ オブジェクトのクエリ シナリオを示します。

    説明
    URL セグメントとしての $count の使用 GET ../groups/$count
    クエリ文字列パラメーターとしての $count の使用 GET ../servicePrincipals?$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
    別のクエリ パラメーターでキャストされた OData の使用 GET ../me/transitiveMemberOf/microsoft.graph.group?$count=true

    注意

    • $filter$orderByの併用は、高度なクエリでのみサポートされます。
    • $expand は、現在、高度なクエリではサポートされていません。
    • 現在、高度なクエリ機能は、Azure AD B2C テナントでは使用できません。

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

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

    • 既定でサポートされているクエリは高度なクエリでも機能しますが、最終的には応答が一貫したものになります。
    • in演算子は、eq演算子が既定でサポートされる場合はいつでも、既定でサポートされます。
    • endsWith演算子は、mailプロパティとuserPrincipalName プロパティに対する高度なクエリでのみサポートされます。
    • 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 値
    appId 既定でサポートされる サポート対象外
    applicationTemplateId 既定でサポートされる サポート対象外
    createdDateTime 既定でサポートされる 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    createdOnBehalfOf/deletedDateTime 既定でサポートされる 既定でサポートされる 既定でサポートされる サポート対象外
    description 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です サポート対象外
    disabledByMicrosoftStatus 既定でサポートされる サポート対象外
    displayName 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    info/logoUrl サポート対象外 サポート対象外 詳細クエリ パラメーターが必要です
    info/termsOfServiceUrl 詳細クエリ パラメーターが必要です サポート対象外 サポート対象外
    keyCredentials/any(k:k/endDateTime) 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です サポート対象外
    publisherDomain 既定でサポートされる 既定でサポートされる サポート対象外
    requiredResourceAccess/any(r:r/resourceAppId) 詳細クエリ パラメーターが必要です サポート対象外
    signInAudience 既定でサポートされる サポート対象外

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

    プロパティ eq startsWith ge le Null 値
    accountEnabled 既定でサポートされる サポート対象外
    appId 既定でサポートされる サポート対象外
    applicationTemplateId 既定でサポートされる サポート対象外
    appOwnerOrganizationId 詳細クエリ パラメーターが必要です サポート対象外
    appRoleAssignmentRequired 詳細クエリ パラメーターが必要です サポート対象外
    createdObjects/any(c:c/id) 詳細クエリ パラメーターが必要です サポート対象外
    description 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です サポート対象外
    displayName 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    info/logoUrl サポート対象外 サポート対象外 詳細クエリ パラメーターが必要です
    info/termsOfServiceUrl 詳細クエリ パラメーターが必要です サポート対象外 サポート対象外
    keyCredentials/any(k:k/endDateTime) 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です サポート対象外

    デバイス プロパティ

    プロパティ eq startsWith ge le Null 値
    accountEnabled 既定でサポートされる サポート対象外
    alternativeSecurityIds/any(a:a/identityProvider) 詳細クエリ パラメーターが必要です サポート対象外 サポート対象外
    alternativeSecurityIds/any(a:a/type) 既定でサポートされる 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です サポート対象外
    approximateLastSignInDateTime 既定でサポートされる 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    deviceId 既定でサポートされる サポート対象外
    extensionAttributes/extensionAttribute1-15 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です
    displayName 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    isCompliant 既定でサポートされる サポート対象外
    isManaged 既定でサポートされる サポート対象外
    mdmAppId 既定でサポートされる サポート対象外
    onPremisesLastSyncDateTime 既定でサポートされる 既定でサポートされる 既定でサポートされる サポート対象外
    onPremisesSyncEnabled 既定でサポートされる 詳細クエリ パラメーターが必要です
    operatingSystem 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    operatingSystemVersion 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です

    グループのプロパティ

    プロパティ eq startsWith ge le Null 値
    assignedLicenses/any(a:a/skuId) 既定でサポートされる サポート対象外
    classification 既定でサポートされる 既定でサポートされる サポート対象外
    createdOnBehalfOf/deletedDateTime 既定でサポートされる 既定でサポートされる 既定でサポートされる サポート対象外
    description 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です サポート対象外
    displayName 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    expirationDateTime 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です サポート対象外
    groupTypes 既定でサポートされる サポート対象外
    infoCatalogs 既定でサポートされる 既定でサポートされる 既定でサポートされる 既定でサポートされる
    mail 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    mailEnabled 既定でサポートされる サポート対象外
    mailNickname 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    membershipRule 既定でサポートされる 既定でサポートされる サポート対象外
    onPremisesLastSyncDateTime 既定でサポートされる 既定でサポートされる 既定でサポートされる サポート対象外
    onPremisesProvisioningErrors/any(o:o/category) 既定でサポートされる サポート対象外
    onPremisesProvisioningErrors/any(o:o/propertyCausingError) 既定でサポートされる サポート対象外
    onPremisesSamAccountName 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です サポート対象外
    onPremisesSecurityIdentifier サポート対象外 詳細クエリ パラメーターが必要です
    onPremisesSyncEnabled 既定でサポートされる 詳細クエリ パラメーターが必要です
    preferredLanguage 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です
    renewedDateTime 既定でサポートされる 既定でサポートされる 既定でサポートされる サポート対象外
    resourceProvisioningOptions (ベータ版のみ) 既定でサポートされる 既定でサポートされる
    securityEnabled 既定でサポートされる サポート対象外

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

    プロパティ eq startsWith ge le Null 値
    companyName 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です
    department 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    displayName 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    givenName 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    imAddresses 既定でサポートされる 既定でサポートされる 既定でサポートされる 既定でサポートされる
    jobTitle 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    mail 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    mailNickname 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    onPremisesLastSyncDateTime 既定でサポートされる 既定でサポートされる 既定でサポートされる サポート対象外
    onPremisesProvisioningErrors/any(o:o/category) 既定でサポートされる サポート対象外
    onPremisesProvisioningErrors/any(o:o/propertyCausingError) 既定でサポートされる サポート対象外
    onPremisesSyncEnabled 既定でサポートされる 詳細クエリ パラメーターが必要です
    surname 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です

    ユーザーのプロパティ

    プロパティ 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) 詳細クエリ パラメーターが必要です サポート対象外
    city 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    companyName 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です
    consentProvidedForMinor 既定でサポートされる サポート対象外
    country 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    createdDateTime 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です サポート対象外
    createdObjects/any(c:c/id) 詳細クエリ パラメーターが必要です サポート対象外
    creationType 既定でサポートされる サポート対象外
    department 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    displayName 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    employeeHireDate 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です サポート対象外
    employeeId 既定でサポートされる 詳細クエリ パラメーターが必要です
    employeeOrgData/costCenter 詳細クエリ パラメーターが必要です サポート対象外 サポート対象外
    employeeOrgData/division 詳細クエリ パラメーターが必要です サポート対象外 サポート対象外
    employeeType 詳細クエリ パラメーターが必要です サポート対象外
    externalUserState 既定でサポートされる サポート対象外
    externalUserStateChangeDateTime 既定でサポートされる 既定でサポートされる 既定でサポートされる サポート対象外
    faxNumber 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です
    givenName 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    ids/any(i:i/issuer) 既定でサポートされる サポート対象外 既定でサポートされる
    imAddresses 既定でサポートされる 既定でサポートされる 既定でサポートされる 既定でサポートされる
    infoCatalogs 既定でサポートされる 既定でサポートされる 既定でサポートされる 既定でサポートされる
    isResourceAccount 既定でサポートされる サポート対象外
    jobTitle 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    mail 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    mailNickname 既定でサポートされる 既定でサポートされる 詳細クエリ パラメーターが必要です
    manager/deletedDateTime 既定でサポートされる 既定でサポートされる 既定でサポートされる サポート対象外
    mobilePhone 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です
    officeLocation 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です
    onPremisesExtensionAttributes/extensionAttribute1-15 詳細クエリ パラメーターが必要です サポート対象外 詳細クエリ パラメーターが必要です
    onPremisesImmutableId 既定でサポートされる サポート対象外
    onPremisesLastSyncDateTime 既定でサポートされる 既定でサポートされる 既定でサポートされる サポート対象外
    onPremisesProvisioningErrors/any(o:o/category) 既定でサポートされる サポート対象外
    onPremisesProvisioningErrors/any(o:o/propertyCausingError) 既定でサポートされる サポート対象外
    onPremisesSamAccountName 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です サポート対象外
    onPremisesSecurityIdentifier サポート対象外 詳細クエリ パラメーターが必要です
    onPremisesSyncEnabled 既定でサポートされる 詳細クエリ パラメーターが必要です
    passwordPolicies サポート対象外 サポート対象外 詳細クエリ パラメーターが必要です
    passwordProfile/forceChangePasswordNextSignIn 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です
    passwordProfile/forceChangePasswordNextSignInWithMfa 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です
    postalCode 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です
    preferredLanguage 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です 詳細クエリ パラメーターが必要です
    provisionedPlans/any(p:p/provisioningStatus) 詳細クエリ パラメーターが必要です サポート対象外
    provisionedPlans/any(p:p/service) 詳細クエリ パラメーターが必要です サポート対象外 サポート対象外
    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/v1.0/users?$filter=id ge '398164b1-5196-49dd-ada2-364b49f99b27'&$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"
        },
      ]
    }
    

    関連項目