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

Important

Diese Features und Funktionen sind Teil der REST-API 2026-05-01-Preview. Die 2026-05-01-preview wird Ihnen als Teil Ihres Azure-Abonnements zur Verfügung gestellt und unterliegt den für „Previews“ geltenden Bestimmungen in den Microsoft-Produktbestimmungen, dem Nachtrag zum Datenschutz für Microsoft-Produkte und -Dienste („DPA“) und den Ergänzenden Nutzungsbedingungen für Microsoft Azure-Vorschauen.

Die Vorschauversion 2026-05-01 unterstützt Verbindungen mit anderen Microsoft-Diensten und Diensten von Drittanbietern. Die Nutzung dieser Dienste unterliegt den jeweiligen Bestimmungen und kann dazu führen, dass Daten außerhalb der Azure-Compliancegrenze verarbeitet oder gespeichert werden und dass Daten in die Azure-Compliancegrenze fließen.

Die Vorschau 2026-05-01 kann keine Zugriffsberechtigungen ändern, die außerhalb der Vorschau von 2026-05-01 festgelegt wurden. Wenn Sie 2026-05-01-preview mit Inhalten mit Zugriffs- oder Berechtigungseinschränkungen verwenden, tritt eine zeitliche Verzögerung auf, bevor 2026-05-01-preview Änderungen an diesen Zugriffs- oder Berechtigungseinschränkungen erkennt.

Es liegt in Ihrer Verantwortung, zu verwalten, ob Ihre Daten außerhalb der Compliance- und geografischen Grenzen Ihrer Organisation und alle damit verbundenen Auswirkungen fließen und dass entsprechende Berechtigungen, Grenzen und Genehmigungen bereitgestellt werden.

Sie sind dafür verantwortlich, Anwendungen, die Sie im Kontext Ihrer spezifischen Anwendungsfälle erstellen, sorgfältig zu überprüfen und zu testen und alle geeigneten Entscheidungen und Anpassungen zu treffen. Dazu gehört die Implementierung ihrer eigenen verantwortungsvollen KI-Entschärfungen, wie Metaprompts, Inhaltsfilter oder andere Sicherheitssysteme, und sicherzustellen, dass Ihre Anwendungen angemessene Qualität, Zuverlässigkeit, Sicherheit und Vertrauenswürdigkeitsstandards erfüllen. Weitere Informationen finden Sie im Azure KI-Suche Transparenzhinweis.

Dieses Tutorial demonstriert, wie Sie Azure Data Lake Storage (ADLS) Gen2 Zugriffskontrolllisten (ACLs) und rollenbasierte Zugriffssteuerung (RBAC) mithilfe eines Indexers in einen Suchindex indexieren.

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

Verwandte Inhalte

  • Last updated on