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

Příjem oprávnění na úrovni dokumentu prostřednictvím rozhraní push REST API (Preview) umožňuje indexovat dokumenty spolu s přidruženými seznamy řízení přístupu (ACL) a kontejnerovými rolemi řízení přístupu na základě role (RBAC). Když vkládáte obsah do indexu služby Azure AI Vyhledávač prostřednictvím rozhraní push REST API, služba tato oprávnění zachovává u zaindexovaného obsahu a vynucuje je při dotazování.

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 v Azure AI Vyhledávač. Tento proces připraví index k dotazování a vynucování oprávnění koncových uživatelů k výsledkům hledání.

Požadavky

• Obsah s metadaty seznamu ACL z Microsoft Entra ID nebo jiného systému seznamu ACL ve stylu POSIX. Pro pole userIds a groupIds seznamu ACL použijte ID objektů Microsoft Entra (GUID), nikoli identifikátory UPN ani e-mailové adresy. Stabilní ID objektů zajišťují spolehlivé porovnávání identit v době dotazu, i když se změní atributy adresáře.

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

• Schéma indexu s povoleným permissionFilterOption, plus atributy polí permissionFilter, které ukládají oprávnění k dokumentu.

Omezení

• Pole seznamu ACL s typem userIds filtru oprávnění nebo groupIds může obsahovat maximálně 1 000 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 aktualizovat tak, aby zahrnovalo permissionFilter přiřazení pro vestavěné filtrování metadat ACL nebo RBAC. Pokud chcete povolit filtrování u existujícího indexu, přidejte nová pole nebo aktualizujte existující pole tak, aby obsahovala permissionFilter hodnotu.

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

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

• Vynucování oprávnění při dotazu odráží hodnoty ACL naposledy zapsané do indexu. Pokud se změní zdrojová oprávnění, tyto změny se nepromítnou, dokud znovu nenačtete nebo neaktualizujete dotčené dokumenty. Naplánujte přírůstkové opětovné načtení nebo částečné aktualizace, aby seznamy řízení přístupu (ACL) zůstaly aktuální.

• Tato funkce se v současné době na portálu Azure 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. Platné hodnoty jsou enabled nebo disableda měli byste je nastavit na enabled. Můžete jej přepnout na disabled, pokud chcete vypnout funkci filtrování oprávnění na úrovni indexu.

Za druhé vytvořte textová pole pro metadata oprávnění a zahrňte permissionFilter. 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"
}

U podnikových úložišť, jako je SharePoint Online, převeďte oprávnění na úrovni dokumentů nebo složek na ID objektů uživatelů a skupin ve službě Microsoft Entra během ingestace před voláním rozhraní push API. Pak byste je měli uložit do odpovídajících polí oprávnění.

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

Jakmile budete mít index s poli filtru pro oprávnění, můžete tyto hodnoty vyplnit pomocí rozhraní API push indexování stejně jako jakákoli jiná pole dokumentu. Tady je příklad použití zadaného schématu indexu, kde každý dokument určuje akci indexování, pole klíče (DocumentId) a pole oprávnění. Dokumenty by také měly obsahovat 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=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"
    }
  ]
}

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

Tato část vysvětluje, jak systém určuje přístup k dokumentům uživatele na základě polí oprávnění v jednotlivých dokumentech. Tato pole jsou buď seznamy řízení přístupu (ACL) (userIds a groupIds, kde groupIds zahrnuje skupiny zabezpečení a skupiny Microsoft 365), nebo obor zabezpečení RBAC (rbacScope). Azure vyhodnotí rozsah RBAC a seznamy ACL v definovaném pořadí v souladu s modelem oprávnění ADLS Gen2.

Uživatel získá přístup tím, že splňuje jedno z následujících polí: odpovídající userIds nebo groupIds vstupní položku nebo opravňující Azure přiřazení role pro dané rbacScopepole . Další informace o tom, jak jsou v čase dotazu poskytovány identity volajících, najdete v tématu Vynucování ACL a RBAC v čase dotazu.

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.

Vzhledem k tomu, že uživatel musí odpovídat pouze jednomu typu pole, speciální hodnota "all" uděluje veřejný přístup bez ohledu na všechny ostatní hodnoty polí seznamu ACL. Naproti tomu nastavení userIds na hodnotu none nebo prázdné pole znamená, že k dokumentu nemají přístup žádní uživatelé na základě ID uživatele. Přístup jim může být stále udělen podle odpovídajícího ID skupiny nebo metadat RBAC.

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

Tento příklad ukazuje, jak jsou pravidla přístupu k dokumentu vyřešena na základě hodnot polí oprávnění v userIdsgroupIds, a rbacScope. Pro čitelnost používá tento scénář aliasy, jako je user1 a group1 místo identifikátorů GUID. v produkčním prostředí použijte id objektů (GUID) Microsoft Entra.

Související obsah

• 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