Sdílet prostřednictvím

Indexování seznamů řízení přístupu k dokumentům (ACL) pomocí nabízených rozhraní REST API

Note

Tato funkce je aktuálně ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučuje se pro produkční úlohy. Některé funkce nemusí být podporované nebo můžou mít omezené možnosti. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Indexování dokumentů spolu s přidruženými seznamy řízení přístupu (ACL) a kontejnerovými rolemi řízení přístupu (RBAC)Role-Based do indexu služby Azure AI Search prostřednictvím rozhraní REST API pro zasílání zachovává oprávnění na úrovni dokumentu k indexovanému obsahu v době dotazu.

Mezi klíčové funkce patří:

  • Flexibilní kontrola nad kanály příjmu dat
  • Standardizované schéma pro metadata oprávnění
  • Podpora hierarchických oprávnění, jako jsou seznamy ACL na úrovni složek

Tento článek vysvětluje, jak pomocí rozhraní REST API push indexovat metadata oprávnění na úrovni dokumentu ve službě Azure AI Search. Tento proces připraví index k dotazování a vynucování oprávnění koncových uživatelů k výsledkům hledání.

Prerequisites

  • Obsah s metadaty ACL z Microsoft Entra ID nebo jiného ACL systému ve stylu POSIX.

  • Nejnovější rozhraní REST API verze Preview nebo balíček Azure SDK verze Preview poskytující ekvivalentní funkce.

  • Schéma indexu s povoleným prvkem permissionFilterOption a také atributy pole permissionFilter, které ukládají oprávnění přidružená k dokumentu.

Limitations

  • Pole seznamu ACL s typem userIds filtru oprávnění nebo groupIds může obsahovat maximálně 32 hodnot.

  • Index může obsahovat maximálně pět jedinečných hodnot mezi poli typu rbacScope ve všech dokumentech. Počet dokumentů, které sdílejí stejnou hodnotu rbacScope, není nijak omezen.

  • Existující pole lze převést na permissionFilter typ pole pro použití s integrovanými seznamy ACL nebo filtrováním metadat RBAC. Chcete-li povolit filtrování u existujícího indexu, vytvořte nová pole nebo upravte existující pole tak, aby zahrnovalo permissionFilter.

  • V indexu může existovat pouze jedno pole každého permissionFilter typu (jedno z groupIds, usersIdsa rbacScope) v indexu.

  • Každé pole permissionFilter by mělo být nastaveno filterable na true.

  • Tato funkce se v současné době na webu Azure Portal nepodporuje.

Vytvoření indexu s poli filtru oprávnění

Indexování seznamů ACL dokumentu a metadat RBAC pomocí rozhraní REST API vyžaduje nastavení schématu indexu, které povoluje filtry oprávnění a má pole s přiřazeními filtru oprávnění.

Nejprve přidejte permissionFilterOption možnost. Platné hodnoty jsou enabled nebo disableda měli byste je nastavit na enabled. Můžete ho přepnout, disabled pokud chcete vypnout funkci filtru oprávnění na úrovni indexu.

Za druhé vytvořte pole řetězců pro metadata oprávnění a zahrňte permissionFilterje . Vzpomeňte si, že můžete mít jeden z každého typu filtru oprávnění.

Tady je základní příklad schématu, které zahrnuje všechny permissionFilter typy:

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

Příklad indexování rozhraní REST API

Jakmile budete mít index s poli filtru oprávnění, můžete tyto hodnoty naplnit pomocí rozhraní API pro nabízení indexování stejně jako u všech ostatních polí dokumentu. Tady je příklad použití zadaného schématu indexu, kde každý dokument určuje akci nahrání, pole klíče (DocumentId) a pole oprávnění. Mělo by mít také obsah, ale toto pole je v tomto příkladu vynecháno kvůli stručnosti.

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2025-11-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"
    }
  ]
}

Pravidla vyřešení přístupu ACL

Tato část vysvětluje, jak se přístup k dokumentům určuje pro uživatele na základě hodnot seznamu ACL přiřazených jednotlivým dokumentům. Klíčové pravidlo je, že uživatel musí odpovídat jenom jednomu typu seznamu ACL, aby získal přístup k dokumentu. Například pokud má dokument pole userIds, groupIds a rbacScope, uživatel může k dokumentu přistupovat tak, že spáruje kterékoliv z těchto polí s ACL.

Speciální hodnoty ACL „all“ a „none“

Pole seznamu ACL, například userIds a groupIds, obvykle obsahují seznamy identifikátorů GUID (Globálně jedinečné identifikátory), které identifikují uživatele a skupiny s přístupem k dokumentu. Pro tyto typy polí seznamu ACL jsou podporovány dvě speciální řetězcové hodnoty, "all" a "none". Tyto hodnoty fungují jako široké filtry pro řízení přístupu na globální úrovni, jak je znázorněno v následující tabulce.

userIds / groupIds hodnota Meaning
["all"] Každý uživatel má přístup k dokumentu.
["none"] K dokumentu nemůže přistupovat žádný uživatel na základě tohoto typu ACL.
[] (prázdné pole) K dokumentu nemůže přistupovat žádný uživatel na základě tohoto typu ACL.

Vzhledem k tomu, že uživatel musí splňovat pouze jeden typ pole, speciální hodnota "all" poskytuje veřejný přístup nezávisle na obsahu jakéhokoli jiného pole ACL, protože všichni uživatelé splňují podmínky a získávají oprávnění. Naproti tomu nastavení userIds na hodnotu none nebo empty znamená, že k dokumentu nemají přístup žádní uživatelé na základě jejich ID uživatele. Může být možné, že jim přístup stále udělí buď shoda jejich ID skupiny, nebo metadata RBAC.

Příklad řízení přístupu

Tento příklad ukazuje, jak se pravidla přístupu k dokumentu řeší na základě konkrétních hodnot polí seznamu ACL dokumentu. Pro čitelnost používá tento scénář místo identifikátorů GUID aliasy seznamu ACL, jako je user1, group1.

Dokument # userIds groupIds Rozsah RBAC Seznam povolených uživatelů Note
1 ["none"] [] Empty Žádní uživatelé nemají přístup Hodnoty ["none"] a [] se chovají úplně stejně.
2 ["none"] [] scope/to/container1 Uživatelé s oprávněními RBAC ke kontejneru1 Hodnota none neblokuje přístup tím, že odpovídá jiným polím seznamu ACL.
3 ["none"] ["skupina1", "skupina2"] Empty Členové skupiny1 nebo skupina2
4 ["all"] ["none"] Empty Libovolný uživatel Každý uživatel, který zadává dotaz, odpovídá kritériím filtru ACL "all", takže všichni uživatelé mají přístup.
5 ["all"] ["skupina1", "skupina2"] scope/to/container1 Libovolný uživatel Vzhledem k tomu, že všichni uživatelé odpovídají filtru "all" pro ID uživatele, nemají filtry groupID a RBAC žádný vliv.
6 ["user1", "user2"] ["group1"] Empty User1, user2 nebo jakýkoli člen skupiny1
7 ["user1", "user2"] [] Empty User1, user2 nebo jakýkoli uživatel s oprávněními RBAC ke kontejneru1

Viz také

  • Last updated on