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

Den här självstudien demonstrerar inmatning av behörighetsmetadata för Azure Data Lake Storage (ADLS) Gen2 (förhandsversion), där en Azure AI-sökning-indexerare lägger till åtkomstkontrollistor (ACL:er) och rollbaserad åtkomstkontroll (RBAC) som omfång i ett sökindex.

Den visar också hur du strukturerar en fråga som respekterar användaråtkomstbehörigheter. Ett lyckat frågeresultat bekräftar den behörighetsöverföring som inträffade under indexeringsfasen.

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 handledningen lär du dig att:

Använd en REST-klient för att slutföra den här självstudien och den senaste förhandsversionen av REST API:et. För närvarande finns det 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 hyrgäster och säkerhetsprincipaler ligger utanför omfattningen för den här handledningen.

• ADLS Gen2 med ett hierarkiskt namnområde.

• Filer i en hierarkisk mappstruktur. I den här självstudien förutsätts ADLS Gen2-demonstrationen av mappstrukturen för filen /Oregon/Portland/Data.txt. Den här handledningen vägleder dig genom ACL-tilldelning på mappar och filer så att du kan slutföra uppgiften.

• Azure AI-sökning, valfri region. Grundläggande nivå eller högre krävs för stöd för hanterad identitet.

• Visual Studio Code med klienttillägget REST.

Förbereda exempeldata

Ladda upp exempeldata för state parks 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.

• Aktivera rollbaserad åtkomst

• Konfigurera en systemtilldelad hanterad identitet.

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 dessa steg för att skaffa en personlig identitetstoken och konfigurera Visual Studio Code för lokala anslutningar till dina Azure-resurser.

Ange behörigheter i ADLS Gen2

Enligt bästa praxis bör du använda Group uppsättningar snarare än att direkt tilldela User uppsättningar.

1. Ge söktjänstens konto 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 .

2. 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.

3. 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.

4. Lägg till nya säkerhetsprincipaler för användare och grupper.

5. Ta bort befintliga huvudkonton för ägare av grupper, ägare av användare och övriga. Dessa huvudnamn 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 den senaste förhandsversions-REST-API:n eller ett förhandsversionspaket för Azure SDKs som tillhandahåller motsvarande funktioner. 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 handledningen använder du en systemtilldelad hanterad identitet för den autentiserade anslutningen.

{
    "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 dokumenten har lästs in kan du utföra sökfrågor mot dem med hjälp av Dokument - Sökförfrågan (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ärandehuvudet. Mer information finns i Frågetids-ACL och RBAC-tillämpning.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-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"
}

Relaterat innehåll

• https://github.com/Azure-Samples/azure-search-rest-samples/tree/main/acl