Použijte indexer blobů nebo zdroj znalostí k ingestování metadat rozsahů RBAC (preview)

Azure Storage umožňuje přístup na základě role ke kontejnerům v úložišti objektů blob, kde role jako Storage Blob Data Reader nebo Storage Přispěvatel dat objektů blob určují, jestli má někdo přístup k obsahu. Azure AI Vyhledávač podporuje příjem uživatelských oprávnění (Preview) společně s příjmem dokumentů, abyste mohli tato oprávnění použít k řízení přístupu k výsledkům hledání. Pokud uživatel nemá oprávnění ke konkrétnímu adresáři nebo souboru v Azure Storage, nemá přístup k odpovídajícím dokumentům ve výsledcích Azure AI Vyhledávač, i když máte osobně přiřazené oprávnění Čtečka dat pro index vyhledávání v indexu.

• Počínaje verzí 2025-05-01-preview a novějšími je možné ingestovat metadata oborů RBAC pomocí Blob indexeru.
• Verze 2025-11-01-preview a novější poskytuje ekvivalentní podporu pro zdroje znalostí Blob v Azure Storage.

Působnost RBAC je nastavena na úrovni kontejneru a přenáší se na všechny objekty blob (dokumenty) díky dědičnosti oprávnění. Rozsah RBAC se zaznamenává během indexování jako metadata oprávnění. Pomocí rozhraní push API můžete ručně nahrát a indexovat obsah a oprávnění metadat (viz Indexování oprávnění pomocí push REST API) nebo můžete použít indexer nebo znalostní zdroj pro automatizaci příjmu dat. Tento článek se zaměřuje na automatizaci indexování.

V době dotazu je identita volajícího zahrnuta do hlavičky požadavku prostřednictvím parametru x-ms-query-source-authorization . Identita se musí shodovat s metadaty oprávnění v dokumentech, pokud uživatel chce zobrazit výsledky hledání.

Tento článek se zaměřuje na přístupy automatizace indexování založené na tomto základu:

• Azure Storage bloby zabezpečené řízením přístupu na základě role (Azure RBAC). Neexistuje žádná podpora řízení přístupu na základě atributů (Azure ABAC).

• Azure indexer objektů blob nebo zdroj znalostí objektů blob, který načítá a zpracovává data a metadata, včetně filtrů oprávnění. Pokud chcete získat podporu filtru oprávnění, použijte nejnovější rozhraní REST API verze Preview nebo balíček preview Azure SDK, který tuto funkci podporuje.

• An index in Azure AI Vyhledávač obsahující ingestované dokumenty a odpovídající oprávnění. Metadata oprávnění se ukládají jako pole v indexu.

• Dotaz, který používá filtry oprávnění K nastavení dotazů, které respektují filtry oprávnění, použijte nejnovější rozhraní REST API verze Preview nebo balíček preview Azure SDK, který tuto funkci podporuje.

Požadavky

• Microsoft Entra ID ověřování a autorizace. Služby a aplikace musí být ve stejném tenantu. Uživatelé mohou být v různých tenantech, pokud jsou všichni tenanti součástí Microsoft Entra ID. Přiřazení rolí se používají pro každé ověřené připojení.

• Azure AI Vyhledávač, všechny oblasti, ale pro podporu spravovaných identit musíte mít fakturovatelnou úroveň (basic a vyšší). Vyhledávací služba musí být nakonfigurovaná pro přístup na základě role a musí mít spravovanou identitu (systém nebo uživatel).

• Azure Storage, výkon úrovně Standard (pro obecné účely v2) na horké, studené a archivní úrovni přístupu s kontejnery nebo objekty blob zabezpečenými pomocí RBAC.

• Měli byste pochopit, jak indexery a zdroje znalostí fungují a jak vytvořit index. Tento článek vysvětluje nastavení konfigurace pro zdroj dat a indexer, ale neobsahuje kroky pro vytvoření indexu. Další informace o indexech navržených pro filtry oprávnění najdete v tématu Vytvoření indexu s poli filtru oprávnění.

Limitations

• Azure Portal tuto funkci nepodporuje.

• Následující funkce indexeru nepodporují dědičnost oprávnění v indexovaných dokumentech pocházejících z ADLS Gen2. Pokud některou z těchto funkcí použijete v sadě dovedností nebo indexeru, nebudou oprávnění na úrovni dokumentu zahrnuta do indexovaného obsahu.

  • Vlastní funkce webového API

  • Úložiště znalostí

  • Mezipaměť rozšiřování indexeru

  • Ladicí relace

Konfigurujte úložiště Blob

Ověřte, že kontejner objektů blob používá přístup na základě role.

1. Přihlaste se k portálu Azure a vyhledejte svůj účet úložiště.

2. Rozbalte kontejnery a vyberte kontejner s objekty blob, které chcete indexovat.

3. Pokud chcete zkontrolovat přiřazení rolí, vyberte Access Control (IAM). Uživatelé a skupiny s rolí Čtenář dat objektů blob Storage nebo rolí Přispěvatel dat objektů blob Storage mají přístup k prohledání dokumentů v indexu po dokončení indexace kontejneru.

Autorizace

Aby bylo možné spustit indexer, musí mít identita vaší vyhledávací služby oprávnění Storage Blob Data Reader. Další informace najdete v tématu Pojení k Azure Storage pomocí spravované identity.

Konfigurace Azure AI Vyhledávač

Vzpomeňte si, že vyhledávací služba musí mít:

• Povolený přístup na základě role
• Nakonfigurovaná spravovaná identita

Autorizace

Pro spuštění indexeru musí mít klient, který vydává volání API, oprávnění Vyhledávací přispěvatel služby pro vytváření objektů, Vyhledávací přispěvatel dat indexu pro provádění importu dat a Vyhledávací čtečka dat indexu pro dotazování indexu. Viz Připojení k Azure AI Vyhledávač pomocí rolí.

Konfigurace zdroje znalostí

Pokud používáte zdroj znalostí, definice ve zdroji znalostí se používají k vygenerování úplného indexovacího kanálu (indexer, zdroj dat a index). Rozsah RBAC se detekuje a automaticky zahrne do vygenerovaného indexu. Pokud chcete, aby byla v indexovaném obsahu zachována dědičnost oprávnění, nemusíte upravovat žádný z vygenerovaných objektů.

Klíčové body týkající se konfigurace, která v tomto scénáři funguje:

• isADLSGen2 je nastavená na false, což znamená, že zdroj dat je Azure Blob Storage.
• ingestionPermissionOptions určuje rbacScope.

# 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": false,
        "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": ["rbacScope"],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}

Referenční informace:Vytvoření nebo aktualizace zdroje znalostí (REST API)

Konfigurace indexování na bázi indexeru

Pokud používáte indexer, nakonfigurujte ho, zdroj dat a index pro stažení metadat oprávnění z objektů blob.

Vytvoření zdroje dat

• Typ zdroje dat musí být azureblob.

• Režim analýzy zdroje dat musí být výchozí.

• Zdroj dat musí obsahovat indexerPermissionOptions s rbacScope.

  • Pro rbacScope nakonfigurujte připojovací řetězec ve formátu spravované identity.

  • U připojovacích řetězců používajících spravovanou identitu přiřazenou uživatelem musíte také zadat identity vlastnost.

Příklad JSON se spravovanou identitou systému a indexerPermissionOptions:

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    }
}

Příklad schématu JSON s identitou spravovanou uživatelem v připojovací řetězec:

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    },
    "identity": {
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

Vytvoření polí oprávnění v indexu

V Azure AI Vyhledávač se ujistěte, že index obsahuje definice polí pro metadata oprávnění. Metadata oprávnění lze indexovat, pokud indexerPermissionOptions je zadána v definici zdroje dat.

Doporučené atributy schématu RBAC:

• Pole oboru RBAC s rbacScope hodnotou permissionFilter
• Vlastnost permissionFilterOption , která povolí filtrování v době dotazování.
• Používejte řetězcová pole pro metadata oprávnění
• Nastavte filterable hodnotu true u všech polí.

Všimněte si, že retrievable je false. Během vývoje můžete nastavit hodnotu true, abyste ověřili, že jsou oprávnění k dispozici, ale nezapomeňte před nasazením do produkčního prostředí nastavit hodnotu false, aby se ve výsledcích nezoviditelnily identity objektu zabezpečení.

Příklad schématu JSON:

{
  ...
  "fields": [
    ...
    { 
        "name": "RbacScope", 
        "type": "Edm.String", 
        "permissionFilter": "rbacScope", 
        "filterable": true, 
        "retrievable": false 
    }
  ],
  "permissionFilterOption": "enabled"
}

Nakonfigurujte indexer

Mapování polí v indexeru nastavují cestu k datům v indexu. Cílová a cílová pole, která se liší podle názvu nebo datového typu, vyžadují explicitní mapování polí. Následující pole metadat v Azure Blob Storage můžou potřebovat mapování polí, pokud se název pole liší:

• metadata_rbac_scope (Edm.String) – rozsah RBAC kontejneru.

Zadejte fieldMappings v indexeru pro směrování metadat oprávnění do cílových polí během indexování.

Příklad schématu JSON:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Spusťte indexer

Po nakonfigurování indexeru, zdroje dat a indexu spusťte indexer, aby se proces zahájil. Pokud dojde k potížím s konfigurací nebo oprávněními, zobrazí se tyto problémy v tomto kroku.

Ve výchozím nastavení se indexer spustí, jakmile ho publikujete do vyhledávací služby, ale pokud konfigurace indexeru obsahuje disabled hodnotu true, indexer se publikuje v zakázaném stavu, takže indexer můžete spustit ručně.

Doporučujeme ruru indexeru z portálu Azure, abyste mohli monitorovat stav a zprávy.

Za předpokladu, že nedojde k žádným chybám, index se teď naplní a můžete pokračovat s dotazy a testováním.

Sledování odstranění

Pokud chcete efektivně spravovat odstranění objektů blob, ujistěte se, že jste před prvním spuštěním indexeru povolili sledování odstranění . Tato funkce umožňuje systému rozpoznat odstraněné objekty blob ze zdroje a odstranit odpovídající obsah z indexu.

Viz také

• Popojte se k Azure AI Vyhledávač pomocí rolí

• Vynucování ACL a RBAC v čase dotazu
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API

• Vyhledat obsah Azure Blob Storage
• Konfigurace indexeru objektů blob