Lernprogramm: Indizierung von Berechtigungsmetadaten aus ADLS Gen2 und Abfrage mit durch Berechtigungen gefilterten Ergebnissen (Vorschau)

Note

Azure KI-Suche ist über das Azure Portal, REST-APIs und Azure SDKs verfügbar. Es unterstützt auch Foundry IQ, die verwaltete Wissensschicht, die Unternehmensinhalte in wiederverwendbare, berechtigungsfähige Wissensbasen für Agenten im Microsoft Foundry-Portal transformiert.

Important

Features, Funktionen oder Eigenschaften, die als (Vorschau) gekennzeichnet sind, werden von keiner Dienstebenenvereinbarung (SLA) abgedeckt, werden für Produktionsworkloads nicht empfohlen und können geändert oder eingeschränkt werden, bevor sie allgemein verfügbar sind. Die Azure KI-Suche Vorschaubedingungen gelten für alle Vorschaufunktionen, unabhängig davon, ob sie eigenständig oder Teil eines allgemein verfügbaren Features ist.

In diesem Tutorial wird die Erfassung von Berechtigungsmetadaten (Vorschau) für Azure Data Lake Storage (ADLS) Gen2 gezeigt, bei der ein Azure KI-Suche-Indexer einem Suchindex Zugriffssteuerungslisten (Access Control Lists, ACLs) und den Bereich der rollenbasierten Zugriffssteuerung (RBAC) hinzufügt.

Außerdem wird gezeigt, wie Sie eine Abfrage strukturieren, die Benutzerzugriffsberechtigungen berücksichtigt. Ein erfolgreiches Abfrageergebnis bestätigt die Berechtigungsübertragung, die während des Indexprozesses stattgefunden hat.

Weitere Informationen zum Indizieren von ACLs finden Sie unter Verwenden eines ADLS Gen2-Indexers zum Erfassen von Berechtigungsmetadaten.

In diesem Lernprogramm erfahren Sie, wie Sie:

  • Konfigurieren von RBAC-Bereich und ACLs für eine adlsgen2 Datenquelle
  • Erstellen eines Azure KI-Suche Index mit Berechtigungsinformationsfeldern
  • Erstellen und Ausführen eines Indexers zum Erfassen von Berechtigungsinformationen in einen Index aus einer Datenquelle
  • Durchsuchen des soeben erstellten Indexes

Verwenden Sie einen REST-Client, um dieses Lernprogramm und die neueste Vorschau-REST-API abzuschließen. Derzeit gibt es keine Unterstützung für die ACL-Indizierung im Azure-Portal.

Voraussetzungen

  • Ein Azure Konto mit einem aktiven Abonnement. Erstellen Sie kostenlos ein Konto.

  • Microsoft Entra ID Authentifizierung und Autorisierung. Dienste und Apps müssen sich im selben Mandanten befinden. Rollenzuweisungen werden für jede authentifizierte Verbindung verwendet. Benutzer und Gruppen müssen sich im selben Mandanten befinden. Sie sollten über Benutzer und Gruppen verfügen, mit denen Sie zusammenarbeiten können. Das Erstellen von Mandanten und Sicherheitsprinzipalen ist nicht Teil dieses Tutorials.

  • ADLS Gen2 mit einem hierarchischen Namespace.

  • Dateien in einer hierarchischen Ordnerstruktur. In diesem Lernprogramm wird die ADLS Gen2-Demo der Ordnerstruktur für die Datei /Oregon/Portland/Data.txtvorausgesetzt. Diese Anleitung führt Sie durch die ACL-Zuweisung zu Ordnern und Dateien, damit Sie in der Lage sind, die Übung erfolgreich abzuschließen.

  • Azure KI-Suche, jede Region. Für die Unterstützung verwalteter Identitäten ist eine Basisebene oder höher erforderlich.

  • Visual Studio Code mit der REST-Clienterweiterung.

Vorbereiten von Beispieldaten

Laden Sie die beispieldaten für state parks in einen Container in ADLS Gen2 hoch. Der Containername sollte "Parks" sein und sollte zwei Ordner aufweisen: "Oregon" und "Washington".

Überprüfen der Suchdienstkonfiguration

Der Suchdienst muss für Microsoft Entra ID Authentifizierung und Autorisierung konfiguriert werden. Überprüfen Sie diese Checkliste, um sicherzustellen, dass Sie vorbereitet sind.

Abrufen eines persönlichen Identitätstokens für lokale Testzwecke

In diesem Lernprogramm wird davon ausgegangen, dass ein REST-Client auf einem lokalen System eine Verbindung mit Azure über eine öffentliche Internetverbindung herstellt.

Folgen Sie diesen Schritten, um ein persönliches Identitätstoken zu erwerben und Visual Studio Code für lokale Verbindungen zu Ihren Azure-Ressourcen einzurichten.

Festlegen von Berechtigungen in ADLS Gen2

Verwenden Sie Group-Sätze als bewährte Praxis, statt User-Sätze direkt zuzuweisen.

  1. Gewähren Sie der Suchdienstidentität Lesezugriff auf den Container. Der Indexer stellt eine Verbindung zu Azure Storage unter der Suchdienstidentität her. Der Suchdienst muss über Berechtigungen für den Speicher-Blob-Datenleser verfügen, um Daten abzurufen.

  2. Erteilen Sie gruppen- oder benutzerspezifische Berechtigungen in der Dateihierarchie. Identifizieren Sie in der Dateihierarchie alle Group und User Sätze, die Containern, Verzeichnissen und Dateien zugewiesen sind.

  3. Sie können das Azure-Portal verwenden, um ACLs zu verwalten. Wählen Sie im Speicherbrowser das Oregon-Verzeichnis und dann im Kontextmenü " ACL verwalten " aus.

  4. Fügen Sie neue Sicherheitsprinzipale für Benutzer und Gruppen hinzu.

  5. Entfernen Sie vorhandene Prinzipale für Besitzergruppen, Besitzerbenutzer und Sonstiges. Diese Prinzipale werden für die ACL-Indizierung während der Vorschau nicht unterstützt.

Erstellen eines Suchindex für Berechtigungsmetadaten

Erstellen Sie einen Index , der Felder für Inhalts- und Berechtigungsmetadaten enthält.

Achten Sie darauf, die latest Preview-REST-API oder ein Vorschaupaket Azure SDK zu verwenden, das gleichwertige Funktionen bereitstellt. Die Berechtigungsfiltereigenschaften sind nur in den Vorschau-APIs verfügbar.

Für Demozwecke ist das Berechtigungsfeld retrievable aktiviert, sodass Sie die Werte aus dem Index überprüfen können. In einer Produktionsumgebung sollten Sie retrievable deaktivieren, um das Leaken vertraulicher Informationen zu verhindern.

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

Erstellen einer Datenquelle

Ändern Sie die Datenquellenkonfiguration , um die Erfassung von Indexerberechtigungen und die Typen von Berechtigungsmetadaten anzugeben, die Sie indizieren möchten.

Eine Datenquelle benötigt indexerPermissionOptions.

Verwenden Sie in diesem Lernprogramm eine vom System zugewiesene verwaltete Identität für die authentifizierte Verbindung.

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

Erstellen und Ausführen des Indexers

Die Indexerkonfiguration für die Berechtigungsaufnahme geht es in erster Linie um die Definition von fieldMappings aus Berechtigungsmetadaten.

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

Nach der Indizierungserstellung und der sofortigen Ausführung werden die Dateiinhalte zusammen mit Berechtigungsmetadaten in den Index indiziert.

Ausführen einer Abfrage zum Überprüfen der Ergebnisse

Nachdem Dokumente geladen wurden, können Sie Abfragen über Documents - Search Post (REST) durchführen.

Der URI wird erweitert, um eine Abfrageeingabe einzuschließen, die mithilfe des /docs/search Operators angegeben wird. Das Abfragetoken wird im Anforderungsheader übergeben. Weitere Informationen finden Sie unter Abfragezeitpunkt-ACL- und RBAC-Implementierung.

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

Verwandte Inhalte

  • Last updated on