Dokumentumhozzáférés-vezérlési listák (ACL-ek) indexelése a leküldéses REST API-k használatával (előzetes verzió)

A dokumentumszintű engedélybetöltés a leküldéses REST API-kon (előzetes verzió) keresztül lehetővé teszi a dokumentumok indexelését a hozzájuk tartozó hozzáférés-vezérlési listákkal (ACL-ekkel) és a tároló szerepköralapú hozzáférés-vezérlési (RBAC) szerepköreivel együtt. Amikor leküldi a tartalmat egy Azure AI Keresés indexbe a leküldéses REST API-kon keresztül, a szolgáltatás megőrzi az indexelt tartalomra vonatkozó engedélyeket, és a lekérdezéskor kényszeríti őket.

A legfontosabb funkciók a következők:

• Az adatbetöltési csatornák rugalmas vezérlése.
• Az engedélyek metaadatainak szabványosított sémája.
• Hierarchikus engedélyek, például mappaszintű ACL-ek támogatása.

Ez a cikk bemutatja, hogyan használható a leküldéses REST API a dokumentumszintű engedély metaadatainak indexelésére Azure AI Keresés. Ez a folyamat előkészíti az indexet a keresési eredményekre vonatkozó végfelhasználói engedélyek lekérdezésére és kikényszerítésére.

Előfeltételek

• Tartalom a Microsoft Entra ID vagy más POSIX típusú ACL-rendszer ACL-metaadataival. userIds Az groupIds ACL-mezőkhöz Microsoft Entra objektumazonosítókat (GUID-ket) használjon, ne UPN-eket vagy e-mail-címeket. A stabil objektumazonosítók megbízható identitás-egyeztetést biztosítanak a lekérdezési időben, még akkor is, ha a címtárattribútumok megváltoznak.

• A latest preview REST API vagy egy olyan előzetes verziójú Azure SDK csomag, amely egyenértékű funkciókat biztosít.

• A permissionFilterOption engedélyezést tartalmazó indexséma, valamint a dokumentumengedélyeket tároló permissionFilter mezőattribútumok.

Korlátozások

• Engedélyszűrő típusú userIds ACL-mező, vagy groupIds legfeljebb 1000 érték tárolására képes.

• Az index legfeljebb öt egyedi értéket tartalmazhat az összes dokumentum típusmezői rbacScope között. Az azonos értékű rbacScopedokumentumok száma nincs korlátozva.

• Egy meglévő mező frissíthető úgy, hogy tartalmazza permissionFilter a beépített ACL- vagy RBAC-metaadat-szűrés hozzárendelését. Ha egy meglévő index szűrését szeretné engedélyezni, adjon hozzá új mezőket, vagy frissítse a meglévő mezőket a permissionFilter értékkel.

• Egy indexben csak egy mező létezhet az egyes permissionFilter típusok közül (mindegyikgroupIdsuserIds, és rbacScope) .

• Minden permissionFilter mezőhöz állítsa be a filterable értékét true-re.

• A lekérdezési idő jogosultságának érvényesítése az indexbe legutóbb írt ACL-értékeket tükrözi. Ha a forrásengedélyek megváltoznak, ezek a frissítések mindaddig nem jelennek meg, amíg az érintett dokumentumok betöltése vagy frissítése nem történik meg. Növekményes újratöltés vagy részleges frissítések ütemezése az ACL-ek naprakészen tartásához.

• Ez a funkció jelenleg nem támogatott a Azure portálon.

Index létrehozása engedélyszűrő mezőkkel

A dokumentum ACL-jeinek és RBAC-metaadatainak REST API-val való indexeléséhez olyan indexsémát kell beállítani, amely engedélyezi az engedélyszűrőket, és engedélyszűrő-hozzárendeléssel rendelkező mezőket tartalmaz.

Először adja hozzá a elemet permissionFilterOption. Az érvényes értékek a enabled vagy a disabled, és enabled-re kell beállítani. Átállíthatja a disabled elemre, ha az engedélyszűrő funkciót az index szintjén ki szeretné kapcsolni.

Másodszor hozzon létre sztringmezőket az engedély metaadataihoz, és adja meg a következőket permissionFilter: Ne feledje, hogy minden engedélyszűrő-típusból választhat egyet.

Íme egy egyszerű példaséma, amely az összes permissionFilter típust tartalmazza:

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

Vállalati adattárak, például a SharePoint Online esetében a push API meghívása előtt, a betöltés során képezze le a dokumentumszintű vagy mappaszintű engedélyeket Microsoft Entra felhasználó- és csoportobjektum-azonosítókra. Ezután ezeket az azonosítókat a megfelelő engedélymezőkben kell tárolnia.

REST API indexelési példa

Miután rendelkezik engedélyszűrő mezőkkel rendelkező indexel, ezeket az értékeket feltöltheti a leküldéses indexelő API-val, ugyanúgy, mint bármely más dokumentummezővel. Íme egy példa a megadott indexséma használatával, ahol minden dokumentum megadja az indexelési műveletet, a kulcsmezőt (DocumentId) és az engedélymezőket. A dokumentumoknak tartalmazniuk kell a tartalmat is, de ez a mező hiányzik ebben a példában a rövidség kedvéért.

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 hozzáférés-kezelési szabályok

Ez a szakasz azt ismerteti, hogyan határozza meg a rendszer a felhasználó dokumentumhozzáférését az egyes dokumentumok engedélymezői alapján. Ezek a mezők ACL-ek (userIds és groupIds, ahol groupIds biztonsági csoportokat és Microsoft 365-csoportok) vagy RBAC-hatókört (rbacScope) tartalmaznak. Azure az RBAC-hatókört és az ACL-eket meghatározott sorrendben értékeli ki, az ADLS Gen2 engedélymodellel összhangban.

A felhasználó az alábbi mezők valamelyikének való megfeleléssel kap hozzáférést: egy egyező userIds- vagy groupIds-bejegyzéssel, vagy a rbacScope-höz tartozó jogosító Azure-szerepkörhozzárendeléssel. A hívóidentitások lekérdezési időben való megadásáról további információt a lekérdezési idejű ACL és az RBAC-kényszerítés című témakörben talál.

Speciális ACL-értékek: "all" és "none"

Az ACL-mezők, például userIds és groupIds, általában olyan grafikus felhasználói azonosítók (globálisan egyedi azonosítók) listáját tartalmazzák, amelyek azonosítják a dokumentumhoz hozzáféréssel rendelkező felhasználókat és csoportokat. Két speciális sztringérték, az "all" és a "none" támogatott ezekhez az ACL-mezőtípusokhoz. Ezek az értékek széles körű szűrőkként működnek a globális szintű hozzáférés szabályozásához, ahogy az az alábbi táblázatban is látható.

Mivel a felhasználónak csak egy mezőtípussal kell egyeznie, az "összes" speciális érték minden más ACL-mezőértéktől függetlenül nyilvános hozzáférést biztosít. Ezzel szemben a "nincs" vagy az üres tömb beállítása userIds azt jelenti, hogy egyetlen felhasználó sem kap hozzáférést a dokumentumhoz a felhasználói azonosító alapján. Előfordulhat, hogy még mindig kapnak hozzáférést, ha megfelelnek a csoportazonosító vagy az RBAC-metaadatok követelményeinek.

Hozzáférés-vezérlési példa

Ez a példa bemutatja, hogyan oldódnak fel a dokumentum-hozzáférési szabályok a ( és userIds) groupIdsengedélymező-értékek rbacScopealapján. Az olvashatóság érdekében ez a forgatókönyv olyan aliasokat használ, mint a "user1" és a "group1" a GUID-k helyett; éles környezetben Microsoft Entra objektumazonosítókat (GUID-ket) használjon.

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