Freigeben über

Lernprogramm: Indizierung von Berechtigungsmetadaten aus ADLS Gen2 und Abfrage mit gefilterten Berechtigungsergebnissen

Dieses Tutorial veranschaulicht, wie Sie mithilfe eines Indexers Azure Data Lake Storage (ADLS) Gen2 Access Control Lists (ACLs) und den Umfang der rollenbasierten Zugriffssteuerung (RBAC) in einen Suchindex aufnehmen.

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

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

In diesem Tutorial lernen Sie Folgendes:

  • Konfigurieren Sie den RBAC-Bereich und die ACLs für eine adlsgen2 Datenquelle
  • Erstellen eines Azure AI Search-Indexes, der Berechtigungsinformationenfelder enthält
  • Erstellen und Ausführen eines Indexers zum Erfassen von Berechtigungsinformationen in einen Index aus einer Datenquelle
  • Durchsuchen des soeben erstellten Index

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. Kostenlos ein Konto erstellen.

  • Microsoft Entra ID-Authentifizierung und Autorisierung. Die Dienste und Apps müssen sich im selben Mandanten befinden. Rollenzuweisungen werden für jede authentifizierte Verbindung verwendet. Die Benutzenden 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 Thema 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 Schritt-für-Schritt-Anleitung führt Sie durch die ACL-Zuweisung zu Ordnern und Dateien, damit Sie erfolgreich die Übung abschließen können.

  • Azure AI Search, eine beliebige Region. Für die Unterstützung von verwalteten Identitäten ist die Grundstufe oder eine höhere Stufe erforderlich.

  • Visual Studio Code mit einem REST-Client oder einem Python-Client und Jupyter-Paket.

Vorbereiten der Beispieldaten

Laden Sie die Beispieldaten der 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 die 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 Tests

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

Führen Sie die folgenden Schritte aus, um ein persönliches Identitätstoken zu erwerben und Visual Studio Code für lokale Verbindungen mit Ihren Azure-Ressourcen einzurichten.

Festlegen von Berechtigungen in ADLS Gen2

Als bewährte Methode verwenden Sie Group Sets anstelle der direkten Zuweisung von User Sets.

  1. Gewähren Sie der Identität des Suchdiensts Lesezugriff auf den Container. Der Indexer verbindet sich mit Azure Storage unter der Identität des Suchdienstes. 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 besitzende Gruppen, Benutzende und andere. Diese Prinzipale werden für die Indizierung mit Zugriffssteuerungslisten (ACLs) während der Public Preview 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 neueste Vorschau-REST-API oder ein Vorschau-Azure SDK-Paket 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 Lecken von vertraulichen Informationen zu vermeiden.

{
  "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 Berechtigungserfassung dient in erster Linie zum Definieren 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 Sie Dokumente geladen haben, können Sie nun mithilfe der POST-REST-API für die Dokumentsuche Abfragen für diese Dokumente ausfü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 ACL- und RBAC-Erzwingung zur Abfragezeit.

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