プッシュ REST API を使用したドキュメント アクセス制御リスト (ACL) のインデックス作成 (プレビュー)

プッシュ REST API (プレビュー) を使用したドキュメント レベルのアクセス許可インジェストを使用すると、関連する アクセス制御リスト (ACL) ロール とコンテナー ロールベースのアクセス制御 (RBAC) ロールと共にドキュメントのインデックスを作成できます。 プッシュ REST API を使用してコンテンツをAzure AI 検索 インデックスにプッシュすると、サービスはインデックス付きコンテンツに対するアクセス許可を保持し、クエリ時に適用します。

主な機能は次のとおりです。

• インジェスト パイプラインを柔軟に制御できます。
• アクセス許可メタデータの標準化されたスキーマ。
• フォルダー レベルの ACL などの階層アクセス許可のサポート。

この記事では、プッシュ REST API を使用して、Azure AI 検索のドキュメント レベルのアクセス許可メタデータのインデックスを作成する方法について説明します。 このプロセスでは、検索結果に対してクエリを実行し、エンドユーザーのアクセス許可を適用するインデックスを準備します。

前提 条件

• Microsoft Entra ID または別の POSIX スタイルの ACL システムからの ACL メタデータを含むコンテンツ。 userIds および groupIds ACL フィールドでは、UPN または電子メール アドレスではなく、Microsoft Entra オブジェクト ID (GUID) を使用します。 安定したオブジェクト ID は、ディレクトリ属性が変更された場合でも、クエリ時に信頼できる ID 照合を保証します。

• 最新のプレビュー REST APIまたは同等の機能を提供するプレビュー Azure SDK パッケージ。

• permissionFilterOptionが有効なインデックス スキーマと、ドキュメントのアクセス許可を格納するフィールド属性permissionFilter。

制限

• アクセス許可フィルターの種類が userIds または groupIds の ACL フィールドには、最大 1,000 個の値を保持できます。

• インデックスは、すべてのドキュメントで rbacScope 型のフィールド間で最大 5 つの一意の値を保持できます。 rbacScopeの同じ値を共有するドキュメントの数に制限はありません。

• 既存のフィールドを更新して、組み込みの ACL または RBAC メタデータ フィルターの permissionFilter 割り当てを含めることができます。 既存のインデックスでフィルター処理を有効にするには、新しいフィールドを追加するか、既存のフィールドを更新して permissionFilter 値を含めます。

• インデックスには、各 permissionFilter 型の 1 つのフィールド (各 groupIds、 userIds、および rbacScopeの 1 つ) しか存在できません。

• 各 permissionFilter フィールドでは、filterable を true に設定していることが必要です。

• クエリ時のアクセス許可の適用には、インデックスに最後に書き込まれた ACL 値が反映されます。 ソースのアクセス許可が変更された場合、影響を受けるドキュメントを再読み込みまたは更新するまで、これらの更新は反映されません。 ACL を最新の状態に保つために、増分再インストールまたは部分的な更新をスケジュールします。

• この機能は現在、Azure ポータルではサポートされていません。

アクセス許可フィルター フィールドを使用してインデックスを作成する

REST API を使用してドキュメント ACL と RBAC メタデータのインデックスを作成するには、アクセス許可フィルターを有効にし、アクセス許可フィルターが割り当てられているフィールドを含むインデックス スキーマを設定する必要があります。

まず、 permissionFilterOptionを追加します。 有効な値は enabled または disabledであり、 enabledに設定する必要があります。 インデックス レベルでアクセス許可フィルター機能を無効にする場合は、 disabled に切り替えることができます。

次に、アクセス許可メタデータの文字列フィールドを作成し、 permissionFilterを含めます。 各アクセス許可フィルターの種類のいずれかを指定できることを思い出してください。

すべての permissionFilter 型を含む基本的なスキーマの例を次に示します。

{  
  "fields": [  
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true },  
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true },  
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true },  
    { "name": "DocumentId", "type": "Edm.String", "key": true }  
  ],
  "permissionFilterOption": "enabled"
}

SharePoint Online などのエンタープライズ リポジトリでは、プッシュ API を呼び出す前に、取り込み時にドキュメント レベルまたはフォルダー レベルのアクセス許可を Microsoft Entra のユーザーおよびグループのオブジェクト ID に解決します。 その後、それらの ID を対応するアクセス許可フィールドに格納する必要があります。

REST API のインデックス作成の例

アクセス許可フィルター フィールドを含むインデックスを作成したら、他のドキュメント フィールドと同様に、プッシュ インデックス作成 API を使用してこれらの値を設定できます。 指定したインデックス スキーマを使用する例を次に示します。各ドキュメントでは、インデックス作成アクション、キー フィールド (DocumentId)、アクセス許可フィールドを指定します。 ドキュメントにはコンテンツも含める必要がありますが、簡潔にするために、この例ではそのフィールドは省略されています。

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-08-01-preview
{
  "value": [
    {
      "@search.action": "upload",
      "DocumentId": "1",
      "UserIds": ["00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"],
      "GroupIds": ["none"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-01"
    },
    {
      "@search.action": "merge",
      "DocumentId": "2",
      "UserIds": ["all"],
      "GroupIds": ["33dd33dd-ee44-ff55-aa66-77bb77bb77bb", "44ee44ee-ff55-aa66-bb77-88cc88cc88cc"]
    },
    {
      "@search.action": "mergeOrUpload",
      "DocumentId": "3",
      "UserIds": ["1cdd8521-38cf-49ab-b483-17ddaa48f68f"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-03"
    }
  ]
}

ACL アクセス解決規則

このセクションでは、各ドキュメントのアクセス許可フィールドに基づいて、ユーザーのドキュメント アクセスを決定する方法について説明します。 これらのフィールドは、ACL (userIdsとgroupIdsのいずれかであり、groupIdsにはセキュリティ グループとMicrosoft 365 グループが含まれます) または RBAC スコープ (rbacScope)。 Azureは、定義された順序で RBAC スコープと ACL を評価し、ADLS Gen2 アクセス許可モデルと一致します。

ユーザーは、一致するuserIdsまたはgroupIdsエントリ、またはrbacScopeの対象となるAzureロールの割り当てのいずれかのフィールドを満たすことでアクセス権を取得します。 クエリ時の呼び出し元 ID の提供方法については、「 クエリ時の ACL と RBAC の適用」を参照してください。

特殊な ACL 値 "all" と "none"

userIdsやgroupIdsなどの ACL フィールドには、通常、ドキュメントにアクセスできるユーザーとグループを識別する GUID (グローバル一意識別子) の一覧が含まれます。 これらの ACL フィールド型では、"all" と "none" という 2 つの特殊な文字列値がサポートされています。 これらの値は、次の表に示すように、グローバル レベルでアクセスを制御するための広範なフィルターとして機能します。

ユーザーが一致する必要があるフィールドの種類は 1 つだけであるため、特殊な値 "all" は、他の ACL フィールド値に関係なくパブリック アクセスを許可します。 これに対し、 userIds を "none" または空の配列に設定すると、ユーザー ID に基づいてドキュメントへのアクセス権がユーザーに付与されません。 グループ ID または RBAC メタデータを照合することで、引き続きアクセス権が付与される場合があります。

アクセス制御の例

この例では、 userIds、 groupIds、および rbacScopeのアクセス許可フィールドの値に基づいてドキュメント アクセス規則を解決する方法を示します。 読みやすくするために、このシナリオでは GUID の代わりに "user1" や "group1" などのエイリアスを使用します。運用環境では、Microsoft Entraオブジェクト ID (GUID) を使用します。

関連するコンテンツ

• ロールを使用してAzure AI 検索に接続
• クエリ時間 ACL と RBAC の適用
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API