OneLake-Berechtigungen in Foundry IQ (Azure KI-Suche) beibehalten (Vorschau)

Konfigurieren Sie einen OneLake-Indexer oder eine indizierte OneLake-Wissensquelle, um Microsoft OneLake-Berechtigungen beizubehalten. Foundry IQ (Azure KI-Suche) indiziert Quellspeicherortmetadaten anstelle von Benutzer- und Gruppen-ACLs und verwendet OneLake, um den Zugriff des anfordernden Benutzers zur Abfragezeit auszuwerten.

Dieser Artikel ergänzt OneLake-Dateien indizieren und das Erstellen einer indizierten OneLake-Wissensquelle um die Konfiguration, die speziell für die Berechtigungserfassung gilt. Verwalten von Quellberechtigungen in Microsoft Fabric.

Diese Vorschau wird nur in der öffentlichen Azure-Cloud unterstützt.

Important

Die Erfassung von OneLake-Berechtigungen befindet sich in der öffentlichen Vorschau und unterliegt den ergänzenden Nutzungsbedingungen für Microsoft Azure Previews.

Spezifische Vorschaubedingungen für dieses Feature finden Sie unter Vorschaufunktionen.

Begriffe, die beim Herstellen einer Verbindung mit externen Datenquellen verwendet werden, finden Sie unter Externe Datenquellen.

Prerequisites

Konfigurieren eines OneLake-Indexers

Fügen Sie für eine direkt verwaltete Indexerpipeline die folgenden Einstellungen zur standardmäßigen OneLake-Indizierungskonfiguration hinzu. Diese Einstellungen sind Konfigurationszusätze, nicht vollständige Erstellungsanforderungen.

  1. Legen Sie indexerPermissionOptions für die Datenquelle fest, um die zu aufnehmenden Quellspeicherortmetadaten auszuwählen. Wählen Sie oneLakeParentFolders und oneLakeLakehouseId unabhängig voneinander für die Aufnahme aus. Das folgende JSON-Fragment wählt beide für den berechtigungsabhängigen Abruf aus:

    {
      "indexerPermissionOptions": [
        "oneLakeParentFolders",
        "oneLakeLakehouseId"
      ]
    }
    
  2. Definieren Sie die entsprechenden Felder im Zielindex.

    Quellmetadaten Beispielzielfeld Indexfeldtyp Erforderliche Feldkonfiguration
    metadata_onelake_parent_folders onelake_parent_folders Collection(Edm.String) filterable: true; permissionFilter: "oneLakeParentFolders".
    metadata_onelake_lakehouse_id onelake_lakehouse_id Edm.String filterable: true; permissionFilter: "oneLakeLakehouseId".
    metadata_onelake_is_shortcut metadata_onelake_is_shortcut Edm.Boolean Ein Feld auf oberster Ebene mit filterable: true und ohne permissionFilter-Anmerkung. Behalten Sie diesen Feldnamen bei.

    Die Lakehouse-ID identifiziert das konfigurierte Quell-Lakehouse, nicht das Ziel-Lakehouse einer Verknüpfung.

  3. Legen Sie den permissionFilterOption des Index auf enabled fest und konfigurieren Sie oneLakeSecuritySource mit den Quellarbeitsbereichs- und Lakehouse-IDs:

    {
      "permissionFilterOption": "enabled",
      "oneLakeSecuritySource": {
        "fabricWorkspaceId": "<fabric-workspace-id>",
        "lakehouseId": "<lakehouse-id>"
      }
    }
    

Ersetzen Sie userIds oder groupIds nicht durch die OneLake-Berechtigungsoptionen. Diese Felder stellen Quellorte dar, nicht kopierte Benutzer- und Gruppen-ACL-Einträge.

Behalten Sie die von der Quelle bereitgestellten Werte bei. Ersetzen Sie sie nicht durch Skill-Ausgaben, Zuordnungsfunktionen oder Felder, die von Dokumentinhalten abgeleitet sind.

Project-Felder in Blöcke projizieren

Wenn ein Skillset Chunks erstellt, ordnen Sie alle drei Metadatenfelder durch Indexprojektionen jedem Chunk zu. Diese Projektionszuordnungen füllen die Chunk-Felder direkt auf; Sie benötigen keinen Indexer fieldMappings für sie.

  1. Fügen Sie die drei Felder in der vorherigen Tabelle zum Chunkindex hinzu. Konfigurieren Sie die permissionFilterOption und oneLakeSecuritySource dieses Index wie zuvor beschrieben.

  2. Fügen Sie Ihrem Skillset das folgende Fragment hinzu. Es verwendet das standardmäßige Chunk-Indexschema mit einem parent_id Feld und einer Textteilungskompetenz, die /document/pages/* erzeugt. Behalten Sie ihre anderen Inhaltszuordnungen bei der Anpassung des Beispiels bei.

    {
      "indexProjections": {
        "selectors": [
          {
            "targetIndexName": "<chunk-index-name>",
            "parentKeyFieldName": "parent_id",
            "sourceContext": "/document/pages/*",
            "mappings": [
              {"name": "chunk", "source": "/document/pages/*"},
              {
                "name": "onelake_parent_folders",
                "source": "/document/metadata_onelake_parent_folders"
              },
              {
                "name": "onelake_lakehouse_id",
                "source": "/document/metadata_onelake_lakehouse_id"
              },
              {
                "name": "metadata_onelake_is_shortcut",
                "source": "/document/metadata_onelake_is_shortcut"
              }
            ]
          }
        ],
        "parameters": {"projectionMode": "skipIndexingParentDocuments"}
      }
    }
    

Durch die Verwendung von skipIndexingParentDocuments schreiben Sie nur Blöcke. Jeder geschriebene Inhaltsindex benötigt alle drei Metadatenfelder. Ordnen Sie sie direkt den entsprechenden /document/metadata_onelake_* Quellen zu, die weiter oben in jeder Inhaltsprojektion angezeigt werden.

Zuordnen von Feldern für die Dokumentindizierung

Bei nicht segmentierter Ingestion oder einem separaten übergeordneten Index werden übereinstimmende Quell- und Zielnamen mit kompatiblen Typen automatisch zugeordnet. Verwenden Sie Indexerfeldzuordnungen nur, um diese Metadatenfelder umzubenennen, z metadata_onelake_parent_foldersonelake_parent_folders . B. in und metadata_onelake_lakehouse_idonelake_lakehouse_id in das Beispielschema. Der unveränderte metadata_onelake_is_shortcut Name benötigt keine explizite Feldzuordnung.

Das Hinzufügen von Berechtigungsfeldern zu einem vorhandenen Index führt nicht dazu, dass sie in bereits indizierten Dokumenten aufgefüllt werden. Nach dem Konfigurieren der Berechtigungsaufnahme verarbeiten Sie diese Dokumente erneut , um die erforderlichen Metadaten aufzufüllen.

Konfigurieren einer indizierten OneLake-Wissensquelle

Wenn Sie eine indizierte OneLake-Wissensquelle erstellen, legen Sie beide Werte in indexedOneLakeParameters.ingestionParameters.ingestionPermissionOptions fest:

{
  "ingestionPermissionOptions": [
    "oneLakeParentFolders",
    "oneLakeLakehouseId"
  ]
}

Dieses JSON-Fragment zeigt nur die Berechtigungseinstellung an. Im Gegensatz zu den direkten Datenquellenoptionen müssen für die gesicherte indizierte OneLake-Erfassung beide Werte gemeinsam angegeben werden. Das vollständige REST-Erstellungsbeispiel unter Verwendung von 2026-11-01-preview und beider Berechtigungsoptionen finden Sie unter Erstellen einer Wissensquelle mit oneLake-Berechtigungserhaltung.

Die Wissensquelle generiert die Indexfelder, die Berechtigungskonfiguration auf Indexebene, Feldzuordnungen und Chunk-Projektionen. Sie müssen diese generierten Zuordnungen nicht separat konfigurieren.

Wenn die Erfassung von OneLake-Berechtigungen aktiviert ist, lassen Sie den asset store, den Anreicherungscache und die Graph-Extraktionseinstellungen aus.

Abfrage mit der Identität des anfordernden Benutzers

Verwenden Sie den vorhandenen ACL-Abfrage- und Testablauf, einschließlich x-ms-query-source-authorization für das Token des anfordernden Benutzers. Verwenden Sie 2026-11-01-preview für OneLake-Anforderungen anstelle der API-Version in diesen freigegebenen Beispielen. Befolgen Sie für eine Wissensdatenbank die gemeinsame Anleitung zur Autorisierung zur Abfragezeit. OneLake erfordert kein separates Abfrageprotokoll.

Die Suche wertet die lesbaren OneLake-Ordner des anfordernden Benutzers anhand der indizierten Werte für übergeordnete Ordner im konfigurierten Lakehouse aus. Eine Übereinstimmung mit dem unmittelbaren übergeordneten Element oder einem übergeordneten Ordner eines Dokuments kann dieses Dokument zum Abruf berechtigen. Quellberechtigungen bleiben in Fabric verwaltet.

Für Files/teamA/reports/document.txt sind die indizierten Ordnerwerte ["Files", "Files/teamA", "Files/teamA/reports"]. Der Dateiname ist nicht enthalten. Die Hierarchie enthält übergeordnete Elemente oberhalb eines konfigurierten Erfassungsunterordners.

Pfade sind lakehouse-relative, verwenden / Trennzeichen und haben keinen führenden oder nachgestellten Schrägstrich. Der Abgleich ist case-sensitiv. Leerzeichen, Unicode-Zeichen und wörtliche Prozentzeichen wie angegeben beibehalten; URI-dekodieren Sie diese Metadatenwerte nicht, oder schreiben Sie diese Metadatenwerte nicht neu.

Berechtigungs- und Pfadaktualität berücksichtigen

Indizierte Quellspeicherorte und Abfragezeitzugriffsinformationen können sich zu unterschiedlichen Zeiten ändern. Berechtigungsänderungen, einschließlich Widerrufen, können Zeit in Anspruch nehmen, sich auf den Abruf auszuwirken; es gibt kein festes End-to-End-Aktualitätsintervall.

Abfragen verwenden indizierte Inhalte und Abfragezeitautorisierung; sie lösen keine Indexerausführung aus. Indexer werden normalerweise bei der Erstellung ausgeführt, es sei denn, sie sind deaktiviert, und anschließend bei Bedarf oder nach Zeitplan. Ein geplanter Zeitpunkt oder eine Ausführungsanforderung ist kein Abschlusstermin. Siehe Planungsverhalten für verzögerte oder übersprungene Starts.

Stage Was kann eine Änderung verzögern?
Fabric und OneLake Verteilung von Arbeitsbereichsrollen, Elementzugriff und Ordnerberechtigungen.
Indexer-Start Planungs- und Ausführungskapazität; Ein geplanter oder angeforderter Lauf wird möglicherweise nicht sofort gestartet.
Indexerausführung Verarbeitungsdauer, Drosselung, Wiederholungen oder fehlgeschlagene Elemente.
Indexverfügbarkeit Chunk-Projektion, Dokumentschreibvorgänge und Indexaktualisierung beeinflussen, wann aktualisierte Inhalte und Pfadmetadaten durchsuchbar werden.
Identität des anfordernden Benutzers Token-Aktualität und Änderungen an den Rollen oder der Gruppenmitgliedschaft des Benutzers.
Zugriff zum Abfragezeitpunkt Zwischengespeicherte OneLake-Zugriffsinformationen können weiterhin frühere Berechtigungen wiedergeben, bis sie aktualisiert werden. Ein neues Benutzertoken allein löscht diese zwischengespeicherten Informationen nicht.

Verwenden Sie den Indexerstatus und den Ausführungsverlauf , um Start- und Endzeiten auf Ausführungsebene, Fehler, Warnungen und fehlgeschlagene Elemente zu überprüfen. Der Status der obersten Ebene running bedeutet, dass der Indexer zur Ausführung verfügbar ist und nicht, dass eine Ausführung ausgeführt wird. Überprüfen Sie repräsentative Dokumente und Blöcke auf die erforderlichen Metadaten. Eine erfolgreiche Erfassungsausführung bedeutet nicht, dass auch Fabric Weitergabe, Benutzertoken und zwischengespeicherte Zugriffsinformationen aktualisiert wurden.

Prüfen Sie nach dem Verschieben, Umbenennen, Löschen oder der Wiederverwendung eines Pfads sowohl auf veraltete Datensätze am alten Speicherort als auch auf Datensätze am neuen Speicherort. Ältere indizierte Inhalte können einem Pfad zugeordnet bleiben, dessen aktueller Zugriff geändert wurde.

Verwenden Sie den OneLake-Soft-Delete-Workflow, bevor Sie eine Quelldatei physisch entfernen. Wenn die Quelldatei bereits entfernt wurde, löschen Sie die verwaisten Suchdokumente und -blöcke manuell.

Befolgen Sie die Anleitung zum Ausführen und Zurücksetzen, um noch vorhandene Dateien erneut zu verarbeiten. Das Zurücksetzen eines Indexers löscht weder seine indizierten Dokumente noch aktualisiert es die Zugriffsinformationen zur Abfragezeit.

Verwenden Sie beim Überprüfen einer Berechtigungsänderung frische Benutzertoken und den freigegebenen ACL-Testablauf. Vergleichen Sie einen zugelassenen und einen abgelehnten Benutzer, und überprüfen Sie ggf. sowohl übergeordnete Dokumente als auch Blöcke. Verwenden Sie den Abschluss der Aufnahme nicht als Maß für den Abschluss des Widerrufs.

Verstehen von Verknüpfungsberechtigungsgrenzen

Der Abruf von OneLake-Berechtigungen unterstützt in dieser Vorschau keine Verknüpfungen. Von Verknüpfungen abgeleitete Inhalte werden von Ergebnissen ausgeschlossen, einschließlich inhalten, die über OneLake-zu-OneLake und externe Verknüpfungen erreicht wurden. Der Zugriff auf den enthaltenden Ordner oder das Verknüpfungsziel ermöglicht nicht das Abrufen von Verknüpfungsinhalten.

Die gewöhnliche Unterstützung für die Aufnahme von Verknüpfungen unterscheidet sich von der berechtigungsbewussten Abrufung.

Das erforderliche metadata_onelake_is_shortcut Feld unterscheidet verknüpfungsbasierte Inhalte von direkten Dateien. Definieren Sie es als Feld auf oberster Ebene Edm.Boolean mit filterable: true und ohne permissionFilter-Anmerkung. Behalten Sie den Namen dieses Felds und die von der Quelle bereitgestellten Werte bei. Fehlende oder NULL-Werte führen nicht dazu, dass ein Dokument in berechtigungsgefilterten Ergebnissen erscheint. Ersetzen Sie dieses Feld nicht durch einen konstanten Wert und leiten Sie es nicht vom Zugriff auf übergeordnete Ordner ab.

Anzahlen, Facets, Zitate und Quellenbezug basierend auf berechtigungsgefilterten Inhalten sind keine Auflistung aller indizierten Inhalte.

Probleme bei der berechtigungsabhängigen Abfrage beheben

Überprüfen Sie bei fehlenden Ergebnissen die folgenden quellspezifischen Bedingungen, bevor Sie die Anleitung zur Problembehandlung für freigegebene Abfragen verwenden:

  • Vergewissern Sie sich, dass die drei erforderlichen Felder vorhanden sind und die zuvor gezeigten Typen und Attribute aufweisen. Überprüfen Sie für Chunks die Zuordnungen und Quellpfade der einzelnen Projektionen.
  • Überprüfen Sie die vom System zugewiesene verwaltete Identität des Foundry IQ-Diensts und seine Fabric-Arbeitsbereichsrolle Admin.
  • Überprüfen Sie, ob der Inhalt durch eine Verknüpfung gelangt ist. Der Verknüpfungsausschluss ist eine Vorschaueinschränkung, keine fehlende Berechtigung für den übergeordneten Ordner.
  • Überprüfen Sie die Aktualität des Pfads, die Groß-/Kleinschreibung und das konfigurierte Lakehouse nach dem Verschieben von Inhalten oder dem Ändern von Berechtigungen.
  • Wenn die OneLake-Zugriffsauflösung aufgrund von Authentifizierung, Paginierung, ungültiger Antwort oder Pfadauflösung fehlschlägt, gibt die Abfrage einen Fehler zurück, anstatt mit unvollständigen Zugriffsinformationen fortzufahren. Korrigieren Sie den Quellzugriff oder die Quellkonfiguration, bevor Sie den Vorgang wiederholen.

Limitations

Integrierte Text- und Einbettungsfunktionen werden für die Aufnahme von OneLake-Berechtigungen unterstützt. Die folgenden Vorschaueinschränkungen gelten:

  • Von Shortcuts abgeleitete Inhalte sind vom berechtigungsabhängigen Abruf ausgeschlossen. Siehe Verknüpfungsberechtigungsgrenzen.
  • Bei aktivierter einer der beiden OneLake-Berechtigungsoptionen werden das Zwischenspeichern von Anreicherungen, Wissensspeichern und benutzerdefinierten Web-API-Fähigkeiten nicht unterstützt.
  • Chat Completion skills erfordern einen unterstützten Microsoft-Endpunkt für die Erfassung von OneLake-Berechtigungen; Custom-Domain- und Azure API Management-Endpunkte werden nicht unterstützt. Wenn Sie auch die Aufnahme von Vertraulichkeitsbezeichnungen aktivieren, werden Chat Completion-Skills mit keinem Endpunkt unterstützt.