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.
Die Berechtigungsaufnahme auf Dokumentebene über die Push-REST-APIs ist allgemein verfügbar. Verwenden Sie die Push-REST-APIs zum Indizieren von Inhalten mit Microsoft Entra Benutzer- und Gruppen-IDs oder Speichercontainer-RBAC-Bereichen. Foundry IQ (Azure KI-Suche) verwendet diese Metadaten zum Filtern von Dokumenten zur Abfragezeit.
Zu den wichtigsten Features gehören:
- Flexible Kontrolle über Aufnahmeleitungen.
- Standardisiertes Schema für Berechtigungsmetadaten.
- Unterstützung für hierarchische Berechtigungen, z. B. ACLs auf Ordnerebene.
In diesem Artikel wird erläutert, wie Sie die Push-REST-API zum Indizieren von Berechtigungsmetadaten auf Dokumentebene in Foundry IQ verwenden. Dieser Prozess bereitet Ihren Index auf das Abfragen und Erzwingen von Endbenutzerberechtigungen für Suchergebnisse vor.
Voraussetzungen
Inhalt mit ACL-Metadaten aus Microsoft Entra ID oder einem anderen POSIX-ACL-System. Verwenden Sie für
userIdsundgroupIdsACL-Felder Microsoft Entra Objekt-IDs (GUIDs), nicht UPNs oder E-Mail-Adressen. Stabile Objekt-IDs stellen einen zuverlässigen Identitätsabgleich zur Abfragezeit sicher, auch wenn sich die Verzeichnisattribute ändern.REST-API-Version
2026-10-01.Ein Indexschema mit aktivierten
permissionFilterOptionundpermissionFilterFeldattributen, die Dokumentberechtigungen speichern.Vorhandene Berechtigungen zum Erstellen der Indexdefinition, zum Hochladen von Dokumenten und zum Abfragen des Indexes sind erforderlich. Informationen zu rollenbasiertem Zugriff finden Sie unter Connect using roles.
Für die Abfragebeispiele werden ein delegiertes Benutzerzugriffstoken und die Microsoft Entra Objekt-ID desselben Benutzers verwendet. Siehe Abfragezeittokenrollen und Berechtigungsflüsse.
Einschränkungen
Ein ACL-Feld mit Berechtigungsfiltertyp
userIdsodergroupIdskann höchstens 1000 Werte enthalten.Ein Index kann maximal fünf unterschiedliche
rbacScopeWerte in allen Dokumenten enthalten.Systemeigene
permissionFilterAnmerkungen können vorhandenen kompatiblen Feldern hinzugefügt oder daraus entfernt werden. Eine vorhandene Annotation kann nicht direkt in einen anderen Berechtigungsfiltertyp geändert werden.In einem Index kann jeweils nur ein Feld jedes Typs (
permissionFilter,groupIds,userIdsundrbacScope) existieren.Jedes
permissionFilter-Feld mussfilterableund auf oberster Ebene sein. Es darf kein Schlüssel- oder Vektorfeld sein. Berechtigungsfelder können keine Analysatoren, Normalisierer oder Synonymzuordnungen haben.Die Erzwingung von Abfragezeitberechtigungen spiegelt die zuletzt in den Index geschriebenen ACL-Werte wider. Wenn sich die Quellberechtigungen ändern, werden diese Änderungen erst übernommen, wenn Sie die betroffenen Dokumente neu einlesen oder aktualisieren. Planen Sie eine inkrementelle erneute Erfassung oder Teilaktualisierungen, um ACLs auf dem aktuellen Stand zu halten.
Diese Funktionalität wird derzeit im Azure-Portal nicht unterstützt.
Erstellen eines Indexes mit Berechtigungsfilterfeldern
Für das Indizieren von Dokument-ACLs und RBAC-Metadaten mit der REST-API muss ein Indexschema eingerichtet werden, das Berechtigungsfilter ermöglicht und Felder mit Berechtigungsfilterzuweisungen enthält.
Setzen Sie permissionFilterOption explizit auf enabled. Gültige Werte sind enabled und disabled. Bei einem neuen Index mit Berechtigungsfeldanmerkungen wird die Option, wenn sie weggelassen wird, standardmäßig auf enabled gesetzt. Bei einer Aktualisierung bleibt eine vorhandene Option erhalten, wenn die Angabe weggelassen wird.
Verwenden Sie Collection(Edm.String) für userIds und groupIds und Edm.String für rbacScope. Ein Index kann über ein Feld jedes Annotationstyps verfügen.
Der folgende 2026-10-01 Workflow erstellt einen separaten Beispielindex mit einem userIds Berechtigungsfeld. Das durchsuchbare content Feld unterstützt auch die moreLikeThis-Beispiele. Ersetzen Sie ihn <SEARCH_SERVICE_ENDPOINT> durch Ihren Endpunkt und <SEARCH_ACCESS_TOKEN> durch ein Aufrufertoken, das über die erforderlichen Suchrollen verfügt. Verwenden Sie den Beispielnamen nur für einen neuen Index, da die Anforderung einen vorhandenen Index mit demselben Namen aktualisiert.
PUT <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')?api-version=2026-10-01
Authorization: Bearer <SEARCH_ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json
{
"name": "secured-content-index",
"fields": [
{
"name": "id",
"type": "Edm.String",
"key": true,
"searchable": false,
"filterable": true,
"sortable": true
},
{
"name": "content",
"type": "Edm.String",
"searchable": true,
"filterable": false,
"sortable": false,
"facetable": false
},
{
"name": "category",
"type": "Edm.String",
"searchable": false,
"filterable": true,
"sortable": false,
"facetable": false
},
{
"name": "userIds",
"type": "Collection(Edm.String)",
"filterable": true,
"retrievable": false,
"searchable": false,
"sortable": false,
"facetable": false,
"permissionFilter": "userIds"
}
],
"permissionFilterOption": "enabled"
}
Referenz: Erstellen oder Aktualisieren des Indexes.
Das folgende 2026-10-01 Schemafragment veranschaulicht alle drei systemeigenen Berechtigungsfeldtypen für das Indizierungsbeispiel weiter unten in diesem Artikel:
{
"fields": [
{ "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true, "retrievable": false },
{ "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
{ "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false },
{ "name": "DocumentId", "type": "Edm.String", "key": true }
],
"permissionFilterOption": "enabled"
}
Bei Unternehmens-Repositorys wie SharePoint Online müssen Sie die Berechtigungen auf Dokument- oder Ordnerebene vor dem Aufruf der Push-API in Microsoft Entra-Benutzer- und Gruppenobjekt-IDs auflösen. Sie sollten diese IDs dann in den entsprechenden Berechtigungsfeldern speichern.
Einrichten einer vertrauenswürdigen Dokumentidentität und Berechtigungen
Beschränken Sie die Dokumentveröffentlichung auf Identitäten, die autorisiert sind, den Zielinhalt und die Zielberechtigungen zu verwalten. Der Herausgeber muss Berechtigungen aus einer autoritativen Zugriffsrichtlinie für dieselbe Dokumentidentität erhalten, anstatt berechtigungsähnliche Eigenschaften aus normalen Inhalten zu kopieren.
Überprüfen Sie den Dokumentschlüssel und die Berechtigungen zusammen, bevor Sie einen Upload übermitteln oder eine Zusammenführung durchführen. Das erneute Verwenden eines Schlüssels zielt auf denselben indizierten Datensatz ab; die Berechtigung zum Schreiben von Inhalten ist für sich genommen keine Befugnis, die Inhalte oder Berechtigungen eines anderen Datensatzes zu ändern. Wenn mehrere vertrauenswürdige Quellen absichtlich einen Datensatz gemeinsam nutzen, einigen Sie sich auf die Besitzverhältnisse und die endgültige Berechtigungsrichtlinie. Eine Zusammenführung ersetzt eine angegebene Auflistung, anstatt die Einträge mit vorhandenen Werten zu kombinieren.
Steuern Sie für eine vom Kunden verwaltete Pipeline, welcher Quellwert DocumentId bereitstellt und welche Richtlinie Berechtigungen für diese Identität gewährt. Behalten Sie Geschäfts-IDs getrennt bei, wenn sie nicht über die beitragenden Quellen hinweg eindeutig sind. Lassen Sie nicht zu, dass Inhalte mit niedriger Vertrauensebene den Schlüssel oder die Berechtigungswerte eines anderen Datensatzes auswählen. Diese Verantwortlichkeiten liegen beim autorisierten Herausgeber, nicht bei einer neuen Einstellung zur Erzwingung des Besitzes.
Die Berechtigungsfeldanmerkungen ermöglichen die Abfrageauswertung gespeicherter Werte; sie stellen nicht fest, dass ein Inhaltsautor berechtigt ist, diese Finanzhilfen zu erteilen. Verwenden Sie die Prüfliste für die Aufnahmekonfiguration , um die Identitäts- und Berechtigungsauswahl innerhalb des vertrauenswürdigen Veröffentlichungsprozesses beizubehalten.
Beispiel für die REST-API-Indizierung
Füllen Sie Berechtigungsfelder wie andere Dokumentfelder aus. Laden Sie für den 2026-10-01 zuvor erstellten Index die folgenden vier Dokumente hoch. Ersetzen Sie durch <USER_OBJECT_ID> die Microsoft Entra-Objekt-ID des delegierten Benutzers, dessen Token Sie im Abfragebeispiel angeben. Dokumente 21, 101 und control gewähren diesem Benutzer Zugriff; hidden hat keine Berechtigung.
POST <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')/docs/search.index?api-version=2026-10-01
Authorization: Bearer <SEARCH_ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json
{
"value": [
{
"@search.action": "upload",
"id": "21",
"content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
"category": "astronomy",
"userIds": [
"<USER_OBJECT_ID>"
]
},
{
"@search.action": "upload",
"id": "101",
"content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
"category": "astronomy",
"userIds": [
"<USER_OBJECT_ID>"
]
},
{
"@search.action": "upload",
"id": "hidden",
"content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
"category": "astronomy",
"userIds": [
"none"
]
},
{
"@search.action": "upload",
"id": "control",
"content": "Botanical gardens cultivate orchids and roses. Gardeners prune flowering plants and water their roots. A greenhouse protects young seedlings from cold weather.",
"category": "gardening",
"userIds": [
"<USER_OBJECT_ID>"
]
}
]
}
Referenz: Indexdokumente.
Fahren Sie mit dem Abfragebeispiel fort, um zu bestätigen, dass die Dokumente des Benutzers zurückgegeben werden, während hidden ausgeschlossen ist.
Das folgende 2026-10-01 Beispiel veranschaulicht die anderen Optionen.
POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-10-01
{
"value": [
{
"@search.action": "upload",
"DocumentId": "1",
"UserIds": ["00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"],
"GroupIds": ["none"],
"RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-01"
},
{
"@search.action": "merge",
"DocumentId": "2",
"UserIds": ["none"],
"GroupIds": ["33dd33dd-ee44-ff55-aa66-77bb77bb77bb", "44ee44ee-ff55-aa66-bb77-88cc88cc88cc"]
},
{
"@search.action": "mergeOrUpload",
"DocumentId": "3",
"UserIds": ["1cdd8521-38cf-49ab-b483-17ddaa48f68f"],
"RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-03"
}
]
}
Aktualisieren von ACLs, die vor der Normalisierungsänderung vom Oktober 2026 gepusht wurden
Foundry IQ normalisiert Berechtigungs-ID-Werte zu Kleinbuchstaben, wenn Sie Dokumente übermitteln. Dieses Verhalten gilt für Felder, die mit permissionFilter: "userIds" oder permissionFilter: "groupIds" annotiert sind, aber es gilt nicht für die Feldnamen oder nicht zusammenhängende Dokumentfelder.
Ein Dienstupdate vom Oktober 2026 führt diese Normalisierung für 2026-05-01-preview und 2026-08-01-preview. Diese Änderung gilt auch in der GA-REST-API 2026-10-01. Der Dienst schreibt zuvor gespeicherte Werte nicht automatisch neu. Wenn Sie die API-Version allein ändern, werden sie nicht aktualisiert.
Wenn Sie ACLs direkt mithilfe einer der beiden Vorschauversionen vor der Normalisierungsänderung übertragen haben, können vorhandene Berechtigungs-IDs in Großbuchstaben oder gemischter Schreibweise nicht mit Abfragezeitidentitäten übereinstimmen. Autorisierte Benutzer erhalten möglicherweise weniger Ergebnisse als erwartet.
Diese Migration gilt nur für ACLs, die direkt über die Push-API übermittelt werden. Es ist nicht für integrierte Indizierer oder indizierte Wissensquellen erforderlich.
So indizieren Sie betroffene ACL-Werte:
- Identifizieren Sie Dokumente und Blöcke mit Berechtigungs-IDs, die vor der Änderung übertragen wurden. In Kleinbuchstaben gespeicherte Werte benötigen diese Anpassung der Groß-/Kleinschreibung nicht.
- Übermitteln Sie die aktuellen ACL-Werte für jeden betroffenen Datensatz erneut. Verwenden Sie eine
mergeAktion mit dem Dokumentschlüssel und vollständige Berechtigungssammlungen, um ACLs zu aktualisieren, ohne Inhalte zu ersetzen. Durch eine Zusammenführung wird die angegebene Sammlung ersetzt; schließen Sie alle aktuellen Berechtigungen ein, nicht nur Einträge, deren Groß-/Kleinschreibung geändert wurde. - Überprüfen Sie die Indizierungsantwort jedes Datensatzes, und wiederholen Sie fehlgeschlagene Aktualisierungen. Fahren Sie fort, bis Sie alle betroffenen Datensätze aktualisieren. Eine partielle Migration kann einen inkonsistenten Abgleich hinterlassen.
- Testen Sie Abfragen als Benutzer, die Zugriff haben sollten, und als Benutzer, der keinen Zugriff haben sollte. Verwenden Sie erweiterten Lesezugriff nur für die Diagnose, nicht zum Verfügbarmachen von ACL-Werten in normalen Benutzerergebnissen.
Auflösungsregeln für ACL-Zugriffe
Die systemeigene Berechtigungsfilterung wertet userIds, groupIds und rbacScope als alternative Berechtigungen aus, die mit ODER kombiniert sind. Eine Übereinstimmung in einem feld gewährt Dokumentzugriff; Eine Nichtübereinstimmung in einem anderen Feld überschreibt diese Gewährung nicht. Für dieses Verhalten bei beliebiger Zugriffsgewährung ist eine erfolgreiche Berechtigungsauswertung erforderlich.
Ein Benutzer erhält Zugriff über eine übereinstimmende Benutzer- oder Gruppen-ID oder die Speicher-BLOB-Leseberechtigung auf der Ebene des indizierten Containerbereichs. Speicherbereichsprüfungen verwenden den delegierten Benutzer in x-ms-query-source-authorization, nicht die Vorgangsanmeldeinformationen. Die Vorgangsautorisierung ist weiterhin erforderlich. Ausführliche Informationen und das Verhalten bei Fehlschlagen der Berechtigungsauswertung finden Sie unter Abfragezeit-ACL- und RBAC-Erzwingung.
Spezieller ACL-Wert "none"
ACL-Felder, wie userIds und groupIds, enthalten in der Regel Microsoft Entra Objekt-IDs (GUIDs), die Benutzer und Gruppen identifizieren, die Zugriff auf das Dokument haben. Verwenden Sie den speziellen Zeichenfolgenwert none oder ein leeres Array, um anzugeben, dass ein ACL-Feld keinen Zugriff gewährt.
| ACL-Wert | Bedeutung |
|---|---|
["none"] |
Kein Benutzer kann auf das Dokument zugreifen, wenn dieser ACL-Typ gilt. |
| [] (leeres Feld) | Kein Benutzer kann auf das Dokument zugreifen, wenn dieser ACL-Typ gilt. |
Das Festlegen userIds auf ["none"] oder ein leeres Array bedeutet, dass keine Benutzer basierend auf der Benutzer-ID Zugriff auf das Dokument erhalten. Möglicherweise wird ihnen weiterhin Zugang gewährt durch übereinstimmende Gruppen-IDs oder RBAC-Metadaten.
Beispiel für zugriffssteuerung
Dieses Beispiel veranschaulicht, wie Dokumentzugriffsregeln anhand der Werte in den Berechtigungsfeldern userIds, groupIds und rbacScope ausgewertet werden. Zur Lesbarkeit verwendet dieses Szenario Aliase wie "user1" und "group1" anstelle von GUIDs; verwenden Sie in der Produktion Microsoft Entra Objekt-IDs (GUIDs).
| Dokument # | Benutzer-IDs | Gruppen-IDs | RBAC-Bereich | Liste zulässiger Benutzer | Hinweis |
|---|---|---|---|---|---|
| 1 | ["none"] |
[] |
Leer | Keine Benutzer haben Zugriff | Die Werte ["none"] und [] verhalten sich genau gleich |
| 2 | ["none"] |
[] |
scope/to/container1 | Benutzer mit RBAC-Berechtigungen für Container1 | Der Wert von "none" blockiert den Zugriff nicht, wenn andere Berechtigungsfelder (groupIds oder rbacScope) Zugriff gewähren |
| 3 | ["none"] |
["group1", "group2"] |
Leer | Mitglieder von Gruppe1 oder Gruppe2 | |
| 4 | ["user1", "user2"] |
["group1"] |
Leer | Benutzer1, Benutzer2 oder ein beliebiges Mitglied von Gruppe1 | |
| 5 | ["user1", "user2"] |
[] |
Leer | Benutzer1 oder Benutzer2 |