ADLS Gen2 インデクサーを使用してアクセス許可メタデータを取り込み、ユーザーアクセス権に基づいて検索結果をフィルター処理する (プレビュー)

Note

Azure AI 検索は、Azure ポータル、REST API、およびAzure SDKから使用できます。また、Foundry IQ は、エンタープライズコンテンツを、Microsoft Foundry ポータルのエージェントの再利用可能なアクセス許可に対応したナレッジベースに変換するマネージドナレッジレイヤーです。

重要

機能、またはマークされたプロパティ (プレビュー) は、サービスレベルアグリーメントの対象ではなく、運用環境のワークロードには推奨されず、一般公開される前に変更または制約される可能性があります。 Azure AI 検索プレビューの用語は、スタンドアロンでも一般公開されている機能の一部でも、すべてのプレビュー機能に適用されます。

Azure Data Lake Storage (ADLS) Gen2 では、アクセス制御リスト (ACL) と role ベースのアクセス制御 (Azure RBAC) を介したディレクトリとファイルへのユーザーごとのアクセスがサポートされます。 Attribute ベースのアクセス制御 (Azure ABAC) はサポートされていません。

Azure AI 検索は、プレビュー REST API を使用して、ドキュメントコンテンツと共にこのアクセス許可メタデータ (プレビュー) を取り込むことができます。ストレージ内のディレクトリまたはファイルにアクセスできないユーザーは、検索結果に対応するドキュメントを表示しません。これは、Azure AI 検索のdocument レベルのアクセス制御のいくつかの戦略の 1 つです。

この記事では、検索インデックスにアクセス許可メタデータを自動的にプルするように ADLS Gen2 インデクサーまたは ADLS Gen2 BLOB ナレッジソースを構成する方法について説明します。 ADLS Gen2 からのインデックスデータを補完し、アクセス許可インジェストに固有の情報を使用して ADLS Gen2 の BLOB ナレッジソースを作成します。アクセス許可メタデータを手動で プッシュ するには、プッシュ API を使用したドキュメント ACL のインデックス作成に関するページを参照してください。

前提条件

Microsoft Entra ID認証と承認。サービスとアプリは、同じテナント内にある必要があります。すべてのテナントがMicrosoft Entra IDを使用している限り、ユーザーは異なるテナントに存在できます。認証された接続ごとにロールの割り当てが使用されます。
任意のリージョンで有料レベル (Basic 以上) の Azure AI 検索を利用します。検索サービスでは、ロールベースのアクセスが有効になっており、システム割り当てマネージド ID またはユーザー割り当てマネージド ID が必要です。
階層型名前空間内の ADLS Gen2 BLOB。ユーザーアクセス許可は ACL またはロールによって付与されます。
インデクサーのアクセス許可インジェスト用の REST API バージョン 2025-05-01-preview 以降。ナレッジソースのサポートのための REST API バージョン 2025-11-01-preview 以降。アクセス許可フィルターをサポートする最新のプレビュー REST API またはプレビュー SDK パッケージを使用します。

制限

Azure ポータルでは、この機能はサポートされていません。
ロールの割り当てと ACL エントリに対する ADLS Gen2 の制限が適用されます。
owning users、owning groups、Other (all) ACL ID カテゴリは、プレビュー期間中はサポートされていません。代わりに、 named users 割り当てと named groups 割り当てを使用します。
次のインデクサー機能では、ADLS Gen2 から生成されたインデックス付きドキュメントでのアクセス許可の継承はサポートされていません。スキルセットまたはインデクサーでこれらの機能のいずれかを使用する場合、ドキュメントレベルのアクセス許可はインデックス付きコンテンツに含まれません。
- カスタム Web API スキル
- エージェント検索でのイメージサービス (プレビュー) に必要な資産ストアを含むナレッジストア。そのため、ACL または RBAC スコープを取り込むナレッジソースでは、イメージサービスはサポートされていません。
- インデクサーエンリッチメントキャッシュ
- デバッグセッション

アクセス許可モデルのサポート

このセクションでは、ADLS Gen2 と Azure AI 検索の間でドキュメントレベルのアクセス制御機能を比較します。 AI Search でサポートまたはマップされる Azure Data Lake Storage (ADLS) Gen2 アクセス制御メカニズムについて説明します。これは、ドキュメントレベルでのアクセス許可の適用方法を理解するのに役立ちます。

ADLS Gen2 の機能	説明	サポートされています	ノート
Rbac	コンテナーレベルでの粗粒度アクセス	はい	AI Search では、コンテナー全体のすべてのドキュメントにアクセスするための RBAC が優先されます。
Abac	RBAC に基づく属性ベースの条件	いいえ	AI Search では、ドキュメントレベルのアクセスに関する ABAC 条件は評価されません。
Acl	ディレクトリ/ファイル (ドキュメント) レベルでのきめ細かなアクセス許可	はい	AI Search では、アクセス許可フィルターにドキュメントレベルの ACL が使用されます。
セキュリティグループ	グループベースのアクセス許可の割り当て	はい	ドキュメントレベルの ACL 内でセキュリティグループがマップされている場合にサポートされます。

クエリ時に、Azure AI 検索は最初にコンテナーレベルの RBAC を評価してから、ドキュメントレベルの ACL エントリを確認します。アクセスは、任意のメカニズムで許可されている場合に付与されます。

ACL 階層型アクセス許可について

インデクサーとナレッジソースは、ADLS Gen2 階層アクセス評価フローに従って、指定されたコンテナーと各ファイルに至るすべてのディレクトリから ACL 割り当てを取得できます。各ファイルの最終的な有効なアクセスリストが計算され、さまざまなアクセスカテゴリが対応するインデックスフィールドにインデックスが作成されます。

たとえば、ADLS Gen2 では、ファイルパス /Oregon/Portland/Data.txtとしてのアクセス許可に関連する一般的なシナリオです。

操作	/	オレゴン/	ポートランド/	Data.txt
データ.txtを開く	--X	--X	--X	R--

インデクサーまたはナレッジソースは、各コンテナーとディレクトリから ACL を収集します。その後、より低いレベルで有効なアクセスが決定され、すべてのファイルのアクセス許可が解決されるまで続行されます。

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

ADLS Gen2 の構成

次の条件が満たされている場合、インデクサーまたはナレッジソースはストレージアカウントの ACL を取得できます。 ACL の割り当ての詳細については、 ADLS Gen2 ACL の割り当てを参照してください。

認証

インデックス作成の場合、検索サービス ID には ストレージ BLOB データ閲覧者 アクセス許可が必要です。

ローカルでテストする場合は、 ストレージ BLOB データ閲覧者 ロールの割り当ても必要です。詳細については、「マネージド ID を使用してAzure Storageに接続するを参照してください。

ルートコンテナーのアクセス許可:

ルートコンテナー GroupのすべてのUserおよび/ セット (セキュリティプリンシパル) を、ReadとExecuteのアクセス許可で割り当てます。
新しく作成されたファイルとディレクトリに自動的に反映されるように、 Read と Execute の両方が "既定のアクセス許可" として追加されていることを確認します。

ファイル階層にアクセス許可を伝達する

新しいディレクトリとファイルはアクセス許可を継承しますが、既存のディレクトリとファイルはこれらの割り当てを自動的に継承しません。

ADLS Gen2 ツールを使用して、既存のコンテンツに対する割り当ての伝達に ACL を再帰的に適用します。このツールは、ルートコンテナーの ACL 割り当てを基になるすべてのディレクトリとファイルに伝達します。

余分なアクセス許可を削除する

ACL を再帰的に適用した後、各ディレクトリとファイルのアクセス許可を確認します。

特定のディレクトリまたはファイルにアクセスできない Group または User セットを削除します。たとえば、フォルダー User2のPortland/を削除したり、フォルダーIdaho割り当てからGroup2やUser2を削除したりします。

ACL の割り当ての構造の例

ADLS Gen2 ドキュメントの架空のディレクトリ階層の ACL 割り当て構造の図を次に示します。

時間の経過に伴う ACL 割り当ての更新

時間の経過と同時に、新しい ACL 割り当てが追加または変更されると、前の手順を繰り返して、適切な伝達とアクセス許可の調整が行われます。インデクサーまたはナレッジソースを使用してコンテンツを再取り込みすると、ADLS Gen2 の更新されたアクセス許可が検索インデックスで更新されます。

Azure AI 検索の構成

検索サービスには次のものが必要であることを思い出してください。

認証

インデックス作成の場合、API 呼び出しを発行するクライアントには、オブジェクトを作成するための Search Service Contributor アクセス許可、データインポートを実行するための 検索インデックスデータ共同作成者 アクセス許可、インデックスを照会するための 検索インデックスデータ閲覧者 が必要です。

ローカルでテストする場合は、同じロールの割り当てが必要です。詳細については、「ロールを使用してAzure AI 検索に接続するを参照してください。

ナレッジソースを構成する

ナレッジソースを使用している場合は、ナレッジソースの定義を使用して、完全なインデックス作成パイプライン (インデクサー、データソース、インデックス) を生成します。 ACL の割り当てが検出され、生成されたインデックスに自動的に含まれます。インデックス付きコンテンツでアクセス許可の継承が必要な場合は、生成されたオブジェクトを変更する必要はありません。

このシナリオで機能する構成に関する重要なポイントは次のとおりです。

isADLSGen2 が true に設定され、このシナリオのデータソース要件が満たされます。
ingestionPermissionOptions は、ユーザー ID とグループ ID を指定します。

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

インデクサーベースのインデックス作成を構成する

インデクサーを使用している場合は、ADLS Gen2 BLOB からアクセス許可メタデータをプルするように、インデクサー、データソース、およびインデックスを構成します。

データソースを作成する

このセクションではADLS Gen2のインデックスデータを、ドキュメントのコンテンツと権限を一緒にAzure AI 検索インデックスに取り込むための情報で補完します。

データソースの種類は adlsgen2する必要があります。
データソースには、indexerPermissionOptionsとuserIds、groupIdsおよび/またはrbacScopeが必要です。
- rbacScope の場合は、マネージド ID 形式で接続文字列を構成します。
- ユーザー割り当てマネージド ID を使用する接続文字列の場合は、identity プロパティも指定する必要があります。

システムマネージド ID を使用した JSON の例:

{
    "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": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

接続文字列のユーザーマネージド ID を持つ JSON スキーマの例:

{
    "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": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

インデックスにアクセス許可フィールドを作成する

Azure AI 検索で、インデックスにアクセス許可メタデータのフィールド定義が含まれていることを確認します。アクセス許可メタデータは、データソース定義で indexerPermissionOptions が指定されている場合にインデックスを作成できます。

ACL (UserIds、GroupIds) と RBAC スコープに推奨されるスキーマ属性:

ユーザー識別子 (ID) フィールドの permissionFilter 値 userIds。
groupIds permissionFilter 値を持つ "グループ ID" フィールド。
rbacScope permissionFilter 値を持つ RBAC スコープフィールド。
プロパティ permissionFilterOption クエリ時にフィルター処理を有効にします。
権限メタデータに文字列フィールドを使用する
すべてのフィールドで filterable を true に設定します。

retrievableが false であることに注意してください。開発中に true を設定してアクセス許可が存在することを確認できますが、運用環境にデプロイする前に必ず false に設定してください。

JSON スキーマの例:

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

インデクサーを構成する

インデクサー内のフィールドマッピングは、データパスをインデックス内のフィールドに設定します。名前またはデータ型によって異なるターゲットフィールドと変換先フィールドには、明示的なフィールドマッピングが必要です。フィールド名を変更すると、ADLS Gen2 の次のメタデータフィールドにフィールドマッピングが必要になる場合があります。

metadata_user_ids (Collection(Edm.String)) - ACL ユーザー ID の一覧。
metadata_group_ids (Collection(Edm.String)) - ACL グループ ID の一覧。
metadata_rbac_scope (Edm.String) - コンテナー RBAC スコープ。

インデクサーで fieldMappings を指定して、インデックス作成中にアクセス許可メタデータをターゲットフィールドにルーティングします。

JSON スキーマの例:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

推奨事項とベストプラクティス

フォルダーを作成する前に、ADLS Gen2 フォルダー構造を慎重に計画してください。
個々のユーザーに直接アクセスを許可するのではなく、可能な限り ID をグループに整理し、グループを使用します。グループを適用する代わりに個々のユーザーを継続的に追加すると、追跡および評価する必要があるアクセス制御エントリの数が増えます。このベストプラクティスに従わないと、このメタデータの変更に伴ってインデックスに必要なセキュリティメタデータの更新が頻繁になり、更新プロセスの遅延と非効率性が高まる可能性があります。

インデックス付きコンテンツとソースコンテンツの間でアクセス許可を同期する

インデクサーで ACL または RBAC エンリッチメントを有効にすると、次の 2 つの状況でのみ自動的に機能します。

最初のフルインデクサー実行/データクロール: 各ドキュメントのその時点に存在するすべてのアクセス許可メタデータがキャプチャされます。
ACL/RBAC のサポートが有効になった後に追加されたまったく新しいドキュメント: ACL/RBAC 情報がコンテンツと共に取り込まれます。

ACL へのユーザーの追加やロールの割り当ての更新など、ドキュメントのアクセス許可を変更した場合、インデクサーにドキュメントのアクセス許可メタデータをもう一度クロールするように指示しない限り、変更は検索インデックスに表示されません。

変更された項目の数に応じて、次のいずれかのメカニズムを選択します。

変更の範囲	最適なトリガー	次の実行時に更新される内容
1 つの BLOB またはほんの一握りの BLOB	ストレージ内の BLOB の `Last-Modified` タイムスタンプを更新する (ファイルにタッチする)	コンテンツと ACL/RBAC メタデータを文書化する
数十から数千の BLOB	/resetdocs (プレビュー) を呼び出し、影響を受けるドキュメントキーを一覧表示します。	コンテンツと ACL/RBAC メタデータを文書化する
全体のデータソース	アクセス許可オプションを使用して /resync (プレビュー) を呼び出します。	だけ ACL/RBAC メタデータ (コンテンツはそのまま残ります)

Resetdocs (プレビュー) API の例:

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{ 
  "documentKeys": [ 
    "1001", 
    "4452" 
  ]
}

再同期 (プレビュー) API の例:

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{ 
  "options": [ 
    "permissions" 
  ] 
}

重要

インデックス付きドキュメントのアクセス許可を変更し、上記のメカニズムの 1 つをトリガーしない場合、検索インデックスは古い ACL または RBAC データを引き続き処理します。新しいドキュメントは自動的にインデックスが作成され続けます。手動トリガーは必要ありません。

削除の追跡

BLOB の削除を効果的に管理するには、インデクサーを初めて実行する前に、削除の追跡が有効になっていることを確認します。この機能を使用すると、ソース内の削除された BLOB をシステムが検出し、インデックスから削除できます。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-17