Självstudie: Indexering av behörighetsmetadata från ADLS Gen2 och fråga med behörighetsfiltrerade resultat

2025-05-20

Den här självstudien visar hur du indexerar åtkomstkontrollistor (ACL) för Azure Data Lake Storage (ADLS) Gen2 och rollbaserad åtkomstkontroll (RBAC) till ett sökindex med hjälp av en indexerare.

Den visar också hur du strukturerar en fråga som respekterar användaråtkomstbehörigheter. Ett lyckat resultat för en sökfråga bekräftar den behörighetsöverföring som inträffade under indexeringen.

Mer information om indexering av ACL:er finns i Använda en ADLS Gen2-indexerare för att mata in behörighetsmetadata.

I den här tutorialen lär du dig följande:

Konfigurera RBAC-omfång och ACL:er på en adlsgen2 datakälla
Skapa ett Azure AI Search-index som innehåller behörighetsinformationsfält
Skapa och kör en indexerare för att mata in behörighetsinformation i ett index från en datakälla
Söka i indexet som du precis skapade

Använd en REST-klient för att slutföra den här självstudien och REST API:et 2025-05-01-preview. Det finns för närvarande inget stöd för ACL-indexering i Azure-portalen.

Förutsättningar

Ett Azure-konto med en aktiv prenumeration. Skapa ett konto kostnadsfritt.
Microsoft Entra ID-autentisering och auktorisering. Tjänster och appar måste finnas i samma klientorganisation. Rolltilldelningar används för varje autentiserad anslutning. Användare och grupper måste finnas i samma klientorganisation. Du bör ha användare och grupper att arbeta med. Att skapa klientorganisationer och säkerhetsobjekt ligger utanför omfånget för den här handledningen.
ADLS Gen2 med ett hierarkiskt namnområde.
Filer i en hierarkisk mappstruktur. Den här guiden antar ADLS Gen2-demonstration av mappstruktur för filen /Oregon/Portland/Data.txt. Den här handledningen vägleder dig genom ACL-tilldelning för mappar och filer så att du kan slutföra övningen framgångsrikt.
Azure AI Search, vilken region som helst. Grundläggande nivå eller högre krävs för stöd för hanterad identitet.
Visual Studio Code med en REST-klient eller en Python-klient och Ett Jupyter-paket.

Förbereda exempeldata

Ladda upp provdata för delstatsparker till en container i ADLS Gen2. Containernamnet ska vara "parks" och det ska ha två mappar: "Oregon" och "Washington".

Kontrollera konfigurationen av söktjänsten

Du måste konfigurera söktjänsten för Microsoft Entra-ID-autentisering och auktorisering. Granska den här checklistan för att se till att du är förberedd.

Hämta en personlig identitetstoken för lokal testning

Den här självstudien förutsätter att en REST-klient i ett lokalt system ansluter till Azure via en offentlig Internetanslutning.

Följ de här stegen för att hämta en personlig identitetstoken och konfigurera Visual Studio Code för lokala anslutningar till dina Azure-resurser.

Ange behörigheter i ADLS Gen2

Vi rekommenderar att du använder Group uppsättningar istället för att direkt tilldela User uppsättningar.

Ge söktjänstens identitet läsbehörighet till containern. Indexeraren ansluter till Azure Storage under söktjänstens identitet. Söktjänsten måste ha behörighet att hämta data i Storage Blob Data Reader .
Bevilja behörigheter per grupp eller användare i filhierarkin. I filhierarkin identifierar du alla Group och User uppsättningar som har tilldelats containrar, kataloger och filer.
Du kan använda Azure-portalen för att hantera ACL:er. I Storage Browser väljer du katalogen Oregon och väljer sedan Hantera ACL på snabbmenyn.
Lägg till nya säkerhetsprincipaler för användare och grupper.
Ta bort befintliga huvudkonton för att äga grupper, äga användare och andra. Dessa principer stöds inte för ACL-indexering under förhandsversionen.

Skapa ett sökindex för behörighetsmetadata

Skapa ett index som innehåller fält för innehåll och behörighetsmetadata.

Se till att använda 2025-05-01-preview-dataplan REST-API eller en förhandsversion av Azure SDK som ger samma funktionalitet. Egenskaperna för behörighetsfilter är endast tillgängliga i förhandsversions-API:erna.

I demosyfte har retrievable behörighetsfältet aktiverats så att du kan kontrollera värdena från indexet. I en produktionsmiljö bör du inaktivera retrievable för att undvika läckage av känslig information.

{
  "name" : "my-adlsgen2-acl-index",
  "fields": [
    {
      "name": "name", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "description", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true    
    },
    {
      "name": "location", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "state", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "AzureSearch_DocumentKey", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
      "stored": true,
      "key": true
    },
    { 
      "name": "UserIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "userIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "GroupIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "groupIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "RbacScope", "type": "Edm.String", 
      "permissionFilter": "rbacScope", 
      "searchable": true, "filterable": false, "retrievable": true
    }
  ],
  "permissionFilterOption": "enabled"
}

Skapa en datakälla

Ändra datakällans konfiguration för att ange indexerarens behörighetsinmatning och vilka typer av behörighetsmetadata som du vill indexera.

En datakälla behöver indexerPermissionOptions.

I den här guiden använder du en systemtilldelad hanterad identitet för en autentiserad anslutning.

{
    "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": "parks",
    "query": null
    }
}

Skapa och köra indexeraren

Indexerarens konfiguration för behörighetsinmatning handlar främst om att fieldMappings definiera från behörighetsmetadata.

{
  "name" : "my-adlsgen2-acl-indexer",
  "dataSourceName" : "my-adlsgen2-acl-datasource",
  "targetIndexName" : "my-adlsgen2-acl-index",
  "parameters": {
    "batchSize": null,
    "maxFailedItems": 0,
    "maxFailedItemsPerBatch": 0,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "delimitedText",
      "firstLineContainsHeaders": true,
      "delimitedTextDelimiter": ",",
      "delimitedTextHeaders": ""
      },
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
    ]
  }
}

När indexeraren har skapats och körts omedelbart indexeras filinnehållet tillsammans med information om behörighetsmetadata i indexet.

Köra en fråga för att kontrollera resultaten

Nu när dokument har lästs in kan du skicka frågor mot dem med hjälp av Dokument – Sök efter (REST).

URI:n utökas till att omfatta en frågeindata, som anges med hjälp av operatorn /docs/search . Frågetoken skickas i begäranhuvudet. Mer information finns iQuery-Time ACL- och RBAC-tillämpning.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2025-05-01-preview
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{search-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

https://github.com/Azure-Samples/azure-search-rest-samples/tree/main/Quickstart-ACL