Indizieren von Dokumentzugriffssteuerungslisten (ACLs) mithilfe der Push-REST-APIs (Vorschau)

Die Erfassung von Berechtigungen auf Dokumentebene über die Push-REST-APIs (Vorschau) ermöglicht es Ihnen, Dokumente zusammen mit den zugehörigen Zugriffssteuerungslisten (ACLs) und den containerbasierten rollenbasierten Zugriffssteuerungsrollen (RBAC-Rollen) zu indizieren. Wenn Sie Inhalte über die Push-REST-APIs in einen Azure KI-Suche Index übertragen, behält der Dienst diese Berechtigungen für indizierte Inhalte bei und erzwingt sie 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 Azure KI-Suche 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 userIds und groupIds ACL-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.

• Die neueste Vorschau-REST-API oder ein Vorschau-Azure-SDK-Paket, das entsprechende Funktionen bereitstellt.

• Ein Indexschema mit aktivierten permissionFilterOption und permissionFilter Feldattributen, die Dokumentberechtigungen speichern.

Einschränkungen

• Ein ACL-Feld mit Berechtigungsfiltertyp userIds oder groupIds kann höchstens 1000 Werte enthalten.

• Ein Index kann höchstens fünf eindeutige Werte zwischen Feldern des Typs rbacScope für alle Dokumente enthalten. Es gibt keine Beschränkung für die Anzahl der Dokumente, die denselben Wert rbacScopeaufweisen.

• Ein vorhandenes Feld kann aktualisiert werden, um eine permissionFilter Zuordnung für die integrierte Metadatenfilterung von ACL oder RBAC einzuschließen. Um das Filtern nach einem vorhandenen Index zu aktivieren, fügen Sie neue Felder hinzu, oder aktualisieren Sie vorhandene Felder, um einen permissionFilter Wert einzuschließen.

• In einem Index kann jeweils nur ein Feld jedes Typs (permissionFilter, groupIds, userIds und rbacScope) existieren.

• Jedes permissionFilter-Feld sollte filterable auf true gesetzt werden.

• 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.

Fügen Sie zuerst permissionFilterOption hinzu. Gültige Werte sind enabled oder disabled, und Sie sollten es auf enabled setzen. Sie können es auf disabled umschalten, wenn Sie die Berechtigungsfilterfunktion auf Indexebene deaktivieren möchten.

Zweitens, erstellen Sie Zeichenfolgenfelder für Ihre Berechtigungsmetadaten und fügen Sie permissionFilter hinzu. Denken Sie daran, dass Sie über einen der einzelnen Berechtigungsfiltertypen verfügen können.

Hier ist ein einfaches Beispielschema, das alle permissionFilter Typen enthält:

{  
  "fields": [  
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true },  
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true },  
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true },  
    { "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.

Beispiel für die REST-API-Indizierung

Sobald Sie über einen Index mit Berechtigungsfilterfeldern verfügen, können Sie diese Werte mithilfe der Pushindizierungs-API wie alle anderen Dokumentfelder auffüllen. Hier ist ein Beispiel für die Verwendung des angegebenen Indexschemas, in dem jedes Dokument die Indizierungsaktion, das Schlüsselfeld (DocumentId) und die Berechtigungsfelder angibt. Dokumente sollten auch Inhalt enthalten, dieses Feld wird jedoch in diesem Beispiel aus Platzgründen weggelassen.

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-08-01-preview
{
  "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": ["all"],
      "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"
    }
  ]
}

Auflösungsregeln für ACL-Zugriffe

In diesem Abschnitt wird erläutert, wie das System den Dokumentzugriff eines Benutzers basierend auf den Berechtigungsfeldern für jedes Dokument bestimmt. Bei diesen Feldern handelt es sich entweder um ACLs (userIds und groupIds, wobei groupIds Sicherheitsgruppen und Microsoft 365-Gruppen umfasst) oder um einen RBAC-Bereich (rbacScope). Azure wertet den RBAC-Bereich und die ACLs in einer definierten Reihenfolge aus, die mit dem ADLS Gen2-Berechtigungsmodell konsistent ist.

Ein Benutzer erhält Zugriff, wenn eines der folgenden Kriterien erfüllt ist: ein passender userIds- oder groupIds-Eintrag oder eine entsprechende Azure-Rollenzuweisung für die rbacScope. Informationen dazu, wie Aufruferidentitäten zur Abfragezeit bereitgestellt werden, finden Sie unter Abfragezeit-ACL- und RBAC-Erzwingung.

Spezielle ACL-Werte ‚all‘ und ‚none‘

ACL-Felder, wie z. B. userIds und groupIds, enthalten in der Regel Listen mit GUIDs (Globally Unique Identifiers), die Benutzer und Gruppen mit Zugriff auf das Dokument identifizieren. Für diese ACL-Feldtypen werden zwei spezielle Zeichenfolgenwerte unterstützt: "all" und "none". Diese Werte dienen als breite Filter, um den Zugriff auf globaler Ebene zu steuern, wie in der folgenden Tabelle dargestellt.

Da ein Benutzer nur einem Feldtyp entsprechen muss, gewährt der Sonderwert "alle" unabhängig von anderen ACL-Feldwerten öffentlichen Zugriff. Im Gegensatz dazu bedeutet die Einstellung userIds auf "None" oder ein leeres Array, dass keine Benutzer zugriff auf das Dokument basierend auf der Benutzer-ID 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).

Verwandte Inhalte

• Verbindung zu Azure KI-Suche mit Rollen herstellen
• Abfragezeit ACL- und RBAC-Durchsetzung
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API