Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Hinweis
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.
Wichtig
Features oder Funktionen, die in diesem Artikel als "Vorschau" gekennzeichnet sind, befinden sich in der öffentlichen Vorschau und unterliegen den ergänzenden Nutzungsbedingungen für Microsoft Azure Previews.
Informationen zu den Vorschaubedingungen speziell für Foundry IQ (Azure KI-Suche) finden Sie unter Vorschaufunktionen.
SharePoint ACL-Berechtigungsfilterung, ADLS Gen2 ACL/RBAC-Filterung, Standard-Blob-Container-RBAC-Filterung und erhöhte Leseberechtigungen sind in der Regel mit der REST-API der Datenebene 2026-10-01 verfügbar.
Die Zugriffssteuerung zur Abfragezeit filtert Suchergebnisse mithilfe der Identität des delegierten Benutzers und der unterstützten Berechtigungsmetadaten des Index. Push ACL-Erfassung ist allgemein verfügbar. Die Erzwingung von Vertraulichkeitsbezeichnungen in Microsoft Purview bleibt in der Vorschau.
Autorisierter Zugriff hängt von Berechtigungsmetadaten ab, die während der Indizierung aufgenommen werden. Für Indizierungsdatenquellen mit integrierten Zugriffsmodellen wie Azure Data Lake Storage (ADLS) Gen2 und SharePoint in Microsoft 365 kann ein Indexer die Berechtigungsmetadaten für jedes Dokument automatisch abrufen. Für andere Datenquellen müssen Sie die Dokumentnutzlast selbst zusammenstellen, und die Nutzlast muss sowohl Inhalt als auch die zugehörigen Berechtigungsmetadaten enthalten. Anschließend verwenden Sie die Push-APIs , um den Index zu laden.
In diesem Artikel wird erläutert, wie Abfragen eingerichtet werden, die Berechtigungsmetadaten zum Filtern von Ergebnissen verwenden.
OneLake-Quellberechtigungen verwenden den x-ms-query-source-authorization Aufrufertokenfluss wieder. Informationen zu den Metadatenanforderungen und dem Autorisierungsmodell des Quellspeicherorts anstelle des unten beschriebenen kopierten ACL/RBAC-Modells finden Sie unter Beibehalten von OneLake-Berechtigungen.
Voraussetzungen
Aktivieren Sie für den Index
permissionFilterOption, und verwenden Sie filterbare Berechtigungsfelder auf oberster Ebene. Sie fügen den Berechtigungsfilter nicht zu Ihren Abfragen hinzu. Die Suchmaschine erstellt ihn intern.Verwenden Sie berechtigungsmetadaten, die für Ihre Quelle geeignet sind: Benutzer- und Gruppen-IDs für SharePoint, POSIX-AcLs für ADLS Gen2 oder Containerressourcen-IDs für ADLS Gen2 oder Standard-Blob Storage RBAC-Bereiche.
Für die ACL-basierte Erzwingung mit benutzerdefinierter Erfassung speichern Sie
userIdsundgroupIdsals Microsoft Entra-Objekt-IDs (GUIDs), nicht als E-Mail-Adressen oder UPNs. Bei der Abfrage verwendet Foundry IQ (Azure KI-Suche) das delegierte Benutzertoken inx-ms-query-source-authorizationzum Auswerten von Dokumentberechtigungen. Informationen zu Feldtypen und Schemadetails finden Sie unter Index document ACLs with the push REST APIs.Abhängig von der Datenquelle:
- Für ADLS Gen2-Datenquellen müssen Sie Zugriffssteuerungslisten (Access Control Lists, ACLs) und/oder Azure rollenbasierte Zugriffssteuerungsrollen (Role-Based Access Control, RBAC) auf Containerebene konfiguriert haben.
- Für Azure Blob-Datenquellen müssen Sie über unterstützten Zugriff auf den Container verfügen. Sie können einen Blob-Indexer, eine Wissensquelle oder Push-APIs verwenden, um Berechtigungsmetadaten in Ihrem Index zu indizieren.
- Für SharePoint Datenquellen müssen Sie Zugriffssteuerungslisten (Access Control Lists, ACLs) konfigurieren. Sie können einen integrierten SharePoint-Indexer verwenden und mit ACL-Aufnahmefunktionen konfigurieren. Sie können auch eine indizierte SharePoint Wissensquelle verwenden und konfigurieren, um Berechtigungen auf Dokumentebene zu erzwingen. Gruppenbasierte Berechtigungen, einschließlich Microsoft 365-Gruppen, werden unterstützt, wenn sie als Entra-Objekt-IDs aufgenommen werden. Die Gruppenerweiterung erfolgt zum Zeitpunkt der Abfrage über Microsoft Graph.
Verwenden Sie DIE REST-API 2026-10-01 für SharePoint- und ADLS/Blob-Berechtigungsfilterabfragen, oder überprüfen Sie die entsprechende SDK-Unterstützung im Paketänderungsprotokoll. Verwenden Sie für unabhängige Vorschauszenarien ihre dokumentierten API-Versionen.
Einschränkungen
Nicht aufgelöste Gruppenmitgliedschaften gewähren keinen Zugriff. Für SharePoint können unabhängig aufgelöste Berechtigungen weiterhin angewendet werden, wenn eine Gruppensuche fehlschlägt. Wenn die Anforderung einen Autorisierungsfehler zurückgibt, versuchen Sie es nicht mit ungefiltertem oder erhöhtem Zugriff.
Bei kopierten ACL- und RBAC-Metadaten hängt die Aktualität davon ab, wie die einzelnen Aufnahmemethoden Berechtigungsänderungen an den Index weitergeben:
- Ein SharePoint Indexer aktualisiert erkannte Änderungen auf Elementebene und unterstützte Nicht-Stammordner-Berechtigungsänderungen während der erfolgreichen inkrementellen Verarbeitung. Konfigurieren Sie einen kurzen wiederkehrenden Zeitplan für die Aktualisierung der Berechtigungen. Das Intervall ist kein Abschlusstermin oder ein Widerrufs-SLA. Die verknüpfte Anleitung umfasst auch andere Bereiche und explizite Aktualisierungsoptionen.
- Ein ADLS Gen2-Indexer aktualisiert die ACLs bei geeigneten normalen Ausführungen standardmäßig ungefähr einmal täglich oder durch eine explizite Neusynchronisierung der Berechtigungen.
- Blob- und ADLS-RBAC-Bereichsprüfungen bewerten die Containerautorisierung des delegierten Benutzers zur Abfragezeit. Die Weitergabe von Rollenzuweisungen und Autorisierungscaches sind von der Aktualität indizierter ACLs getrennt.
- Die benutzerdefinierte oder Push-Erfassung erfordert, dass Sie die betroffenen Dokumente erneut erfassen.
Informationen zu OneLake-Quellspeicherortmetadaten und Abfragezeitzugriffsinformationen finden Sie unter Berechtigung und Pfadaktualität.
Für Abfragen ohne erhöhten Lesezugriff sind beide erforderlich:
- Such-RBAC-Autorisierung (
AuthorizationHeader) des Aufrufers. - Die delegierte Benutzeridentität, die von
x-ms-query-source-authorizationfür berechtigungsgeschützte Inhalte übertragen wird.
- Such-RBAC-Autorisierung (
Anfängliche ACL-basierte Abfragen können im Vergleich zu nachfolgenden Anforderungen aufgrund von Zwischenspeicherung und Berechtigungsauflösung eine höhere Latenz aufweisen.
Bei indizierten SharePoint Inhalten werden Microsoft Entra gruppen, die in SharePoint Gruppen geschachtelt sind, innerhalb von fünf Ebenen unterstützt, vorbehaltlich eines separaten Prinzipalgrenzwerts auf Websiteebene. Siehe Unterstützte Gruppenbeziehungen.
ACL-Eintragsbeschränkungen pro Datenquelle
Einträge in einer Zugriffssteuerungsliste (Access Control List, ACL) definieren, wie viele unterschiedliche Berechtigungseinträge einer Datei, einem Ordner oder einem Element in einer verbundenen Datenquelle zugeordnet werden können. Jeder Eintrag stellt eine einzelne Benutzer- oder Gruppenidentität und die Zugriffsrechte dar, die dieser Identität gewährt werden (z. B. "Lesen", "Schreiben" oder "Execute").
Die maximale Anzahl von ACL-Einträgen, die von der Foundry IQ-Funktionalität unterstützt werden, variiert je nach Datenquellentyp:
Azure Data Lake Storage Gen2 (ADLS Gen2): Jede Datei oder jedes Verzeichnis kann bis zu 32 ACL-Eintragsberechtigungen haben. In diesem Kontext bedeutet ein Eintrag einen einzelnen Benutzer oder eine Gruppe mit einem spezifischen Satz festgelegter Berechtigungen. Beispiel: Das Zuweisen des Lesezugriffs für "Jeder" und des Ausführungszugriffs für "Azure-Benutzer" wird als zwei ACL-Einträge gezählt.
SharePoint in Microsoft 365: SharePoint Datenquelle in der Suche unterstützt bis zu 1.000 Berechtigungseinträge pro Datei. Jeder Eintrag stellt eine eindeutige Benutzer- oder Gruppenzuweisung in der Berechtigungsliste des Elements dar. Dies unterscheidet sich von den allgemeinen eindeutigen Berechtigungsbereichen pro Liste oder Bibliothek, die bestimmt, wie viele Elemente über eindeutige Berechtigungen verfügen können.
Diese Grenzwerte bestimmen, wie präzise Foundry IQ Berechtigungen auf Elementebene beim Indizieren oder Filtern von Suchergebnissen berücksichtigen kann. Wenn ein Element diese ACL-Eintragsgrenzwerte überschreitet, werden Berechtigungen, die über den Grenzwert hinausgehen, möglicherweise zur Abfragezeit nicht erzwungen.
Wie die Erzwingung von Abfragen zur Laufzeit funktioniert
In diesem Abschnitt wird die Reihenfolge der Vorgänge für die ACL-Erzwingung zur Abfragezeit aufgeführt. Vorgänge variieren je nachdem, ob Sie entweder den Azure RBAC-Geltungsbereich oder Microsoft Entra ID-Gruppen oder Benutzer-IDs verwenden.
1. Eingabe von Benutzerberechtigungen
Für systemeigene berechtigungsgefilterte Abfragen weisen die beiden Tokenpositionen separate Rollen auf:
-
Authorizationauthentifiziert den Aufrufer und autorisiert den Suchvorgang auf der Datenebene über Search RBAC. Der Aufrufer kann ein Benutzer, ein Anwendungsdienstprinzipal oder eine verwaltete Identität mit der erforderlichen Suchrolle und dem Ressourcenbereich sein. -
x-ms-query-source-authorizationträgt ein delegiertes Benutzerzugriffstoken. Foundry IQ wertet die Dokumentberechtigungen des Benutzers aus, nicht die Dokumentberechtigungen der Anwendung inAuthorization.
Eine Anwendung oder verwaltete Identität, die zum Aufrufen der Suche autorisiert ist, ist nicht automatisch ein unterstütztes Subjekt für Dokumentberechtigungen. Die Identität, die von einem Indexer zum Lesen einer Quelle verwendet wird, unterscheidet sich auch von dem Abfrageaufrufer und dem Benutzer, dessen Berechtigungen ausgewertet werden.
In der folgenden Tabelle werden die unterstützten delegierten Benutzerflüsse beschrieben. Jeder Fluss behält seine quellspezifischen Berechtigungs- und API-Grenzwerte bei.
| Berechtigungsfluss | Unterstütztes Verhalten für delegierte Benutzer |
|---|---|
userIds ACLs |
Vergleicht die Microsoft Entra Objekt-ID (oid) des delegierten Benutzers von x-ms-query-source-authorization mit indizierten Benutzer-ACLs. |
groupIds ACLs |
Löst die Microsoft Entra Gruppenmitgliedschaften des Benutzers über Microsoft Graph auf, einschließlich unterstützter Sicherheitsgruppen und Microsoft 365-Gruppen, und gleicht deren Objekt-IDs mit indizierten Gruppen-ACLs ab. |
| SharePoint Websitegruppen | Löst die Websitegruppenmitgliedschaften des delegierten Benutzers über die registrierte Anwendung im Index auf. Erkennt spg:-präfixierte IDs in groupIds. Erfordert die Konfiguration der SharePoint gruppen. Verwenden Sie die REST-API 2026-10-01 für SharePoint Berechtigungsfilterung. |
rbacScope |
Wertet die unterstützte Blob-Lese-Autorisierung des delegierten Benutzers für die indizierten ADLS Gen2- oder Standard-BLOB-Containerbereiche aus. |
| Purview-Vertraulichkeitsbezeichnungen (Vorschau) | Wertet die Bezeichnungsberechtigungen des delegierten Benutzers unter den separaten Purview-Anforderungen aus. |
Microsoft Entra Gruppenerweiterung verwendet das Abfragequellenbenutzertoken in einem Benutzerfluss im Namen eines Benutzers (OBO). Gruppen sind keine tokenbasierten Identitäten. Ein Anwendungstoken in Authorization ersetzt nicht die delegierte Benutzerassertion, die für diesen Gruppenauflösungsfluss erforderlich ist. Unterstützte Gruppenbeziehungen finden Sie in den quellspezifischen Grenzwerten.
Anwendungstoken-Grenzen
Wählen Sie den Tokenfluss für den Vorgang und das Berechtigungsmodell aus, nicht nur für die Fähigkeit der Anwendung, sich bei der Suche zu authentifizieren.
| Fluss | Anwendungstokengrenze |
|---|---|
| Authentifizierung des Search-Aufrufers | Ein Dienstprinzipal einer Anwendung oder eine systemseitig oder benutzerseitig zugewiesene verwaltete Identität kann den Aufrufer mithilfe der erforderlichen Search-Rolle authentifizieren. Dadurch wird es nicht zum Subjekt der Dokumentberechtigung. |
userIds, groupIds, und SharePoint-Websitegruppen |
Verwenden Sie den oben beschriebenen delegierten Benutzerablauf für die Abfragequelle. Eine Anwendungsobjekt-ID in einem Token oder einer ACL begründet keinen unterstützten app-only-Abfragequellenflow. Die Gruppenerweiterung erfordert weiterhin die dokumentierte Benutzerassertion und Zustimmung. |
| Organisationsweite Berechtigungswerte | Eine allgemein anwendbare Berechtigung ändert die Token-Anforderung nicht. Lassen Sie das erforderliche Benutzertoken nicht aus, oder ersetzen Sie ein Anwendungstoken nur, weil der Inhalt über eine organisationsweite Berechtigung verfügt. |
Container rbacScope |
Verwenden Sie den unterstützten Ablauf für delegierte Benutzer. Das Zuweisen einer Speicherrolle zu einem Indexer oder einer Anwendung ersetzt nicht die Autorisierung des Abfragebenutzers. |
| OneLake-Quellberechtigungen | Folgen Sie dem quellspezifischen Previewvertrag, und übergeben Sie das Token des anfordernden Benutzers. Die verwaltete Identität der Suche, die sich bei OneLake authentifiziert, ist von diesem Benutzer getrennt. |
| Purview-Bezeichnungen | Befolgen Sie die separaten Anforderungen für delegierte Benutzer, einschließlich der Anforderung für delegierte Benutzer für erhöhte Leseberechtigungen in einem Purview-aktivierten Index. |
| Lesezugriff mit erhöhten Rechten ohne Purview | Eine autorisierte Anwendung kann für den Direct-Index-Verwaltungsvorgang die Nur-App-Aufruferauthentifizierung verwenden. Dadurch wird die Dokumentberechtigungsfilterung umgangen; die ACL-Mitgliedschaft der Anwendung wird nicht ausgewertet. |
| Anwendungsverwaltete Security-String-Filter | Die Anwendung authentifiziert ihre Benutzer und erstellt vertrauenswürdige Filter selbst. Dies ist keine native Auswertung von Berechtigungen für Anwendungstoken. |
Leiten Sie keine zusätzliche Unterstützung für Berechtigungssubjekte aus oid- oder tid-Ansprüchen, Workload Identity Federation, einer Agentidentität oder einer App-zu-App-OBO-Konfiguration ab. Verwenden Sie den Identitätserwerbsablauf, die Einwilligung, die API-Version und den für das jeweilige Feature dokumentierten Vorgang.
Direkte Suchanfragen sowie Dokumentabruf, Knowledge-Base-Abruf und MCP-/agentischer Zugriff unterliegen separaten Vereinbarungen. Die Verfügbarkeit auf einer Oberfläche begründet nicht dieselben Header, Identitätstypen oder administrativen Umgehungen auf einer anderen Oberfläche. Befolgen Sie für den Knowledge-Base- und MCP-Zugriff die Autorisierung beim Abruf zur Abfragezeit; Zitierungen bieten keinen separaten Autorisierungspfad.
Wenn eine Anforderung das bereitgestellte Token oder Akteur ablehnt, schlägt die Anwendungsanforderung sicher fehl. Wiederholen Sie den Vorgang nicht, indem Sie das Benutzertoken weglassen, Identitäten wechseln, ungefilterte oder nur öffentliche Ergebnisse zurückgeben oder erhöhte Leseberechtigungen aktivieren.
2. Konstruktion von Sicherheitsfiltern
Intern erstellt Foundry IQ dynamisch Sicherheitsfilter basierend auf den bereitgestellten Benutzerberechtigungen. Diese Sicherheitsfilter werden automatisch an alle Filter angefügt, die in der Abfrage enthalten sind, wenn der Index die Berechtigungsfilteroption aktiviert hat.
Für Azure RBAC speichert der Index Containerressourcen-IDs, nicht kopierte Rollenzuweisungen. Foundry IQ wertet den delegierten Benutzer x-ms-query-source-authorization für die unterstützte Blob-Lese-Autorisierung für diese Bereiche aus. Dieser Benutzer ist nicht unbedingt der Anwendungsprinzipal, in Authorizationdem der Zugriff auf die Suchdatenebene unabhängig autorisiert wird. Die Autorisierungsauflösung verwendet Caches; Durch die erneute Indizierung werden diese Caches nicht aktualisiert.
3. Ergebnisfilterung
Der ACL/RBAC-Sicherheitsfilter stimmt mit den Berechtigungen des Benutzers mit den indizierten userIds, groupIdsund rbacScope Feldern überein. Diese Zuschüsse werden unabhängig ausgewertet: Alle übereinstimmenden unterstützten Finanzhilfen erfüllen diesen Filter. Beispielsweise erfordert eine passende userIds-Berechtigung nicht zusätzlich eine passende groupIds-Berechtigung.
Die Erzwingung von Purview-Bezeichnungen hat separate Anforderungen.
Für dieses Any-Grant-Verhalten ist eine erfolgreiche Berechtigungsauswertung erforderlich. Fehler beim Auflösen von Gruppen oder einem anderen konfigurierten Berechtigungsfluss können die Anforderung fehlschlagen, auch wenn eine direkte Benutzer-ACL- oder RBAC-Erteilung übereinstimmen könnte.
Schließen Sie beim Testen der Sperrung alternative unterstützte Zuschüsse aus. Durch das Entfernen einer ACL-Berechtigung wird der Zugriff nicht verweigert, wenn eine Container-RBAC-Berechtigung den Benutzer weiterhin autorisiert. Wenn die Berechtigungsauswertung fehlschlägt, schlägt die Anwendungsanforderung sicher fehl; Versuchen Sie es nicht erneut, ohne das delegierte Token zu verwenden oder Lesevorgänge mit erhöhten Rechten als Fallback zu aktivieren.
Für ADLS Gen2 können nicht unterstützte implizite blocklists Zuweisungen keinen ACL-abgeleiteten Zugriff gewähren, aber unabhängige unterstützte RBAC-Zuweisungen können weiterhin den Zugriff autorisieren.
Diese nativen Berechtigungsüberprüfungen gelten auch für moreLikeThis: Das Quelldokument muss lesbar sein, bevor der Abruf von Ähnlichkeiten ausgeführt wird, und Kandidatendokumente werden unabhängig voneinander gefiltert. Wenn das Quelldokument nicht lesbar oder fehlt, gibt die Anforderung ein leeres Suchergebnis zurück, kein Vorgangsautorisierungsfehler. Purview-fähige Indizes lehnen moreLikeThis separat ab.
SharePoint Gruppen zur Abfragezeit
Foundry IQ kann SharePoint Websitegruppenberechtigungen auswerten, z. B. Besitzer, Mitglieder, Besucher und benutzerdefinierte Websitegruppen, zur Abfragezeit mithilfe der REST-API2026-10-01. Um dieses Szenario zu aktivieren, muss der Index Folgendes enthalten:
- Eine
sharePointConnectorAppRegistrationEigenschaft, die die Client-ID der Aufnahmeanwendung und die Anwendungs-ID der verwalteten Identität für die Verbundauthentifizierung angibt. - Ein Feld, das mit dem Attribut
sharepointSiteUrl: truegekennzeichnet ist und die URL der SharePoint-Website für jedes indizierte Element speichert (normalerweiseSharePointSiteUrlgenannt und aus dem Quellfeldmetadata_spo_site_urlbefüllt).
Zur Abfragezeit verwendet Foundry IQ die registrierte Anwendung und die Website-URL in jedem Kandidatendokument, um die SharePoint-Gruppe Mitgliedschaften des aufrufenden Benutzers auf dieser Website aufzulösen. Die aufgelösten Gruppen werden mit den Werten mit spg:-Präfix abgeglichen, die im Berechtigungsfilterfeld groupIds gespeichert sind. Das Präfix spg: unterscheidet SharePoint Websitegruppen von Microsoft Entra Gruppenobjekt-IDs, die ohne Präfix gespeichert werden.
Informationen zu Konfigurationsdetails und Einschränkungen finden Sie unter Configure SharePoint-Gruppenunterstützung.
Wenn SharePoint Berechtigungsfilterung fehlende oder unerwartete Ergebnisse zurückgibt, lesen Sie die Problembehandlung SharePoint Berechtigungsfilterung.
Beispiel: Abfrage mit Durchsetzung von SharePoint-Websitegruppen
Die Anforderung ist identisch mit der standardmäßigen ACL-erzwungenen Abfrage. Der Foundry IQ-Dienst verwendet das sharePointConnectorAppRegistration des Index, um die Mitgliedschaft in der SharePoint-Gruppe im Namen des Aufrufers aufzulösen. Ersetzen Sie <SEARCH_SERVICE_ENDPOINT> durch Ihren Endpunkt, <INDEX_NAME> durch den Indexnamen und <USER_ACCESS_TOKEN> durch das unformatierte delegierte Benutzertoken. Um gespeicherte Berechtigungsmetadaten zu prüfen, befolgen Sie die Schritte zur Überprüfung der ACL-Erfassung, anstatt ACL-Felder in normalen Benutzerabfragen offenzulegen.
POST <SEARCH_SERVICE_ENDPOINT>/indexes('<INDEX_NAME>')/docs/search.post.search?api-version=2026-10-01
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: <USER_ACCESS_TOKEN>
Content-Type: application/json
{
"search": "*",
"select": "name,description",
"orderby": "name asc"
}
Abfragebeispiel
Verwenden Sie den 2026-10-01 Index und die Nutzlast mit vier Dokumenten aus dem Pushindizierungsworkflow. Warten Sie, bis die Dokumente durchsucht werden können. Ersetzen Sie <SEARCH_SERVICE_ENDPOINT> durch Ihren Endpunkt und <USER_ACCESS_TOKEN> durch das unformatierte delegierte Benutzertoken für den beim Upload verwendeten <USER_OBJECT_ID>. Verwenden Sie ein zum Abfragen des Indexes autorisiertes Aufrufertoken.
POST <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')/docs/search.post.search?api-version=2026-10-01
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: <USER_ACCESS_TOKEN>
Content-Type: application/json
{
"search": "*",
"select": "id,content",
"top": 4,
"count": true,
"orderby": "id asc"
}
Referenz: Dokumente durchsuchen.
Erhöhte Berechtigungen zum Untersuchen falscher Ergebnisse
Lesezugriff mit erhöhten Rechten ist in der REST-API 2026-10-01allgemein verfügbar. Verwenden Sie sie nur für autorisierte administrative Untersuchungen, nicht als Fallback für Endbenutzerabfragen.
Eine Anforderung mit erhöhten Leseberechtigungen gibt übereinstimmende Dokumente unabhängig von Berechtigungsfiltern auf Dokumentebene zurück. Legen Sie fest x-ms-enable-elevated-read: true , dass indizierte Inhalte überprüft werden, wenn sie fehlende oder unerwartete Ergebnisse untersuchen.
Bei Indizes ohne aktiviertem Purview kann ein Dienstprinzipal einer Anwendung ein Nur-App-Zugriffstoken in Authorization für erweiterten Lesezugriff verwenden. Weisen Sie dem Aufrufer die erforderlichen Berechtigungen mit erhöhten Leseberechtigungen zu. Dadurch wird die Dokumentberechtigungsfilterung umgangen; sie wertet die Anwendung nicht als Subjekt von Dokumentberechtigungen aus.
Nehmen Sie x-ms-query-source-authorization nicht in eine Anforderung mit erhöhten Leseberechtigungen auf. Um Ergebnisse mit der Ansicht eines Endbenutzers zu vergleichen, stellen Sie eine separate normale Abfrage mit dem Token dieses Benutzers und ohne den Header mit erhöhten Leseberechtigungen aus.
Für purview-fähige Indizes erfordert das Lesen mit erhöhten Rechten ein delegiertes Benutzertoken in Authorization; Nur-App-Token werden für diesen Fluss nicht unterstützt. Siehe Purview-Anforderungen mit erhöhten Leseberechtigungen.
Berechtigungen für Anforderungen für erweiterte Lesezugriffe
Der Aufrufer in Authorization muss über die Berechtigung Search Index Data Contributor oder über eine benutzerdefinierte Rolle verfügen, die die Berechtigung „Leseberechtigung erhöhen“ enthält.
Abfragen sind ein Datenebenenvorgang, sodass die benutzerdefinierte Rolle nur aus Berechtigungen für atome Datenebenen bestehen kann. Fügen Sie für eine benutzerdefinierte Rolle die Berechtigung Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read hinzu.
Hinzufügen eines Headers mit erhöhtem Lesezugriff zu einer Abfrage
Nachdem Sie Berechtigungen eingerichtet haben, können Sie die Abfrage ausführen. Das folgende Beispiel ist eine Abfrageanforderung für einen Suchindex.
POST {endpoint}/indexes('{indexName}')/docs/search.post.search?api-version=2026-10-01
Authorization: Bearer {AUTH_TOKEN}
x-ms-enable-elevated-read: true
Content-Type: application/json
{
"search": "prototype tests",
"select": "filename, author, date",
"count": true
}
Wichtig
Die 2026-10-01 REST-API unterstützt x-ms-enable-elevated-read die Suchaktionen GET, Search POST und Get Document. Für Untersuchungen der Wissensdatenbank senden Sie die Anfrage direkt an den zugrunde liegenden Suchindex. Die knowledge base retrieve REST-API deklariert diesen Header nicht. Die Erzwingung von Vertraulichkeitsbezeichnungen behält ihre separaten Vorschauanforderungen bei.
Wichtige Verhaltensänderung der ACL-Funktionalität in bestimmten Vorschau-API-Versionen
Vor der REST-API-Version 2025-11-01-previewhaben frühere Vorschauversionen 2025-05-01-preview und 2025-08-01-preview alle Dokumente bei Verwendung eines Dienst-API-Schlüssels oder autorisierter Entra-Rollen zurückgegeben, auch wenn kein Benutzertoken bereitgestellt wurde. Anwendungen, die das Vorhandensein eines Benutzertokens nicht überprüft haben, könnten versehentlich Ergebnisse für Endbenutzer verfügbar machen, wenn sie nicht ordnungsgemäß implementiert oder bewährte Methoden befolgt werden.
Ab November 2025 hat sich dieses Verhalten geändert:
- ACL-Berechtigungsfilter gelten jetzt auch dann, wenn nur Dienst-API-Schlüssel oder Entra-Authentifizierung für alle Versionen verwendet werden, die ACL unterstützen.
- Wenn das Benutzertoken nicht angegeben wird, werden ACL-geschützte Inhalte nicht zurückgegeben.
- Um alle Dokumente zur Fehlerbehebung anzuzeigen, müssen Sie bei Verwendung der REST-API-Version
2026-05-01-previewoder höher den Header für erweiterten Lesezugriff explizit angeben.
Dieses Update trägt dazu bei, dass Inhalte geschützt bleiben, wenn Anwendungen keine bewährten Methoden für die Tokenüberprüfung erzwingen.
Verwandte Inhalte
- Tutorial: Indizierung von Berechtigungsmetadaten aus ADLS Gen2 und Abfrage mit nach Berechtigungen gefilterten Ergebnissen
- Indexdokument-ACLs mit den Push-REST-APIs
- Verwenden Sie einen ADLS Gen2-Indexer, um Berechtigungsmetadaten aufzunehmen
- Verwenden Sie einen BLOB-Indexer oder eine Wissensquelle, um RBAC-Bereichsmetadaten zu erfassen
- Verwenden Sie einen SharePoint-Indexer zum Aufnehmen von Berechtigungsmetadaten und Filtern von Suchergebnissen basierend auf Benutzerzugriffsrechten