Tutorial: ADLS Gen2-Berechtigungen indizieren und gefilterte Ergebnisse überprüfen

Note

Foundry IQ (Azure KI-Suche) bietet direkte Indizierungs- und Abfrage-APIs zusammen mit Wissensquellen- und Knowledge Base-APIs auf höherer Ebene für den verwalteten Abruf. Verwenden Sie das Azure Portal, REST-APIs oder Azure SDKs, um diese Funktionen zu konfigurieren, oder verbinden Sie Agents mit Wissensdatenbanken im Microsoft Foundry-Portal.

Dieses Lernprogramm veranschaulicht Azure Data Lake Storage (ADLS) Gen2-Berechtigungsmetadatenaufnahme, bei der ein Foundry IQ (Azure KI-Suche) Indexer Zugriffssteuerungslisten (ACCESS Control Lists, ACLs) und rollenbasierten Zugriffssteuerungsbereich (RBAC) zu einem Suchindex hinzufügt. Diese Funktionalität ist allgemein in der REST-API 2026-10-01verfügbar.

Außerdem wird gezeigt, wie Sie nach der Indizierung Abfragen als zugelassene und abgelehnte Benutzer ausführen und Berechtigungsänderungen überprüfen.

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 Sie einen Foundry IQ-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 und REST API 2026-10-01. 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. 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.

  • Foundry IQ, beliebige 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

Erstellen Sie einen Container mit dem Namen parks in ADLS Gen2. Laden Sie zwei Nur-Text-Dateien mit unterschiedlichem Inhalt hoch:

  • Oregon/Portland/Data.txt
  • Washington/Seattle/Data.txt

In diesem Lernprogramm wird der Standardanalysemodus verwendet, um ein Suchdokument pro Datei zu erstellen. Der Index speichert den Dateinamen und extrahierten Text. Die .txt Dateien erfordern den speziellen text Analysemodus nicht, der mit Berechtigungen auf Dokumentebene nicht unterstützt wird. Siehe Unterstützte Analyse und Inhaltsextraktion für die Erfassung von Berechtigungen.

Überprüfen der Konfiguration des Foundry IQ-Diensts

Konfigurieren Sie Ihren Foundry IQ-Dienst für Microsoft Entra ID Authentifizierung und Autorisierung. Ü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.

Führen Sie die folgenden Schritte aus, um ein persönliches Identitätstoken abzurufen und Visual Studio Code für lokale Verbindungen mit 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 Foundry IQ-Dienstidentität Lesezugriff auf den Container. Der Indexer stellt unter der Foundry IQ-Dienstidentität eine Verbindung mit Azure Storage her. Der Foundry IQ-Dienst muss über die Berechtigung Storage Blob Data Reader zum Abrufen von Daten verfügen.

  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. Verwenden Sie benannte Benutzer und benannte Gruppen für die Testberechtigungen. Besitzender Benutzer, besitzende Gruppe und andere Einträge werden für die ACL-Indizierung nicht unterstützt; verlassen Sie sich nicht auf sie für die Testidentitäten.

Überprüfen Sie vor der Indizierung die Quell-ACLs auf nicht unterstützte implizite blocklists und korrigieren Sie sie mit unterstützten allowlists.

Erstellen eines Suchindex für Berechtigungsmetadaten

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

Verwenden Sie DIE REST-API 2026-10-01 für die Index-, Datenquellen- und Indexeranforderungen.

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": "metadata_storage_path", "type": "Edm.String",
      "searchable": false, "filterable": true, "retrievable": true
    },
    {
      "name": "name", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "content", "type": "Edm.String",
      "searchable": true, "retrievable": true, "filterable": false
    },
    {
      "name": "id", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true, "stored": true,
      "key": true
    },
    { 
      "name": "UserIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "userIds", 
      "searchable": false, "filterable": true, "retrievable": true
    },
    { 
      "name": "GroupIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "groupIds", 
      "searchable": false, "filterable": true, "retrievable": true
    },
    { 
      "name": "RbacScope", "type": "Edm.String", 
      "permissionFilter": "rbacScope", 
      "searchable": false, "filterable": true, "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

Definieren Sie die oberste Ebene fieldMappings für den rohen Quellpfad und Berechtigungsmetadaten. metadata_storage_path ist auch dann erforderlich, wenn Sie nur RBAC-Scopes aufnehmen. Codieren Sie dieses Feld nicht.

{
  "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": "default",
      "refreshAllAcls": true
    }
  },
  "fieldMappings": [
    { "sourceFieldName": "metadata_storage_path", "targetFieldName": "id", "mappingFunction": { "name": "base64Encode" } },
    { "sourceFieldName": "metadata_storage_name", "targetFieldName": "name" },
    { "sourceFieldName": "metadata_storage_path", "targetFieldName": "metadata_storage_path" },
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Das Erstellen des Indexers startet die erste Ausführung. Verwenden Sie vor der Abfrage Get Indexer Status, um zu bestätigen, dass die Ausführung erfolgreich abgeschlossen wurde. Überprüfen Sie Fehler und Warnungen, und überprüfen Sie, ob beide Dateien indiziert wurden.

Wenn Sie beabsichtigen, die automatische ACL-Aktualisierung zum Überprüfen von Berechtigungsänderungen zu verwenden, konfigurieren Sie einen Indexerzeitplan.

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/my-adlsgen2-acl-index/docs/search?api-version=2026-10-01
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{query-user-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,content,metadata_storage_path,GroupIds"
}

Der Authorization Header autorisiert Ihre Anwendung zum Abfragen von Search. query-user-token ist das Token des delegierten Benutzers für die Berechtigungsauswertung; es kann eine andere Identität darstellen.

Berechtigungsänderungen überprüfen

  1. Abfrage als benannter Benutzer mit Dateilesezugriff und Ausführungs-/Durchquerungszugriff über die übergeordneten Verzeichnisse. Vergewissern Sie sich, dass das erwartete Dokument angezeigt wird.
  2. Abfrage als Benutzer ohne übereinstimmende Benutzer- oder Gruppen-ACL und ohne unterstützte Container-RBAC-Berechtigung. Vergewissern Sie sich, dass dasselbe Dokument nicht vorhanden ist.
  3. Entfernen Sie die ACL-Gewährung des ersten Benutzers, ohne Dateiinhalte zu ändern. Stellen Sie sicher, dass keine andere ACL- oder unterstützte RBAC-Berechtigung den Benutzer autorisiert. Fordern Sie eine erneute Synchronisierung von Berechtigungen an, und führen Sie den Indexer aus, oder warten Sie auf eine zutreffende automatische ACL-Aktualisierung.
  4. Wiederholen Sie nach Abschluss beide Abfragen. Der widerrufene Benutzer darf das Dokument nicht mehr abrufen, während ein anderer explizit autorisierter Benutzer das Dokument weiterhin abrufen kann.
  5. Wiederholen Sie diesen Vorgang mit einer benannten Gruppe, einer Gewährung oder Entfernung und einer Änderung der Traversierung eines übergeordneten Verzeichnisses. Testen Sie RBAC-Berechtigungen oder -Entzüge separat, unter Berücksichtigung von Storage-Propagierung und Abfrageautorisierungs-Caches.

Überprüfen Sie für eine Pipeline mit Chunks auch repräsentative Blöcke von jedem betroffenen übergeordneten Element. Überprüfen Sie nach teilweisen Fehlern Fehler und Warnungen und versuchen Sie es erneut, bevor Sie alle Ergebnisse als abgeglichen betrachten. Verwenden Sie die kanonischen Projektionszuordnungen; ein geschütztes übergeordnetes Element allein schützt keinen Chunk, dem Berechtigungsmetadaten fehlen.