このチュートリアルでは、インデクサーを使用して、Azure Data Lake Storage (ADLS) Gen2 アクセス制御リスト (ACL) と ロールベースのアクセス制御 (RBAC) スコープのインデックスを検索インデックスに作成する方法について説明します。
また、ユーザー アクセス許可を尊重するクエリを構成する方法についても説明します。 クエリ結果が成功すると、インデックス中に発生したアクセス許可の転送が確認されます。
ACL のインデックス作成の詳細については、「 ADLS Gen2 インデクサーを使用してアクセス許可メタデータを取り込む」を参照してください。
このチュートリアルでは、以下の内容を学習します。
-
adlsgen2データ ソースで RBAC スコープと ACL を構成する - アクセス許可情報フィールドを含む Azure AI Search インデックスを作成する
- インデクサーを作成して実行し、データ ソースからインデックスにアクセス許可情報を取り込む
- 作成したインデックスを検索する
このチュートリアルと最新のプレビュー REST API を完了するには、REST クライアントを使用してください。 現在、Azure portal では ACL インデックス作成はサポートされていません。
[前提条件]
アクティブなサブスクリプションを持つ Azure アカウント。 無料でアカウントを作成できます。
Microsoft Entra ID の認証と承認。 サービスとアプリは、同じテナント内にある必要があります。 認証された接続ごとにロールの割り当てが使用されます。 ユーザーとグループは、同じテナントに存在する必要があります。 作業を行うためには、ユーザーとグループが必要です。 テナントとセキュリティ プリンシパルの作成は、このチュートリアルでは範囲外です。
階層型名前空間を持つ ADLS Gen2。
階層フォルダー構造内のファイル。 このチュートリアルでは、ファイル
/Oregon/Portland/Data.txtのフォルダー構造の ADLS Gen2 デモを前提としています。 このチュートリアルでは、演習を正常に完了できるように、フォルダーとファイルに対する ACL の割り当てについて説明します。Azure AI Search、任意のリージョン。 マネージド ID のサポートには Basic レベル以上が必要です。
REST クライアントまたは Python クライアントと Jupyter パッケージを含む Visual Studio Code。
サンプル データの準備
ADLS Gen2 のコンテナーに 、州立公園のサンプル データ をアップロードします。 コンテナー名は "パーク" で、"オレゴン" と "Washington" の 2 つのフォルダーが必要です。
検索サービスの構成を確認する
検索サービスは、Microsoft Entra ID の認証と承認用に構成する必要があります。 このチェックリストを確認して、準備ができていることを確認します。
ローカル テスト用の個人 ID トークンを取得する
このチュートリアルでは、ローカル システム上の REST クライアントを想定し、パブリック インターネット接続経由で Azure に接続します。
個人 ID トークンを取得し、Azure リソースへのローカル接続用に Visual Studio Code を設定するには、次の手順に従います。
ADLS Gen2 でアクセス許可を設定する
ベスト プラクティスとして、Group セットを直接割り当てるのではなく、User セットを使用します。
検索サービス ID にコンテナーへの読み取りアクセス権を付与します。 インデクサーは、検索サービス ID で Azure Storage に接続します。 検索サービスには、データを取得するための ストレージ BLOB データ閲覧者 のアクセス許可が必要です。
ファイル階層内のグループ単位またはユーザー単位のアクセス許可を付与します。 ファイル階層で、コンテナー、ディレクトリ、およびファイルに割り当てられているすべての
GroupセットとUserセットを識別します。Azure portal を使用して ACL を管理できます。 ストレージ ブラウザーで、オレゴン ディレクトリを選択し、コンテキスト メニューから [ACL の管理 ] を選択します。
ユーザーとグループの新しいセキュリティ プリンシパルを追加します。
所有グループ、所有ユーザー、その他の既存のプリンシパルを削除します。 これらのプリンシパルは、パブリック プレビュー中の ACL インデックス作成ではサポートされていません。
アクセス許可メタデータの検索インデックスを作成する
コンテンツとアクセス許可のメタデータのフィールドを含むインデックスを作成します。
最新のプレビュー REST API または同等の機能を提供するプレビュー Azure SDK パッケージを必ず使用してください。 アクセス許可フィルターのプロパティは、プレビュー API でのみ使用できます。
デモの目的で、アクセス許可フィールド retrievable 有効になっているため、インデックスの値を確認できます。 運用環境では、機密情報の漏洩を回避するために、 retrievable を無効にする必要があります。
{
"name" : "my-adlsgen2-acl-index",
"fields": [
{
"name": "name", "type": "Edm.String",
"searchable": true, "filterable": false, "retrievable": true
},
{
"name": "description", "type": "Edm.String",
"searchable": true, "filterable": false, "retrievable": true
},
{
"name": "location", "type": "Edm.String",
"searchable": true, "filterable": false, "retrievable": true
},
{
"name": "state", "type": "Edm.String",
"searchable": true, "filterable": false, "retrievable": true
},
{
"name": "AzureSearch_DocumentKey", "type": "Edm.String",
"searchable": true, "filterable": false, "retrievable": true
"stored": true,
"key": true
},
{
"name": "UserIds", "type": "Collection(Edm.String)",
"permissionFilter": "userIds",
"searchable": true, "filterable": false, "retrievable": true
},
{
"name": "GroupIds", "type": "Collection(Edm.String)",
"permissionFilter": "groupIds",
"searchable": true, "filterable": false, "retrievable": true
},
{
"name": "RbacScope", "type": "Edm.String",
"permissionFilter": "rbacScope",
"searchable": true, "filterable": false, "retrievable": true
}
],
"permissionFilterOption": "enabled"
}
データ ソースを作成する
インデクサーのアクセス許可インジェストと、インデックスを作成するアクセス許可メタデータの種類を指定するように 、データ ソースの構成 を変更します。
データ ソースには indexerPermissionOptionsが必要です。
このチュートリアルでは、認証された接続にシステム割り当てマネージド ID を使用します。
{
"name" : "my-adlsgen2-acl-datasource",
"type": "adlsgen2",
"indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
"credentials": {
"connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
},
"container": {
"name": "parks",
"query": null
}
}
インデクサーを作成して実行する
アクセス許可インジェストのインデクサー構成は、主にfieldMappingsからを定義することです。
{
"name" : "my-adlsgen2-acl-indexer",
"dataSourceName" : "my-adlsgen2-acl-datasource",
"targetIndexName" : "my-adlsgen2-acl-index",
"parameters": {
"batchSize": null,
"maxFailedItems": 0,
"maxFailedItemsPerBatch": 0,
"configuration": {
"dataToExtract": "contentAndMetadata",
"parsingMode": "delimitedText",
"firstLineContainsHeaders": true,
"delimitedTextDelimiter": ",",
"delimitedTextHeaders": ""
},
"fieldMappings": [
{ "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
{ "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
{ "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
]
}
}
インデクサーの作成と即時実行の後、ファイルの内容とアクセス許可メタデータ情報がインデックスにインデックス化されます。
クエリを実行して結果を確認する
これでドキュメントが読み込まれたので、Documents - Search Post (REST) を使って、それらに対してクエリを発行できます。
URI は、 /docs/search 演算子を使用して指定されたクエリ入力を含むように拡張されます。 クエリ トークンは要求ヘッダーで渡されます。 詳細については、「 クエリ時間 ACL と RBAC の適用」を参照してください。
POST {{endpoint}}/indexes/stateparks/docs/search?api-version=2025-11-01-preview
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{search-token}}
Content-Type: application/json
{
"search": "*",
"select": "name,description,location,GroupIds",
"orderby": "name asc"
}