Indexera dokumentåtkomstkontrollistor (ACL: er) med hjälp av PUSH REST API:er (förhandsversion)

Inmatning av behörigheter på dokumentnivå via Push REST-API:erna (förhandsversion) gör att du kan indexera dokument tillsammans med deras associerade åtkomstkontrollistor (ACL:er) och containerns rollbaserade åtkomstkontrollroller (RBAC). När du push-överför innehåll till ett Azure AI-sökning index via PUSH REST API:er bevarar tjänsten dessa behörigheter för indexerat innehåll och framtvingar dem vid frågetillfället.

Viktiga funktioner är:

• Flexibel kontroll över inmatningspipelines.
• Standardiserat schema för behörighetsmetadata.
• Stöd för hierarkiska behörigheter, till exempel ACL:er på mappnivå.

Den här artikeln beskriver hur du använder PUSH REST API för att indexering av behörighetsmetadata på dokumentnivå i Azure AI-sökning. Den här processen förbereder ditt index för att fråga och framtvinga slutanvändarbehörigheter för sökresultat.

Förutsättningar

• Innehåll med ACL-metadata från Microsoft Entra ID eller ett annat ACL-system i POSIX-format. För ACL-fälten userIds och groupIds använder du Microsoft Entra-objekt-ID:n (GUID:er), inte UPN:er eller e-postadresser. Stabila objekt-ID:er säkerställer tillförlitlig identitetsmatchning vid frågetillfället, även om katalogattributen ändras.

• REST API:et latest preview eller ett förhandsversionspaket Azure SDKs som tillhandahåller motsvarande funktioner.

• Ett indexschema med permissionFilterOption aktiverad, plus permissionFilter fältattribut som lagrar dokumentbehörigheter.

Begränsningar

• Ett ACL-fält med behörighetsfiltertyp userIds eller groupIds kan innehålla högst 1 000 värden.

• Ett index kan innehålla högst fem unika värden bland fält av typen rbacScope i alla dokument. Det finns ingen gräns för antalet dokument som delar samma värde för rbacScope.

• Ett befintligt fält kan uppdateras för att inkludera en permissionFilter tilldelning för inbyggd ACL- eller RBAC-metadatafiltrering. Om du vill aktivera filtrering på ett befintligt index lägger du till nya fält eller uppdaterar befintliga fält för att inkludera ett permissionFilter värde.

• Endast ett fält av varje permissionFilter typ (ett av groupIds, userIdsoch rbacScope) kan finnas i ett index.

• Varje permissionFilter fält ska ha filterable angetts till true.

• Behörighetskontroll vid frågetillfället avspeglar de ACL-värden som senast har skrivits till indexet. Om källbehörigheterna ändras återspeglas inte dessa uppdateringar förrän du har ändrat eller uppdaterat de berörda dokumenten. Schemalägg inkrementell återinläsning eller delvisa uppdateringar för att hålla ACL:er aktuella.

• Den här funktionen stöds för närvarande inte i Azure portalen.

Skapa ett index med behörighetsfilterfält

Indexering av dokument-ACL:er och RBAC-metadata med REST-API:et kräver att du konfigurerar ett indexschema som aktiverar behörighetsfilter och har fält med tilldelningar av behörighetsfilter.

Lägg först till permissionFilterOption. Giltiga värden är enabled eller disabled, och du bör ange det till enabled. Du kan växla till disabled om du vill inaktivera funktioner för behörighetsfilter på indexnivå.

För det andra skapar du strängfält för dina behörighetsmetadata och inkluderar permissionFilter. Kom ihåg att du kan ha en av varje typ av behörighetsfilter.

Här är ett grundläggande exempelschema som innehåller alla permissionFilter typer:

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

För företagslagringsplatser, till exempel SharePoint Online, ska du vid importen matcha behörigheter på dokument- eller mappnivå mot Microsoft Entra-användares och -gruppers objekt-ID:n innan du anropar Push API:et. Du bör sedan lagra dessa ID:er i motsvarande behörighetsfält.

Exempel på REST API-indexering

När du har ett index med behörighetsfilterfält kan du fylla i dessa värden med hjälp av PUSH-indexerings-API:et, precis som andra dokumentfält. Här är ett exempel med det angivna indexschemat, där varje dokument anger indexeringsåtgärden, nyckelfältet (DocumentId) och behörighetsfälten. Dokument bör också innehålla innehåll, men det fältet utelämnas i det här exemplet för korthet.

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

Regler för ACL-åtkomstlösning

I det här avsnittet beskrivs hur systemet avgör en användares dokumentåtkomst baserat på behörighetsfälten i varje dokument. Dessa fält är antingen ACL:er (userIds och , där groupIds inkluderar säkerhetsgrupper och Microsoft 365-grupper) eller ett RBAC-omfång (groupIdsrbacScope). Azure utvärderar RBAC-omfånget och ACL:erna i en definierad ordning, i enlighet med ADLS Gen2-behörighetsmodellen.

En användare får åtkomst genom att uppfylla något av följande villkor: en matchande post för userIds eller groupIds, eller en berättigande Azure-rolltilldelning för rbacScope. Information om hur anroparidentiteter tillhandahålls vid frågetillfället finns i Frågetids-ACL och RBAC-tillämpning.

Specifika ACL-värden "all" och "none"

ACL-fält, till exempel userIds och groupIds, innehåller vanligtvis listor över GUID:er (globalt unika identifierare) som identifierar användare och grupper med åtkomst till dokumentet. Två specialsträngsvärden, "all" och "none", stöds för dessa ACL-fälttyper. Dessa värden fungerar som breda filter för att styra åtkomsten på global nivå, enligt följande tabell.

Eftersom en användare bara behöver matcha en fälttyp ger specialvärdet "alla" offentlig åtkomst oavsett andra ACL-fältvärden. Inställningen "ingen" eller en tom matris innebär däremot userIds att inga användare beviljas åtkomst till dokumentet baserat på användar-ID. De kan fortfarande beviljas åtkomst genom matchande grupp-ID eller RBAC-metadata.

Exempel på åtkomstkontroll

Det här exemplet illustrerar hur regler för dokumentåtkomst matchas baserat på behörighetsfältvärden i userIds, groupIdsoch rbacScope. För läsbarhet använder det här scenariot alias som "user1" och "group1" i stället för GUID. i produktion använder du Microsoft Entra objekt-ID :er (GUID).

Relaterat innehåll

• Anslut till Azure AI-sökning med hjälp av roller
• Frågetids-ACL och RBAC-tillämpning
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API