Verwenden eines SharePoint Indexers zum Aufnehmen von Berechtigungsmetadaten und Filtern von Suchergebnissen basierend auf Benutzerzugriffsrechten (Vorschau)

Die SharePoint-Berechtigungs-Metadatenerfassung (Vorschauversion) verwendet einen Azure KI-Suche-Indexer, um Berechtigungsmetadaten wie Zugriffssteuerungslisten (ACLs) neben anderen Inhalten aus SharePoint in Microsoft 365 beizubehalten. Der Indexer speichert die Berechtigungen als Metadaten für jedes indizierte Dokument. Zur Abfragezeit erhalten Benutzer nur Dokumente, auf die sie über die Berechtigung zum Zugriff verfügen.

Voraussetzungen

• Azure KI-Suche auf einer abrechnungsfähigen Ebene (Einfach oder höher) in einer beliebigen Region.

• SharePoint in Microsoft 365 Websites, Bibliotheken, Ordnern und Dateien mit konfigurierten Berechtigungen.

• Führen Sie alle Konfigurationsschritte in der Dokumentation SharePoint Indexer aus, und wenden Sie die in diesem Artikel beschriebenen ACL-spezifischen Anforderungen an.

• Konfigurieren Sie Anwendungsberechtigungen für Microsoft Entra und eine für Ihr Szenario geeignete Anmeldeinformation. Siehe Berechtigungen nach ACL-Szenario. Für die ACL-Erfassung sind Anwendungsberechtigungen erforderlich. Delegierte Berechtigungen werden nicht unterstützt. Informationen zu Anwendungs- und delegierten Entscheidungen finden Sie unter Auswählen der Berechtigungskonfiguration.

• REST API Version 2026-08-01-preview oder ein entsprechendes Vorschau-SDK-Paket.

Einschränkungen

• Inkrementelle ACL-Updates erfordern die REST-API 2026-05-01-preview oder neuer. In früheren Vorschau-API-Versionen erfasst das System ACLs nur bei der ersten Aufnahme jedes Elements. Spätere Berechtigungsänderungen erfordern eine explizite Neuindizierung. Schritte zur Migration finden Sie unter Synchronisieren von Berechtigungen zwischen indizierten und Quellinhalten.

• Berechtigungsänderungen im übergeordneten Bereich werden bei nachfolgenden Indizierungsausführungen nicht automatisch aufgenommen. Informationen zu den Aktualisierungsoptionen finden Sie unter "Synchronisieren von Berechtigungen zwischen indiziertem und Quellinhalt".

• Dieses Feature wird vom Azure-Portal nicht unterstützt.

• Die folgenden Features werden in dieser Vorschau nicht unterstützt:

  • SharePoint Informationsverwaltungsrichtlinien anwendbar für den Benutzerzugriff. Das System wertet diese Richtlinien zur Abfragezeit nicht aus, nimmt sie auf oder berücksichtigt sie nicht.

  • Freigabefähige Links für "Jeder" oder "Personen in Ihrer Organisation". Nur Links, die auf "Bestimmte Personen" festgelegt sind, werden unterstützt.

  • SharePoint-Gruppen (z. B. Besitzer, Mitglieder und Besuchergruppen) werden ab 2026-05-01-Preview-REST-API unterstützt. Siehe Configure SharePoint Gruppenunterstützung. In früheren Vorschau-API-Versionen werden nur SharePoint Gruppen unterstützt, die zu Microsoft Entra Gruppen aufgelöst werden.

• Die folgenden Indexerfeatures unterstützen die Berechtigungsvererbung in indizierten Dokumenten, die von SharePoint stammen, nicht. Wenn Sie eines dieser Features in einem Skillset oder Indexer verwenden, werden Berechtigungen auf Dokumentebene nicht in den indizierten Inhalt einbezogen.

  • Benutzerdefinierte Web-API-Fähigkeit

  • Wissensspeicher, einschließlich des Ressourcenspeichers, der für die Bildbereitstellung (Vorschau) im agentischen Abruf erforderlich ist. Daher wird die Bereitstellung von Bildern für Wissensquellen, die SharePoint-ACLs übernehmen, nicht unterstützt.

  • Indexeranreicherungscache

  • Debugsitzungen

Unterstützung für das SharePoint-Berechtigungsmodell

Diese Vorschau unterstützt grundlegende ACLs für Dokumente, Listenelemente und moderne ASPX-Websiteseiten.

Unterstützte Gruppenbeziehungen

Microsoft Entra Gruppentransitivität gilt innerhalb von Microsoft Entra. Es werden keine Microsoft Entra-Gruppen erweitert, die Mitglieder von SharePoint Gruppen sind.

Wie hierarchische Berechtigungen ausgewertet werden

SharePoint Berechtigungen erben die Hierarchie der Website → Bibliothek → Ordner → Datei, es sei denn, die Vererbung ist unterbrochen.

Während der Aufnahme sammelt der Indexer Benutzer- und Gruppen-IDs (ID) auf jeder Ebene und berechnet die effektive ACL für jede Datei.

Berechtigungen nach ACL-Szenario

Die für die ACL-Erfassung erforderlichen Microsoft Entra-Anwendungsberechtigungen und Anmeldeinformationstypen hängen davon ab, welche Element- und Gruppentypen Sie indizieren. In der App-Registrierung werden alle Berechtigungen unter API-Berechtigungen>Berechtigung hinzufügen hinzugefügt, und die Verbundanmeldeinformation wird unter Zertifikate & Geheimnisse>Verbundanmeldeinformationen hinzugefügt. Eine schrittweise Anleitung und Screenshots finden Sie unter Schritt 3: Microsoft Entra-Anwendungsregistrierung erstellen und Konfigurieren der registrierten Anwendung mit einer verwalteten Identität.

Verbundanmeldeinformationen ermöglichen der App die Authentifizierung mithilfe einer vertrauenswürdigen verwalteten Identität anstelle eines Clientschlüssels. Die gleichen Verbundanmeldeinformationen decken sowohl die Erfassung (Indexer) als auch die Abfragezeitbewertung von SharePoint-Websitegruppen ab. Schritte zum Einrichten finden Sie unter Konfigurieren der registrierten Anwendung mit einer verwalteten Identität.

Bevor Sie die ACL-Erfassung aktivieren

Führen Sie die folgenden Schritte für Ihre registrierte Microsoft Entra Anwendung aus:

1. Identifizieren Sie Ihr Szenario in der vorherigen Tabelle basierend auf dem, was Sie indizieren möchten (Dokumentbibliotheksdateien, Listenelemente, ASPX-Websiteseiten), und ob SharePoint Websitegruppen berücksichtigt werden müssen.
2. Öffnen Sie Ihre App-Registrierung im Microsoft Entra Admin Center und wechseln Sie zu API-Berechtigungen>Berechtigung hinzufügen.
3. Fügen Sie die für Ihr Szenario aufgeführten Microsoft Graph Berechtigungen hinzu. Administratorzustimmung erteilen.
4. Wenn Ihr Szenario auch SharePoint Berechtigungen erfordert, wählen Sie Eine Berechtigung hinzufügen erneut aus, wählen Sie die API SharePoint aus, und fügen Sie Sites.FullControl.All (oder Sites.Selected) hinzu. Administratorzustimmung erteilen.
5. Konfigurieren Sie die Anmeldedaten:
   • Für szenarien mit nur Microsoft Graph können Sie entweder einen geheimen Clientschlüssel (Certificates & secretsClient secrets) oder Verbundanmeldeinformationen verwenden.
   • Fügen Sie für jedes Szenario, das SharePoint Berechtigungen enthält, unter Certificates & secretsFederated credentials eine Verbundanmeldeinformationen hinzu. Siehe Konfigurieren der registrierten Anwendung mit einer verwalteten Identität.
6. Gewähren Sie der Anwendung Zugriff auf die Zielwebsites SharePoint Websites (insbesondere, wenn Sie Sites.Selected für den bereichsbezogenen Zugriff verwenden), damit sie die Inhalte und Berechtigungen lesen kann, die Sie indizieren möchten.

Suchen der richtigen Microsoft Entra-IDs

Jeder Bezeichner wird an einem anderen Ort im Azure Portal angezeigt und einem bestimmten Konfigurationsfeld zugeordnet. Verwenden Sie diesen Abschnitt als Referenz, wenn Sie SharePoint ACL-Erfassung mit Verbundanmeldeinformationen konfigurieren. Diese Bezeichner werden in Unterstützung für SharePoint-Gruppen konfigurieren und in der Verbindungszeichenfolge der Datenquelle verwendet.

Anwendungs-ID für Verbundanmeldeinformationen

Verwenden Sie für FederatedCredentialApplicationId in der Verbindungszeichenfolge der Datenquelle und für federatedCredentialId in der Indexdefinition die eigene Anwendungs-ID (Client-ID) der verwalteten Identität, nicht die ID der Erfassungs-App.

Vom System zugewiesene verwaltete Identität:

1. Wechseln Sie zu Ihrem Azure KI-Suche-Dienst.
2. Wählen Sie "Sicherheit + Netzwerkidentität>" aus.
3. Notieren Sie sich auf der Registerkarte Vom System zugewiesen die Objekt-ID (Prinzipal).
4. Wechseln Sie zu Microsoft Entra ID>Manage>Enterprise-Anwendungen.
5. Suchen Sie nach Ihrem Suchdienstnamen, oder fügen Sie die Objekt-ID (Prinzipal) in das Suchfeld ein.
6. Wählen Sie das Ergebnis aus, und öffnen Sie "Eigenschaften". Kopieren Sie die hier gezeigte Anwendungs-ID , bei der es sich um den Wert FederatedCredentialApplicationId in der Datenquelle und federatedCredentialId im Index handelt.

Vom Benutzer zugewiesene verwaltete Identität:

1. Wechseln Sie zur vom Benutzer zugewiesenen verwalteten Identitätsressource.
2. Wählen Sie Einstellungen>Eigenschaften aus.
3. Kopieren Sie die Client-ID, bei der es sich um den Wert FederatedCredentialApplicationId in der Datenquelle und federatedCredentialId im Index handelt.

Konfigurieren des Suchdienstes für die ACL-Erfassung und die Durchsetzung zur Abfragezeit

Diese Schritte konfigurieren Ihren Suchdienst für die ACL-Integration und aktivieren die ACL-Anerkennung während der Abfrage.

Auswählen, wo ACL-Felder aufgefüllt werden sollen

Wo Sie die ACL-Metadatenfelder zuordnen, hängt davon ab, ob der Indexer ein Dokument pro Quellelement oder mehrere Blöcke pro Quellelement schreibt.

In allen Segmentierungsszenarien muss jedes Segment die ACL-Felder enthalten. Berechtigungsfilter gelten pro Dokument, sodass ein Chunk, dem ACL-Felder fehlen, nicht an den richtigen Aufrufer zurückgegeben werden kann.

1. Datenquellenkonfiguration

Dieser Abschnitt ist ein Delta über der grundlegenden exemplarischen Vorgehensweise gemäß Schritt 4: Erstellen einer Datenquelle. Legen Sie indexerPermissionOptions in der Datenquellendefinition fest, um die Indizierung von userIds und groupIds aus SharePoint Dokumenten zu ermöglichen.

{
  "name": "my-sharepoint-acl-datasource",
  "type": "sharepoint",
  "indexerPermissionOptions": ["userIds", "groupIds"],
  "credentials": {
    "connectionString": "<connection-string>;"
  },
  "container": {
    "name": "<library-name>",
    "query": "<optional-folder-path>"
  }
}

2. Hinzufügen von Berechtigungsfeldern zur Indexdefinition

Fügen Sie Ihrer Indexschemadefinition Felder hinzu, um ACLs zu speichern und abfragezeitfiltern zu unterstützen.

{
  "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 }
  ],
  "permissionFilterOption": "enabled"
}

Legen Sie das Attribut retrievable nur während der Entwicklung auf true fest, um die Werte zu verifizieren. Sie können "retrievable" von "true" in "false" ändern, ohne eine Indexneuerstellung zu erfordern.

3. Konfigurieren von Indexprojektionen in Ihrem Skillset (falls zutreffend)

Wenn Chunking aktiviert ist, wird das übergeordnete Dokument nicht in den Index geschrieben, wenn projectionModeskipIndexingParentDocuments ist. Übertragen Sie die ACL-Metadaten über indexProjections.selectors[].mappings für jeden Chunk.

Wenn Ihr Indexer ein Skillset mit Datenblöcken verwendet, z. B. die Fähigkeit "Textteilung" beim Aktivieren der integrierten Vektorisierung, stellen Sie sicher, dass ACL-Eigenschaften mithilfe von Indexprojektionen jedem Abschnitt zugeordnet werden. Die // Zeilen im folgenden Beispiel sind illustrative Anmerkungen und sind keine gültigen JSON-Werte. Entfernen Sie sie, bevor Sie die Anforderung übermitteln.

PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2026-08-01-preview
{
  "name": "my-skillset",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
      "name": "#split",
      "context": "/document",
      "inputs": [{ "name": "text", "source": "/document/content" }],
      "outputs": [{ "name": "textItems", "targetName": "chunks" }]
    }
    // ... (other skills such as embeddings, entity recognition, etc.)
  ],
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "chunks-index",
        "parentKeyFieldName": "parentId",          // must exist in target index
        "sourceContext": "/document/chunks/*",     // match your split output path
        "mappings": [
          { "name": "chunkId",           "source": "/document/chunks/*/id" },     // if you create an id per chunk
          { "name": "content",           "source": "/document/chunks/*/text" },   // chunk text
          { "name": "parentId",          "source": "/document/id" },              // parent doc id
          { "name": "UserIds",  "source": "/document/metadata_user_ids" },
          { "name": "GroupIds",  "source": "/document/metadata_group_ids" },
          { "name": "SharePointSiteUrl", "source": "/document/metadata_spo_site_url" } // include when the index has sharePointConnectorAppRegistration (SharePoint groups support)
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

Die Zuordnungen UserIds, GroupIds und SharePointSiteUrl lesen Metadaten auf Quellenebene, die vom SharePoint-Indexer (/document/metadata_*) ausgegeben werden, und schreiben die Werte in jedes Segment.

4. Konfigurieren der Indexerfeldzuordnungen für ACLs

Verwenden Sie Indexerfeldzuordnungen, wenn der Indexer ein Dokument pro Quellelement (ohne Blöcke) schreibt oder wenn Sie einen separaten übergeordneten Index zusammen mit einem Blockindex verwalten. Wenn Ihr Skillset Dokumente in Blöcke aufteilt und dabei einen einzelnen Zielindex mit projectionMode: skipIndexingParentDocuments verwendet, werden die hier gezeigten Feldzuordnungen durch das indexProjections.mappings aus dem vorherigen Schritt für den Blockindex außer Kraft gesetzt.

Ordnen Sie ACL-Rohmetadatenfelder von SharePoint zu Ihren Indexfeldern zu, neben der erforderlichen Indexerkonfiguration.

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",  "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" }
  ]
}

5. Führen Sie den Indexer aus.

ACL-Metadaten werden aufgenommen, wenn der Indexer ausgeführt wird. Nachdem Sie den Indexer erstellt oder aktualisiert haben (siehe Schritt 6: Erstellen eines Indexers), lösen Sie eine Ausführung aus, sodass der Indexer ACLs zusammen mit Inhalten einnimmt.

POST https://[service name].search.windows.net/indexers/[indexer-name]/run?api-version=2026-08-01-preview
api-key: [admin key]

Wenn Sie die ACL-Erfassung für einen vorhandenen Indexer aktiviert haben, der bereits Elemente indiziert hat, rufen Sie /resync mit options: ["permissions"] auf, um ACLs für diese Elemente nachträglich aufzufüllen, oder /resetdocs, um bestimmte Elemente erneut zu extrahieren.

6. Überprüfen der ACL-Erfassung

So bestätigen Sie, dass ACL-Werte richtig ausgefüllt sind:

1. Legen Sie in Ihrer Indexdefinition retrievable vorübergehend auf true fest für UserIds und GroupIds. Das Ändern retrievable erfordert keine Indexneuerstellung.
2. Führen Sie eine Abfrage mit erweiterten Leseberechtigungen aus, die UserIds und GroupIds auswählt, und bestätigen Sie, dass die Sammlungen nicht leer sind. Vergewissern Sie sich bei chunkbasierten Szenarien, dass jeder Chunk beide Felder enthält.
3. Senden Sie retrievable nach der Überprüfung an false zurück.

Konfigurieren SharePoint Gruppenunterstützung

Ab der REST-API 2026-05-01 kann der SharePoint Indexer SharePoint Websitegruppenmitgliedschaften (Besitzer, Mitglieder, Besucher und benutzerdefinierte Websitegruppen) erfassen. Dies berücksichtigt diese Gruppen zur Abfragezeit. SharePoint-Gruppe IDs werden im Feld metadata_group_ids mit dem Präfix spg: ausgegeben, um sie von Microsoft Entra Gruppenobjekt-IDs zu unterscheiden.

Diese exemplarische Vorgehensweise ist in sich abgeschlossen: Führen Sie die Schritte der Reihe nach aus, um den Index und die Indexerfeldzuordnungen zu konfigurieren und den Index mit Durchsetzung von SharePoint-Websitegruppen abzufragen.

Die folgenden Komponenten arbeiten zusammen, um die Auflösung von SharePoint-Websitegruppen zu ermöglichen:

1. Voraussetzungen

• SharePoint-Indexer ist bereits für die ACL-Erfassung konfiguriert. Siehe Konfigurieren der Indexerfeldzuordnungen für ACLs.
• Microsoft Entra-App-Registrierung mit Anmeldeinformationen für eine Verbundidentität. Siehe Konfigurieren der registrierten Anwendung mit einer verwalteten Identität.
• REST-API 2026-05-01-preview oder höher.

2. Konfigurieren des Indexes

Fügen Sie die sharePointConnectorAppRegistration Konfiguration und das SharePointSiteUrl Feld zusammen mit den UserIds Feldern und GroupIds Berechtigungsfiltern hinzu, sodass sich das vollständige Index-Shape an einer zentralen Stelle befindet. Behalten Sie permissionFilterOption: "enabled".

PUT https://{service}.search.windows.net/indexes/{index}?api-version=2026-08-01-preview
{
  "name": "my-sharepoint-acl-index",
  "sharePointConnectorAppRegistration": {
      "applicationId": "<ingestion-app-client-id>",
      "federatedCredentialId": "<managed-identity-application-id>",
     "tenantId": "<sharepoint-tenant-id>"
  },
  "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": "SharePointSiteUrl", "type": "Edm.String", "sharepointSiteUrl": true, "filterable": false, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

3. Konfigurieren der Indexerfeldzuordnungen

Ordnen Sie die SharePoint Metadatenfelder den Indexfeldern in einem einzigen kombinierten Zuordnungsblock zu. Die ersten beiden Zuordnungen sind dieselben, die für die standardmäßige ACL-Erfassung verwendet werden; die dritte Zuordnung aktiviert die Auflösung von SharePoint-Gruppen.

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",             "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids",            "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_spo_site_url",  "targetFieldName": "SharePointSiteUrl" }
  ]
}

Wenn Ihr Skillset Dokumente in Blöcke aufteilt (z. B. mit der Fertigkeit zur Textaufteilung für die integrierte Vektorisierung), projizieren Sie stattdessen SharePointSiteUrl über indexProjections.mappings auf jeden Block. Siehe Auswählen, wo ACL-Felder aufgefüllt werden sollen.

4. Abfragen des Indexes

Es ist keine clientseitige Änderung erforderlich. Dasselbe x-ms-query-source-authorization-Token aktiviert sowohl die Microsoft Entra-Durchsetzung als auch die Durchsetzung von SharePoint-Websitegruppen. Der Suchdienst löst die Mitgliedschaften von SharePoint-Gruppen serverseitig unter Verwendung von sharePointConnectorAppRegistration im Index auf.

Das Anforderungsformat finden Sie im allgemeinen Abfragebeispiel sowie im SharePoint-spezifischen Beispiel mit Erzwingung von SharePoint-Websitegruppen.

5. Überprüfen

Um zu bestätigen, dass SharePoint-Gruppe IDs im Index landen, führen Sie eine elevated-read query aus, die GroupIds auswählt, und suchen Sie in der Antwort nach spg:-präfixierten Werten.

Berechtigungen zwischen indizierten und Quellinhalten synchronisieren

Ab der REST-API 2026-05-01-Vorschau werden ACL-Änderungen für Elemente mit eindeutigen Berechtigungen erkannt und bei jeder erfolgreichen Indizierungsausführung aktualisiert. Der Indexer verwendet SharePoint-Änderungstoken, um Hinzufügungen und Entfernungen von Rollenzuweisungen inkrementell zu erfassen, genauso wie er Inhaltsänderungen erfasst.

Für einige Szenarien ist weiterhin eine explizite Aktualisierung erforderlich:

Zurücksetzen bestimmter Dokumente

Sie können bestimmte Dokumente zurücksetzen, um Inhalte und ACLs vollständig neu zu erfassen.

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{
  "documentKeys": ["doc123", "doc456"]
}

Resynchronisieren der ACLs über die gesamte Datenquelle hinweg

Sie können den ACL-Inhalt des vollständigen Datasets nach der ursprünglichen Erfassung vollständig erneut synchronisieren. Um diesen Vorgang vollständig erfolgreich abzuschließen, ist nach Abschluss ein Indexer-Lauf erforderlich.

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{
  "options": ["permissions"]
}

Nach der Indizierung Ihrer Daten und ACLs können Sie den Index abfragen.

Problembehandlung

Informationen zu fehlenden, unerwarteten oder fehlgeschlagenen Abfragezeitergebnissen, nachdem ACL-Metadaten indiziert wurden, finden Sie unter Problembehandlung SharePoint Berechtigungsfilterung.

Verwandte Inhalte

• Indexiere SharePoint-Inhalte in Azure KI-Suche (Vorschau)
• Abfragezeit-ACL-Erzwingung