Documenttoegangsbeheerlijsten (ACL's) indexeren met behulp van de PUSH REST API's (preview)

Met de opname van machtigingen op documentniveau via de push REST API's (preview) kunt u documenten indexeren, samen met de bijbehorende toegangsbeheerlijsten (ACL's) en containerrollen voor op rollen gebaseerd toegangsbeheer (RBAC). Wanneer u inhoud naar een Azure AI Zoeken-index pusht via de PUSH REST API's, behoudt de service deze machtigingen voor geïndexeerde inhoud en dwingt deze af tijdens het uitvoeren van query's.

Belangrijke functies zijn onder andere:

• Flexibele controle over opnamepijplijnen.
• Gestandaardiseerd schema voor metagegevens van machtigingen.
• Ondersteuning voor hiërarchische machtigingen, zoals ACL's op mapniveau.

In dit artikel wordt uitgelegd hoe u de PUSH REST API gebruikt om metagegevens van machtigingen op documentniveau te indexeren in Azure AI Zoeken. Met dit proces wordt uw index voorbereid om query's uit te voeren en machtigingen voor eindgebruikers af te dwingen voor zoekresultaten.

Voorwaarden

• Inhoud met ACL-metagegevens van Microsoft Entra ID of een ander ACL-systeem in POSIX-stijl. Gebruik voor userIds- en groupIds-ACL-velden Microsoft Entra object-ID's (GUID's), niet UPN's of e-mailadressen. Stabiele object-id's zorgen voor betrouwbare identiteitskoppeling tijdens de query, zelfs als de directorykenmerken veranderen.

• De latest preview REST API of een preview-Azure SDK-pakket met gelijkwaardige functies.

• Een indexschema met permissionFilterOption ingeschakeld, plus permissionFilter veldkenmerken waarmee documentmachtigingen worden opgeslagen.

Beperkingen

• Een ACL-veld met machtigingsfiltertype userIds of groupIds kan maximaal 1000 waarden bevatten.

• Een index kan maximaal vijf unieke waarden bevatten tussen velden van het type rbacScope voor alle documenten. Er is geen limiet voor het aantal documenten dat dezelfde waarde rbacScopeheeft.

• Een bestaand veld kan worden bijgewerkt om een permissionFilter toewijzing op te nemen voor ingebouwde ACL- of RBAC-metagegevensfiltering. Als u filteren op een bestaande index wilt inschakelen, voegt u nieuwe velden toe of werkt u bestaande velden bij om een permissionFilter waarde op te nemen.

• Er kan slechts één veld van elk permissionFilter type (één van groupIds, userIdsen rbacScope) in een index voorkomen.

• Elk permissionFilter veld moet filterable worden ingesteld op true.

• Het afdwingen van querytijdmachtigingen weerspiegelt de ACL-waarden die voor het laatst naar de index zijn geschreven. Als de bronmachtigingen veranderen, worden deze updates pas doorgevoerd als u de betreffende documenten opnieuw opneemt of bijwerkt. Plan incrementele heropname of gedeeltelijke updates om ACL's actueel te houden.

• Deze functionaliteit wordt momenteel niet ondersteund in de Azure-portal.

Een index maken met machtigingsfiltervelden

Voor het indexeren van document-ACL's en RBAC-metagegevens met de REST API moet u een indexschema instellen dat machtigingsfilterfilters mogelijk maakt en velden bevat met toewijzingen van machtigingenfilters.

Voeg eerst permissionFilterOption toe. Geldige waarden zijn enabled of disabled, en u moet deze instellen op enabled. U kunt deze disabled optie inschakelen als u de functionaliteit voor machtigingsfilters wilt uitschakelen op indexniveau.

Ten tweede maakt u stringvelden voor uw permissiemetadata en neem permissionFilter op. Zoals u weet, kunt u een van elk machtigingsfiltertype hebben.

Hier volgt een eenvoudig voorbeeldschema met alle permissionFilter typen:

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

Voor bedrijfsopslagplaatsen, zoals SharePoint Online, kunt u machtigingen op document- of mapniveau oplossen voor Microsoft Entra gebruikers- en groepsobject-id's tijdens de opname voordat u de push-API aanroept. Vervolgens moet u deze id's opslaan in de bijbehorende machtigingsvelden.

Voorbeeld van REST API-indexering

Zodra u een index met machtigingsfiltervelden hebt, kunt u deze waarden vullen met behulp van de push-indexerings-API, net als andere documentvelden. Hier volgt een voorbeeld met behulp van het opgegeven indexschema, waarbij elk document de indexeringsactie, het sleutelveld (DocumentId) en de machtigingsvelden specificeert. Documenten moeten ook inhoud bevatten, maar dat veld wordt weggelaten in dit voorbeeld voor beknoptheid.

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-toegangsoplossingsregels

In deze sectie wordt uitgelegd hoe het systeem de documenttoegang van een gebruiker bepaalt op basis van de machtigingsvelden voor elk document. Deze velden zijn ofwel ACL's (userIds en groupIds, waarbij groupIds beveiligingsgroepen en Microsoft 365-groepen omvat) of een RBAC-bereik (rbacScope). Azure evalueert het RBAC-bereik en de ACL's in een gedefinieerde volgorde, consistent met het ADLS Gen2-machtigingsmodel.

Een gebruiker krijgt toegang door te voldoen aan een van de volgende velden: een overeenkomende userIds of groupIds vermelding, of een in aanmerking komende Azure roltoewijzing voor de rbacScope. Zie ACL- en RBAC-afdwinging tijdens query-uitvoering voor informatie over hoe identiteiten van aanroepers worden verstrekt tijdens het uitvoeren van query's.

Speciale ACL-waarden "all" en "none"

ACL-velden, zoals userIds en groupIds, bevatten meestal lijsten met GUID's (Globally Unique Identifiers) waarmee gebruikers en groepen met toegang tot het document worden geïdentificeerd. Twee speciale tekenreekswaarden, 'all' en 'none', worden ondersteund voor deze ACL-veldtypen. Deze waarden fungeren als brede filters om de toegang op globaal niveau te beheren, zoals wordt weergegeven in de volgende tabel.

Omdat een gebruiker moet overeenkomen met slechts één veldtype, verleent de speciale waarde 'alle' openbare toegang, ongeacht andere ACL-veldwaarden. Als u daarentegen 'geen' of een lege matrix instelt, userIds krijgen gebruikers geen toegang tot het document op basis van de gebruikers-id. Ze kunnen nog steeds toegang krijgen met een overeenkomende groeps-ID of RBAC-metagegevens.

Voorbeeld van toegangsbeheer

In dit voorbeeld ziet u hoe regels voor documenttoegang worden omgezet op basis van machtigingsveldwaarden in userIds, groupIdsen rbacScope. Voor leesbaarheid gebruikt dit scenario aliassen zoals 'user1' en 'group1' in plaats van GUID's; gebruik in productie Microsoft Entra object-id's (GUID's).

Verwante onderwerpen

• Verbinden met Azure AI Zoeken door gebruik te maken van rollen
• ACL- en RBAC-afdwinging tijdens querytijd
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API