ADLS Gen2-indexelő használata jogosultsági metaadatok betöltésére és keresési eredmények szűrésére felhasználói hozzáférési jogosultságok (előzetes verzió) alapján

Azure Data Lake Storage (ADLS) Gen2 hozzáférés-vezérlő listák és szerepkör-alapú hozzáférés-vezérlés (Azure RBAC) segítségével támogatja a címtárakhoz és fájlokhoz való felhasználónkénti hozzáférést. Attribute-alapú hozzáférés-vezérlés (Azure ABAC) nem támogatott.

Azure AI Keresés ezt az engedély metaadatait (előzetes verzió) a dokumentumtartalom mellett egy előzetes REST API használatával is betöltheti. Azok a felhasználók, akik nem férnek hozzá egy könyvtárhoz vagy fájlhoz a tárban, nem látják a megfelelő dokumentumokat a keresési eredményekben. Ez az Azure AI Keresés dokumentum szintű hozzáférés-vezérlésének számos stratégiája egyike.

Ez a cikk bemutatja, hogyan konfigurálhat egy ADLS Gen2-indexelőt vagy ADLS Gen2-blob-tudásbázist, hogy automatikusan lekérje az engedély metaadatait egy keresési indexbe. Kiegészíti az ADLS Gen2 indexadatait , és létrehoz egy blob-tudásbázist az ADLS Gen2-hez az engedélybetöltésre vonatkozó információkkal. Az engedély metaadatainak manuális leküldéséhez tekintse meg az Index dokumentum ACL-jeit a leküldéses API használatával.

Előfeltételek

• Microsoft Entra ID hitelesítés és engedélyezés. A szolgáltatásoknak és alkalmazásoknak ugyanabban a bérlőben kell lenniük. A felhasználók különböző bérlőkben lehetnek, amíg az összes bérlő Microsoft Entra ID használ. A szerepkör-hozzárendelések minden hitelesített kapcsolathoz használhatók.

• Azure AI Keresés bármely régióban számlázható szinten (alapszintű vagy magasabb). A keresési szolgáltatásnak engedélyezve kell lennie a szerepköralapú hozzáféréssel , valamint egy rendszer által hozzárendelt vagy felhasználó által hozzárendelt felügyelt identitással.

• Az ADLS Gen2-blobok hierarchikus névtérben, ACL-eken vagy szerepkörökön keresztül megadott felhasználói engedélyekkel.

• A REST API 2025-05-01-preview vagy újabb verziója az indexelői engedélyek beolvasásához. Az ismeretforrások támogatásához a REST API 2025-11-01-preview vagy újabb verziója szükséges. Használja a legújabb előzetes verziójú REST API-t vagy egy előzetes verziójú SDK-csomagot, amely támogatja az engedélyszűrőket.

Korlátozások

• A Azure portál nem támogatja ezt a funkciót.

• Az ADLS Gen2 szerepkör-hozzárendelésekre és ACL-bejegyzésekre vonatkozó korlátozásai érvényesek.

• owning users owning groups Other Az allACL-identitáskategóriák nem támogatottak az előzetes verzióban. Használja inkább a named users és named groups hozzárendeléseket.

• Az alábbi indexelő funkciók nem támogatják az ADLS Gen2-ből származó indexelt dokumentumok engedélyöröklését. Ha valamelyik funkciót egy képességkészletben vagy indexelőben használja, a dokumentumszintű engedélyek nem szerepelnek az indexelt tartalomban.

  • Egyéni webes API-képesség

  • Tudástár, beleértve az ágensalapú lekérésben a képkiszolgáláshoz (előzetes verzió) szükséges eszköztárat is. Ezért a rendszerkép-szolgáltatás nem támogatott az ACL-eket vagy RBAC-hatóköröket tartalmazó tudásbázisok esetében.

  • Indexelőbővítési gyorsítótár

  • Hibakeresési munkamenetek

Az engedélymodell támogatása

Ez a szakasz az ADLS Gen2 és Azure AI Keresés dokumentumszintű hozzáférés-vezérlési funkcióit hasonlítja össze. Ismerteti, hogy az AI Search mely Azure Data Lake Storage (ADLS) Gen2 hozzáférés-vezérlési mechanizmusokat támogat vagy képez le. Ez segít megérteni az engedélyek dokumentumszinten történő kikényszerítésének módját.

Lekérdezéskor Azure AI Keresés először kiértékeli a tárolószintű RBAC-t, majd ellenőrzi a dokumentumszintű ACL-bejegyzéseket. A hozzáférés akkor adható meg, ha bármely mechanizmus engedélyezi.

Flowchart és igazságtábla bemutatja, hogyan értékeli ki az Azure AI Keresés az engedélyezést: először a tárolószintű RBAC jogosultságokat ellenőrzi, majd az ACL-csoportok és felhasználói bejegyzések alapján biztosít hozzáférést, ha bármelyik mechanizmus engedélyezi, és csak akkor tagadja meg a hozzáférést, ha minden ellenőrzés meghibásodik.

Tudnivalók az ACL hierarchikus engedélyeiről

Az indexelők és a tudásbázisok az ADLS Gen2 hierarchikus hozzáférés-kiértékelési folyamatának követésével lekérhetik az ACL-hozzárendeléseket a megadott tárolóból és az egyes fájlokhoz vezető összes könyvtárból. Az egyes fájlok végső tényleges hozzáférési listája ki lesz számítva, és a különböző hozzáférési kategóriák a megfelelő indexmezőkbe vannak indexelve.

Az ADLS Gen2-ben például az engedélyekkel kapcsolatos gyakori forgatókönyveket szemlélteti a fájl elérési útja, mint például /Oregon/Portland/Data.txt.

Az indexelő vagy a tudásbázis minden tárolóból és könyvtárból gyűjt ACL-eket. Ezután meghatározza a hatékony hozzáférést alacsonyabb szinteken, és mindaddig folytatódik, amíg meg nem oldja az összes fájl engedélyeit.

/ 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

Az ADLS Gen2 konfigurálása

Az indexelők vagy a tudásbázisok lekérhetik az ACL-eket egy tárfiókban, ha az alábbi feltételek teljesülnek. További információ az ACL-hozzárendelésekről: ADLS Gen2 ACL-hozzárendelések.

Engedélyezési

Az indexeléshez a keresési szolgáltatás identitásának rendelkeznie kell a blobtárolási adatok olvasói engedéllyel.

Ha helyileg tesztel, a Storage Blob Data Reader szerepkör-hozzárendeléssel is rendelkeznie kell. További információkat a következő témában talál: Felügyelt identitással való kapcsolódás az Azure Storage-hoz.

Gyökértároló engedélyei:

1. Rendelje hozzá az összes Group és User biztonsági főösszetevőt a gyökértárolóhoz és alkalmazza a / és Read engedélyeket.

2. Győződjön meg arról, hogy mind a Read, mind a Execute hozzá van adva az "Alapértelmezett engedélyek" beállításhoz, hogy automatikusan alkalmazhatóak legyenek az újonnan létrehozott fájlokra és könyvtárakra.

Az engedélyek továbbítása a fájlhierarchiában

Bár az új könyvtárak és fájlok öröklik az engedélyeket, a meglévő könyvtárak és fájlok nem öröklik automatikusan ezeket a hozzárendeléseket.

Az ADLS Gen2 eszközzel rekurzív módon alkalmazhatja az ACL-eket a hozzárendelések propagálására a meglévő tartalmakon. Ez az eszköz propagálja a gyökértároló ACL-hozzárendeléseit az összes mögöttes könyvtárba és fájlba.

Felesleges engedélyek eltávolítása

Az ACL-ek rekurzív alkalmazása után tekintse át az egyes címtárak és fájlok engedélyeit.

Távolítsa el azokat Group a készleteket vagy User csoportokat, amelyeknek nem kellene hozzáféréssel rendelkezniük bizonyos könyvtárakhoz vagy fájlokhoz. Például távolítsa el a User2 elemet a Portland/ mappáról, és a Idaho mappában távolítsa el a Group2 és User2 elemeket a hozzárendeléseiből, és így tovább.

Az ACL-hozzárendelések mintastruktúrája

Az alábbi ábra az ADLS Gen2 dokumentációjának fiktív címtárhierarchiájának ACL-hozzárendelési struktúráját mutatja be.

ACL-hozzárendelések frissítése idővel

Idővel az új ACL-hozzárendelések hozzáadásakor vagy módosításakor ismételje meg az előző lépéseket a megfelelő propagálás és engedélyek igazításának biztosítása érdekében. Az ADLS Gen2 frissített engedélyei frissülnek a keresési indexben, amikor újra betölti a tartalmat az indexelő vagy a tudásbázis használatával.

Azure AI Keresés konfigurálása

Ne feledje, hogy a keresési szolgáltatásnak a következő szolgáltatással kell rendelkeznie:

• Szerepköralapú hozzáférés engedélyezve
• Konfigurált felügyelt identitás

Engedélyezési

Az indexeléshez az API-hívást kibocsátó ügyfélnek keresési szolgáltatás közreműködői engedéllyel kell rendelkeznie objektumok létrehozásához, keresési index adatszolgáltatói engedéllyel kell rendelkeznie az adatok importálásához, valamint az index lekérdezéséhez.

Ha helyileg tesztel, ugyanazoknak a szerepkör-hozzárendeléseknek kell lennie. További információ: Kapcsolódás Azure AI Keresés szerepkörök használatával.

Tudásbázis konfigurálása

Ha tudásbázist használ, a tudásbázis definíciói teljes indexelési folyamatot (indexelőt, adatforrást és indexet) hoznak létre. A rendszer észleli az ACL-hozzárendeléseket, és automatikusan belefoglalja a létrehozott indexbe. Nincs szükség a létrehozott objektumok módosítására, ha engedélyöröklést szeretne az indexelt tartalomban.

Az ebben a forgatókönyvben használható konfigurációval kapcsolatos főbb pontok:

• isADLSGen2 igaz értékre van állítva, amely megfelel a forgatókönyv adatforrás-követelményének.
• ingestionPermissionOptions felhasználó- és csoportazonosítókat határoz meg.

# 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}}"
            }
        }
    }
}
###

Indexelőalapú indexelés konfigurálása

Ha indexelőt használ, konfigurálja azt, az adatforrást és az indexet az ADLS Gen2-blobok engedély-metaadatainak lekéréséhez.

Az adatforrás létrehozása

Ez a szakasz Index-adatokat egészít ki az ADLS Gen2 adataival, amelyek a dokumentumtartalommal együtt az engedélyek Azure AI Keresés indexbe való betöltésére vonatkoznak.

• Az adatforrás típusának meg kell lennie adlsgen2.

• Az adatforrásnak rendelkeznie kell indexerPermissionOptions, userIds, groupIds és/vagy rbacScope elemekkel.

  • A rbacScope esetében konfigurálja a kapcsolati karakterlánc felügyelt identitásformátumot.

  • A felhasználó által hozzárendelt felügyelt identitást használó kapcsolati sztringek esetén meg kell adnia a identity tulajdonságot is.

JSON-példa rendszer által felügyelt identitással:

{
    "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>"
    }
}

JSON-séma példa egy felhasználó által felügyelt identitással a kapcsolati sztringben.

{
    "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}"
    }
}

Engedélymezők létrehozása az indexben

A Azure AI Keresés ellenőrizze, hogy az index tartalmaz-e meződefiníciókat az engedély metaadataihoz. Az engedély metaadatai indexelhetők, ha indexerPermissionOptions az adatforrás definíciójában meg van adva.

Ajánlott sémaattribútumok az ACL-hez (UserIds, GroupIds) és RBAC-hatókörhöz:

• User identifier (ID) mező a userIds permissionFilter értékkel.
• Csoportazonosítók mező engedélyszűrő groupIds értékkel.
• RBAC-hatókör mező a rbacScope permissionFilter értékkel.
• Tulajdonság permissionFilterOption , amely lehetővé teszi a szűrést a lekérdezési időpontban.
• Sztringmezők használata az engedély metaadataihoz
• Állítsa filterable a true (igaz) értéket az összes mezőre.

Figyelje meg, hogy retrievable ez hamis. Fejlesztés közben igazra állíthatja, hogy ellenőrizze az engedélyek meglétét, de ne felejtse el visszaállítani hamisra, mielőtt éles környezetbe telepítené.

Példa JSON-séma:

{
  ...
  "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"
}

Az indexelő konfigurálása

Az indexelőn belüli mezőleképezések az adatelérési utat egy index mezőire állítják be. A név vagy adattípus szerint változó cél- és célmezők explicit mezőleképezést igényelnek. Az ADLS Gen2 következő metaadatmezőinek szükség lehet mezőleképezésekre, ha eltérő a mező neve:

• metadata_user_ids (Collection(Edm.String)) – az ACL felhasználói azonosítóinak listája.
• metadata_group_ids (Collection(Edm.String)) – az ACL-csoport azonosítóinak listája.
• metadata_rbac_scope (Edm.String) – a tároló RBAC-hatóköre.

Adja meg fieldMappings az indexelőben, hogy az engedély metaadatait célmezőkre irányíthassa az indexelés során.

Példa JSON-séma:

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

Javaslatok és ajánlott eljárások

• A mappák létrehozása előtt gondosan tervezze meg az ADLS Gen2 mappastruktúráját.

• Az identitásokat csoportokba rendezi, és amikor csak lehetséges, csoportokat használ, ahelyett, hogy közvetlenül biztosít hozzáférést az egyes felhasználóknak. A csoportok alkalmazása helyett folyamatosan egyéni felhasználók hozzáadása növeli a nyomon követendő és kiértékelendő hozzáférés-vezérlési bejegyzések számát. Ha nem követi ezt az ajánlott eljárást, az az indexhez szükséges gyakoribb biztonsági metaadat-frissítésekhez vezethet, mivel ezek a metaadatok megváltoznak, ami a frissítési folyamat nagyobb késését és hatékonysági zavarait okozza.

Engedélyek szinkronizálása indexelt és forrástartalom között

Az ACL- vagy RBAC-bővítés engedélyezése egy indexelőn csak két esetben működik automatikusan:

• Az első teljes indexelő futtatás/adatbejárás: minden, az adott pillanatban létező engedély metaadatai rögzítve lesznek az egyes dokumentumokhoz.

• Az ACL/RBAC-támogatás engedélyezése után hozzáadott vadonatúj dokumentumok: az ACL/RBAC-információk a tartalommal együtt kerülnek betöltésre.

Ha módosítja a dokumentumengedélyeket, például felhasználót ad hozzá egy ACL-hez vagy egy szerepkör-hozzárendelést frissít, a módosítás csak akkor jelenik meg a keresési indexben, ha azt mondja az indexelőnek, hogy bejárja újra a dokumentum engedély metaadatait.

Válasszon az alábbi mechanizmusok közül attól függően, hogy hány elem változott:

Resetdocs (előzetes) API példája:

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

Példa újraszinkronizálási (előzetes verziójú) API-ra:

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

Törlés nyomon követése

A blobtörlés hatékony kezeléséhez győződjön meg arról, hogy a törléskövetés engedélyezve van, mielőtt az indexelő első alkalommal fut. Ez a funkció lehetővé teszi, hogy a rendszer észlelje a törölt blobokat a forrásban, és eltávolítsa őket az indexből.

Kapcsolódó tartalom

• Azure AI Keresés-hez való csatlakozás szerepkörök használatával
• Lekérdezés idejű ACL- és RBAC-kényszerítés
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API