Een ADLS Gen2-indexeerfunctie gebruiken om metagegevens van machtigingen op te nemen en zoekresultaten te filteren op basis van gebruikerstoegangsrechten (preview)

Azure Data Lake Storage (ADLS) Gen2 ondersteunt per-gebruikerstoegang tot mappen en bestanden via toegangscontrolelijsten (ACL's) en role-based access control (Azure RBAC). Toegangsbeheer op basis van distributie (Azure ABAC) wordt niet ondersteund.

Azure AI Zoeken kan deze machtigingsmetagegevens (preview) naast documentinhoud opnemen met behulp van een preview-REST API. Gebruikers die geen toegang hebben tot een map of bestand in de opslag, zien de bijbehorende documenten niet in de zoekresultaten. Dit is een van de verschillende strategieën voor toegangsbeheer op documentniveau in Azure AI Zoeken.

In dit artikel wordt uitgelegd hoe u een ADLS Gen2-indexeerfunctie of ADLS Gen2-blobkennisbron configureert om automatisch machtigingsmetagegevens in een zoekindex op te halen . Het vormt een aanvulling op indexgegevens uit ADLS Gen2 en maakt een blobkennisbron voor ADLS Gen2 met informatie die specifiek is voor het opnemen van machtigingen. Zie Document-ACL's indexeren met behulp van de push-APIom handmatig machtigingenmetagegevens te pushen.

Voorwaarden

• Microsoft Entra ID verificatie en autorisatie. Services en apps moeten zich in dezelfde tenant bevinden. Gebruikers kunnen zich in verschillende tenants bevinden zolang alle tenants Microsoft Entra ID gebruiken. Roltoewijzingen worden gebruikt voor elke geverifieerde verbinding.

• Azure AI Zoeken in een factureerbare laag (Basic of hoger) in elke regio. De zoekservice moet op rollen gebaseerde toegang hebben ingeschakeld en een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit.

• ADLS Gen2-blobs in een hiërarchische naamruimte, met gebruikersmachtigingen verleend via ACL's of rollen.

• REST API-versie 2025-05-01-preview of hoger voor opname van indexeermachtigingen. REST API-versie 2025-11-01-preview of hoger voor ondersteuning van kennisbronnen. Gebruik de nieuwste preview REST API of een preview SDK-pakket dat machtigingsfilters ondersteunt.

Beperkingen

• De Azure-portal biedt geen ondersteuning voor deze functie.

• ADLS Gen2-limieten voor roltoewijzingen en ACL-vermeldingen zijn van toepassing.

• De owning users, owning groups, en Other (all) ACL-identiteitscategorieën worden niet ondersteund tijdens de preview. Gebruik named users en named groups toewijzingen in plaats daarvan.

• De volgende indexeerfuncties bieden geen ondersteuning voor overname van machtigingen in geïndexeerde documenten die afkomstig zijn van ADLS Gen2. Als u een van deze functies gebruikt in een vaardighedenset of indexeerfunctie, worden machtigingen op documentniveau niet opgenomen in de geïndexeerde inhoud.

  • Vaardigheid voor aangepaste web-API

  • Kennisopslag, inclusief de assetopslag die vereist is voor het aanbieden van afbeeldingen (preview) binnen agentische retrieval. Daarom wordt het aanbieden van afbeeldingen niet ondersteund voor kennisbronnen waarin ACL's of RBAC-scopes worden ingelezen.

  • Indexer-verrijkingscache

  • Debug-sessies

Ondersteuning voor het machtigingsmodel

In deze sectie worden functies voor toegangsbeheer op documentniveau vergeleken tussen ADLS Gen2 en Azure AI Zoeken. Hierin wordt uitgelegd welke Azure Data Lake Storage (ADLS) Gen2-toegangsbeheermechanismen AI Search ondersteunt of in kaart brengt. Dit helpt u te begrijpen hoe machtigingen worden afgedwongen op documentniveau.

Tijdens query's evalueert Azure AI Zoeken eerst RBAC op containerniveau en controleert vervolgens de ACL-vermeldingen op documentniveau. Toegang wordt verleend als een mechanisme dit toestaat.

Over hiërarchische ACL-machtigingen

Indexeerfuncties en kennisbronnen kunnen ACL-toewijzingen ophalen uit de opgegeven container en alle mappen die naar elk bestand leiden door de hiërarchische toegangsevaluatiestroom van ADLS Gen2 te volgen. De laatste effectieve toegangslijsten voor elk bestand worden berekend en de verschillende toegangscategorieën worden geïndexeerd in de bijbehorende indexvelden.

Bijvoorbeeld, in ADLS Gen2-veelvoorkomende scenario's met betrekking tot machtigingen als het bestandspad /Oregon/Portland/Data.txt.

De indexeerfunctie of kennisbron verzamelt ACL's van elke container en map. Dan wordt de effectieve toegang op lagere niveaus vastgesteld en gaat verder totdat de machtigingen voor elk bestand zijn vastgesteld.

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

ADLS Gen2 configureren

Een indexeerfunctie of kennisbron kan ACL's ophalen in een opslagaccount als aan de volgende criteria wordt voldaan. Zie ADLS Gen2 ACL-toewijzingen voor meer informatie over ACL-toewijzingen.

Vergunning

Voor het indexeren moet de identiteit van uw zoekservice de Storage Blob Data Reader-machtiging hebben.

Als u lokaal test, moet u ook een roltoewijzing opslagblobgegevenslezer hebben. Zie Connect to Azure Storage using a managed identity voor meer informatie.

Hoofdcontainermachtigingen:

1. Wijs alle Group en User sets (beveiligingsprinciplen) toe aan de hoofdcontainer / met Read en Execute machtigingen.

2. Zorg ervoor dat zowel Read als Execute worden toegevoegd als 'standaardmachtigingen', zodat ze automatisch worden doorgegeven aan nieuw aangemaakte bestanden en mappen.

Machtigingen naar beneden doorgeven in de bestandshiërarchie

Hoewel nieuwe mappen en bestanden machtigingen overnemen, nemen bestaande mappen en bestanden deze toewijzingen niet automatisch over.

Gebruik het ADLS Gen2-hulpprogramma om ACL's recursief toe te passen voor het doorgeven van toewijzingen aan bestaande inhoud. Met dit hulpprogramma worden de ACL-toewijzingen van de hoofdcontainer doorgegeven aan alle onderliggende mappen en bestanden.

Overtollige machtigingen verwijderen

Nadat acl's recursief zijn toegepast, controleert u de machtigingen voor elke map en elk bestand.

Verwijder een Group of User sets die geen toegang mogen hebben tot specifieke mappen of bestanden. Verwijder bijvoorbeeld User2 in map Portland/en voor map Idaho verwijderen Group2 en User2 uit de toewijzingen, enzovoort.

Voorbeeldstructuur van ACL-toewijzingen

Hier is een diagram van de ACL-toewijzingsstructuur voor de fictieve directoryhiërarchie in de ADLS Gen2-documentatie.

ACL-toewijzingen na verloop van tijd bijwerken

Na verloop van tijd, wanneer nieuwe ACL-toewijzingen worden toegevoegd of gewijzigd, herhaal de voorgaande stappen om ervoor te zorgen dat de machtigingen correct worden verspreid en uitgelijnd. Bijgewerkte machtigingen in ADLS Gen2 worden bijgewerkt in de zoekindex wanneer u de inhoud opnieuw opneemt met behulp van de indexeerfunctie of kennisbron.

Azure AI Zoeken configureren

Zoals u weet, moet de zoekservice beschikken over:

• Op rollen gebaseerde toegang ingeschakeld
• De beheerde identiteit is geconfigureerd

Vergunning

Voor indexering moet de client die de API-aanroep uitgeeft, de machtiging Inzender voor de zoekservice hebben om objecten te maken, de machtiging Inzender voor zoekindexgegevens om gegevensimport uit te voeren en zoekindexgegevenslezer om een query uit te voeren op een index.

Als je lokaal test, moet je dezelfde roltoewijzingen hebben. Voor meer informatie, zie Verbind met Azure AI Zoeken met behulp van rollen.

Een kennisbron configureren

Als u een kennisbron gebruikt, worden definities in de kennisbron gebruikt om een volledige indexeringspijplijn (indexeerfunctie, gegevensbron en index) te genereren. ACL-toewijzingen worden gedetecteerd en automatisch opgenomen in de gegenereerde index. Het is niet nodig om een van de gegenereerde objecten te wijzigen als u de overname van machtigingen in uw geïndexeerde inhoud wilt.

Belangrijke punten over de configuratie waarmee deze werkt voor dit scenario:

• isADLSGen2 is ingesteld op true, waarmee voldaan wordt aan de vereiste van de gegevensbron voor dit scenario.
• ingestionPermissionOptions geeft gebruikers- en groeps-id's op.

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

Indexeerfunctie-gebaseerde indexering configureren

Als u een indexeerfunctie gebruikt, configureert u deze, de gegevensbron en de index om machtigingsmetagegevens op te halen uit ADLS Gen2-blobs.

De gegevensbron maken

Deze sectie is een aanvulling op Indexgegevens van ADLS Gen2 met informatie die specifiek is voor het opnemen van machtigingen naast documentinhoud in een Azure AI Zoeken-index.

• Het gegevensbrontype moet zijn adlsgen2.

• De gegevensbron moet hebben indexerPermissionOptions met userIds, groupIdsen/of rbacScope.

  • Configureer voor rbacScope de verbindingsreeks in het formaat voor beheerde identiteiten.

  • Voor verbindingsreeksen met een door de gebruiker toegewezen beheerde identiteit moet u ook de identity eigenschap opgeven.

JSON-voorbeeld met door het systeem beheerde identiteit:

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

Voorbeeld van een JSON-schema met een door de gebruiker beheerde identiteit in de verbindingsreeks:

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

Machtigingsvelden maken in de index

Controleer in Azure AI Zoeken of uw index velddefinities bevat voor de machtigingsmetagegevens. Machtigingsmetagegevens kunnen worden geïndexeerd wanneer indexerPermissionOptions deze is opgegeven in de definitie van de gegevensbron.

Aanbevolen schemakenmerken voor ACL (UserIds, GroupIds) en RBAC-bereik:

• Veld Gebruikers-id (ID) met userIds permissionFilter-waarde.
• Veld Groeps-ID's met de waarde van groupIds permissionFilter.
• RBAC-bereikveld met rbacScope permissionFilter-waarde.
• Eigenschap permissionFilterOption voor het inschakelen van filteren tijdens het uitvoeren van query's.
• Stringvelden gebruiken voor machtigingsmetagegevens
• Stel filterable in op waar voor alle velden.

U ziet dat dit retrievable onwaar is. U kunt dit op true zetten tijdens de ontwikkeling om te verifiëren dat de machtigingen aanwezig zijn, maar vergeet niet het terug te zetten op false voordat u deze in een productieomgeving implementeert.

JSON-schemavoorbeeld:

{
  ...
  "fields": [
    ...
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

De indexeerfunctie configureren

Veldtoewijzingen in een indexer leggen het gegevenspad naar velden in een index. Voor doel- en doelvelden die per naam of gegevenstype variëren, is een expliciete veldtoewijzing vereist. De volgende metagegevensvelden in ADLS Gen2 hebben mogelijk veldtoewijzingen nodig als u de veldnaam wijzigt:

• metadata_user_ids (Collection(Edm.String)) - de lijst met id's van ACL-gebruikers.
• metadata_group_ids (Collection(Edm.String)) - de lijst met ACL-groeps-id's.
• metadata_rbac_scope (Edm.String) - het RBAC-bereik van de container.

Geef fieldMappings in de indexeerfunctie op om de machtigingsmetagegevens tijdens het indexeren te routeren naar doelvelden.

JSON-schemavoorbeeld:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Aanbevelingen en best practices

• Plan de ADLS Gen2-mapstructuur zorgvuldig voordat u mappen maakt.

• Organiseer identiteiten in groepen en gebruik indien mogelijk groepen in plaats van rechtstreeks toegang te verlenen aan afzonderlijke gebruikers. Het continu toevoegen van afzonderlijke gebruikers in plaats van het toepassen van groepen verhoogt het aantal vermeldingen voor toegangsbeheer dat moet worden bijgehouden en geëvalueerd. Als u deze aanbevolen procedure niet volgt, kan dit leiden tot frequentere updates van beveiligingsupdates die nodig zijn voor de index, omdat deze metagegevens veranderen, waardoor er meer vertragingen en inefficiënties optreden in het vernieuwingsproces.

Machtigingen synchroniseren tussen geïndexeerde en broninhoud

Het inschakelen van ACL- of RBAC-verrijking op een indexer werkt automatisch alleen in twee situaties:

• De allereerste volledige indexeerfunctie wordt uitgevoerd/gegevens verkennen: alle metagegevens van machtigingen die op dat moment voor elk document bestaan, worden vastgelegd.

• Gloednieuwe documenten die zijn toegevoegd nadat ACL-/RBAC-ondersteuning is ingeschakeld: hun ACL/RBAC-gegevens worden opgenomen samen met hun inhoud.

Als u documentmachtigingen wijzigt, zoals het toevoegen van een gebruiker aan een ACL of het bijwerken van een roltoewijzing, wordt de wijziging niet weergegeven in de zoekindex, tenzij u de indexeerfunctie vertelt dat de metagegevens van het document opnieuw moeten worden verkend.

Kies een van de volgende mechanismen, afhankelijk van het aantal gewijzigde items:

Voorbeeld van resetdocs -API (preview):

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{ 
  "documentKeys": [ 
    "1001", 
    "4452" 
  ]
}

Api-voorbeeld opnieuw synchroniseren (preview):

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{ 
  "options": [ 
    "permissions" 
  ] 
} 

Verwijdering bijhouden

Als u blobverwijdering effectief wilt beheren, moet u ervoor zorgen dat het bijhouden van verwijderingen is ingeschakeld voordat de indexeerfunctie voor het eerst wordt uitgevoerd. Met deze functie kan het systeem verwijderde blobs in uw bron detecteren en uit de index verwijderen.

Verwante inhoud

• 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