Använd en SharePoint indexerare för att mata in behörighetsmetadata och filtrera sökresultat baserat på användaråtkomsträttigheter (förhandsversion)

SharePoint behörighetsmetadatainmatning (förhandsversion) använder en Azure AI-sökning indexerare för att bevara behörighetsmetadata, till exempel åtkomstkontrollistor (ACL), tillsammans med annat innehåll från SharePoint i Microsoft 365. Indexeraren lagrar behörigheterna som metadata för varje indexerat dokument. Vid frågetillfället får användarna endast dokument som de har behörighet att komma åt.

Förutsättningar

• Azure AI-sökning på en fakturerbar nivå (Basic eller högre) i valfri region.

• SharePoint på Microsoft 365 webbplatser, bibliotek, mappar och filer med konfigurerade behörigheter.

• Slutför alla konfigurationssteg i dokumentationen SharePoint indexerare och tillämpa de ACL-specifika krav som beskrivs i den här artikeln.

• Konfigurera Microsoft Entra programbehörigheter och en autentiseringsuppgift som är lämplig för ditt scenario. Se Behörigheter efter ACL-scenario. ACL-inmatning kräver programbehörigheter. Delegerade behörigheter stöds inte. Mer information om skillnaden mellan programbehörighet och delegerad behörighet finns i Välj konfiguration av behörigheter.

• REST API version 2026-08-01-preview eller ett motsvarande SDK-paket för förhandsversion.

Begränsningar

• Inkrementella ACL-uppdateringar kräver REST API-versionen 2026-05-01-preview eller senare. I tidigare förhandsversioner av API:et avbildar systemet endast ACL:er vid den första inmatningen av varje objekt. Senare behörighetsändringar kräver explicit omindexering. Information om migreringssteg finns i Synkronisera behörigheter mellan indexerat innehåll och källinnehåll.

• Behörighetsändringar på överordnad nivå fångas inte upp automatiskt vid efterföljande indexeringskörningar. Information om uppdateringsalternativen finns i Synkronisera behörigheter mellan indexerat innehåll och källinnehåll.

• Den Azure portalen stöder inte den här funktionen.

• Följande funktioner stöds inte i den här förhandsversionen:

  • SharePoint Information Management-principer tillämpliga för användaråtkomst. Systemet utvärderar, inhämtar eller följer inte dessa policyer vid frågetillfället.

  • Delningsbara länkar som är begränsade till "Alla" eller "Personer i din organisation". Endast länkar som är begränsade till "Specifika personer" stöds.

  • SharePoint-grupper (som grupperna Ägare, Medlemmar och Besökare) stöds i REST-API:et 2026-05-01-preview. Se Konfigurera stöd för SharePoint-grupper. I tidigare förhandsversioner av API:et stöds endast SharePoint grupper som matchar Microsoft Entra grupper.

• Följande indexeringsfunktioner stöder inte arv av behörigheter i indexerade dokument som kommer från SharePoint. Om du använder någon av dessa funktioner i en kompetensuppsättning eller indexerare ingår inte behörigheter på dokumentnivå i det indexerade innehållet.

  • Anpassad webb-API-färdighet

  • Kunskapslager, inklusive det resurslager som krävs för bildvisning (förhandsversion) i agentbaserad hämtning. Därför stöds inte bildservering för kunskapskällor som matar in SharePoint ACL:er.

  • Indexerarens berikningscache

  • Felsöka sessioner

Stöd för SharePoint-behörighetsmodellen

Den här förhandsversionen stöder grundläggande ACL:er för dokument, listobjekt och moderna ASPX-webbplatssidor.

Grupprelationer som stöds

Microsoft Entra-grupptransitivitet gäller inom Microsoft Entra. Den expanderar inte Microsoft Entra-grupper som är medlemmar i SharePoint-grupper.

Hur hierarkiska behörigheter utvärderas

SharePoint-behörigheter ärver hierarkin plats → bibliotek → mapp → fil, om inte arv bryts.

Under inmatningen samlar indexeraren in användar- och gruppidentifierare (ID) på varje nivå och beräknar den effektiva ACL:en för varje fil.

Scenario med behörigheter efter ACL

Vilka Microsoft Entra-programbehörigheter och vilken typ av autentiseringsuppgifter som krävs för ACL-import beror på vilka objekttyper och grupptyper du indexerar. I appregistreringen läggs alla behörigheter till under API-behörigheter>Lägg till en behörighet och federerade autentiseringsuppgifter läggs till under Certifikat och hemligheter>Federerade autentiseringsuppgifter. Stegvisa instruktioner och skärmbilder finns i Steg 3: Skapa en Microsoft Entra programregistrering och Konfigurera det registrerade programmet med en hanterad identitet.

En federerad autentiseringsuppgift autentiserar appen med hjälp av en betrodd hanterad identitet i stället för en klienthemlighet. Samma federerade autentiseringsuppgifter omfattar både inmatning (indexerare) och frågetidsutvärdering av SharePoint webbplatsgrupper. Installationssteg finns i Konfigurera det registrerade programmet med en hanterad identitet.

Innan du aktiverar ACL-inmatning

Slutför de här stegen i ditt registrerade Microsoft Entra program:

1. Identifiera ditt scenario i föregående tabell baserat på vad du planerar att indexera (dokumentbiblioteksfiler, listobjekt, ASPX-webbplatssidor) och om SharePoint webbplatsgrupper måste respekteras.
2. Öppna appregistreringen i Microsoft Entra administrationscenter och gå till API-behörigheter>Lägg till en behörighet.
3. Lägg till Microsoft Graph behörigheter som anges för ditt scenario. Bevilja administratörsmedgivande.
4. Om ditt scenario också kräver SharePoint behörigheter väljer du Lägg till en behörighet igen, väljer SharePoint API och lägger till Sites.FullControl.All (eller Sites.Selected). Bevilja administratörsmedgivande.
5. Konfigurera autentiseringsuppgifterna:
   • För scenarier med endast Microsoft Graph kan du använda antingen en klienthemlighet (Certifikat och hemligheter>Klienthemligheter) eller en federerad autentiseringsuppgift.
   • För alla scenarion som innehåller SharePoint behörigheter lägger du till en federerad autentiseringsuppgift under Certificates & secretsFederated credentials. Se Konfigurera det registrerade programmet med en hanterad identitet.
6. Ge programmet åtkomst till målwebbplatserna SharePoint (särskilt viktigt när du använder Sites.Selected för begränsad åtkomst) så att det kan läsa det innehåll och de behörigheter som du vill indexeras.

Hitta rätt Microsoft Entra identifierare

Varje identifierare visas på en annan plats i Azure-portalen och mappar till ett specifikt konfigurationsfält. Använd det här avsnittet som referens när du konfigurerar SharePoint ACL-inmatning med en federerad autentiseringsuppgift. Dessa identifierare refereras till i Konfigurera stöd för SharePoint-grupper och i datakällans anslutningssträng.

Program-ID för federerade autentiseringsuppgifter

För FederatedCredentialApplicationId i anslutningssträngen för datakällan och federatedCredentialId i indexdefinitionen använder du den hanterade identitetens eget program-ID (klient-ID), inte inmatningsappens ID.

Systemtilldelad hanterad identitet:

1. Gå till din Azure AI-sökning-tjänst.
2. Välj Säkerhet + nätverksidentitet>.
3. På fliken Systemtilldelad noterar du objekt-ID:t (huvudnamn).
4. Gå till Microsoft Entra ID>Hantera>Företagsprogram.
5. Sök efter söktjänstens namn eller klistra in objekt-ID:t (huvudnamn) i sökrutan.
6. Välj resultatet och öppna Egenskaper. Kopiera program-ID :t som visas här, vilket är värdet för FederatedCredentialApplicationId i datakällan och federatedCredentialId i indexet.

Användartilldelad hanterad identitet:

1. Gå till den användartilldelade hanterade identitetsresursen.
2. Välj Inställningar>egenskaper.
3. Kopiera klient-ID:t, som är värdet för FederatedCredentialApplicationId i datakällan och federatedCredentialId i indexet.

Konfigurera din söktjänst för ACL-inmatning och tillämpning av frågetid

De här stegen konfigurerar din söktjänst för ACL-inmatning och aktiverar ACL-hantering vid frågetillfället.

Välj var ACL-fält ska fyllas i

Var du mappar ACL-metadatafälten beror på om indexeraren skriver ett dokument per källobjekt eller flera segment per källobjekt.

I alla scenarier med segmentering måste varje segment innehålla ACL-fälten. Behörighetsfilter gäller per dokument, så ett segment som saknar ACL-fält kan inte returneras till rätt anropare.

1. Konfiguration av datakälla

Det här avsnittet är ett delta ovanpå den grundläggande genomgången av steg 4: Skapa datakälla . Ange indexerPermissionOptions i källdefinitionen data för att tillåta indexering av userIds och groupIds från SharePoint dokument.

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

2. Lägg till behörighetsfält i indexdefinitionen

Lägg till fält i indexschemadefinitionen för att lagra ACL:er och stödja frågetidsfiltrering.

{
  "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"
}

Ange retrievable attributet till true endast under utveckling för att verifiera värden. Du kan ändra sökbar från true till false utan att behöva göra en indexombyggnad.

3. Konfigurera indexprognoser i din kompetensuppsättning (om tillämpligt)

När segmentering är aktiverat skrivs inte det överordnade dokumentet till indexet när projectionMode är skipIndexingParentDocuments. Bär ACL-metadata till varje segment genom indexProjections.selectors[].mappings.

Om indexeraren använder en kompetensuppsättning med datasegmentering, till exempel färdigheten Textdelning när du aktiverar integrerad vektorisering, ser du till att mappa ACL-egenskaper till varje segment med hjälp av indexprojektioner. Raderna // i följande exempel är illustrativa anteckningar och är inte giltiga JSON. Ta bort dem innan du skickar begäran.

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"
    }
  }
}

UserIds, GroupIds och SharePointSiteUrl mappningar läser metadata på källnivå som genereras av SharePoint-indexeraren (/document/metadata_*) och skriver värdena till varje segment.

4. Konfigurera indexerarens fältmappningar för ACL:er

Använd indexeringsfältmappningar när indexeraren skriver ett dokument per källobjekt (ingen segmentering) eller när du underhåller ett separat överordnat index tillsammans med ett segmentindex. Om din kompetensuppsättning delar upp dokument i ett enda målindex med projectionMode: skipIndexingParentDocumentsersätts fältmappningarna som visas här av indexProjections.mappings från föregående steg för segmentindexet.

Förutom den nödvändiga konfigurationen av indexer mappar du ACL-fält med rådata från SharePoint till dina indexfält.

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

5. Kör indexeraren

ACL-metadata matas in när indexeraren körs. När du har skapat eller uppdaterat indexeraren (se Steg 6: Skapa en indexerare) utlöser du en körning så att indexeraren matar in ACL:er tillsammans med innehåll.

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

Om du har aktiverat ACL-inmatning på en befintlig indexerare som redan har indexerat objekt anropar /resync du med options: ["permissions"] för att fylla på ACL:er för dessa objekt eller /resetdocs för att extrahera specifika objekt igen.

6. Kontrollera ACL-inläsning

Så här bekräftar du att ACL-värdena har fyllts i korrekt:

1. Ställ tillfälligt in retrievable på true för UserIds och GroupIds i din indexdefinition. Om du ändrar retrievable behöver du inte återskapa ett index.
2. Kör en upphöjd läsfråga som väljer UserIds och GroupIdsoch bekräftar att samlingarna inte är tomma. För segmenterade scenarier bekräftar du att varje segment bär båda fälten.
3. Återgå retrievable till false efter verifieringen.

Konfigurera stöd för SharePoint grupper

Från och med 2026-05-01-preview REST API kan SharePoint indexeraren mata in SharePoint webbplatsgruppmedlemskap (ägare, medlemmar, besökare och anpassade webbplatsgrupper). Den hedrar dessa grupper vid frågetillfället. ID:n för SharePoint-grupper anges i fältet metadata_group_ids med prefixet spg: för att skilja dem från objekt-ID:n för Microsoft Entra-grupper.

Den här genomgången är fristående: slutför stegen för att konfigurera indexet, indexeringsfältmappningar och fråga indexet med SharePoint platsgruppsframtvingande.

Följande komponenter samverkar för att möjliggöra matchning av SharePoint-webbplatsgrupper:

1. Förutsättningar

• SharePoint indexerare som redan har konfigurerats för ACL-inmatning. Se Konfigurera indexerarens fältmappningar för ACL:er.
• Microsoft Entra appregistrering med federerade identitetsautentiseringsuppgifter. Se Konfigurera det registrerade programmet med en hanterad identitet.
• REST API 2026-05-01-preview eller senare.

2. Konfigurera indexet

Lägg till konfigurationen sharePointConnectorAppRegistration och fältet SharePointSiteUrl tillsammans med behörighetsfilterfälten UserIds och GroupIds, så att hela indexstrukturen finns samlad på ett ställe. Behåll 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. Konfigurera indexerarens fältmappningar

Mappa de SharePoint metadatafälten till indexfälten i ett enda kombinerat mappningsblock. De två första mappningarna är samma som används för standard-ACL-inmatning. den tredje mappningen aktiverar SharePoint gruppmatchning.

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

Om din kompetensuppsättning delar upp dokument i segment (till exempel med Text Split-färdigheten för integrerad vektorisering) projicera du SharePointSiteUrl på varje segment via indexProjections.mappings i stället. Se Välj var du vill fylla I ACL-fält.

4. Fråga indexet

Ingen ändring på klientsidan krävs. Samma x-ms-query-source-authorization-token aktiverar både Microsoft Entra och SharePoint platsgruppstillämpning. Söktjänsten matchar upp SharePoint-gruppmedlemskap på serversidan med sharePointConnectorAppRegistration i indexet.

Information om begärans format finns i det allmänna frågeexemplet och det SharePoint-specifika exemplet med framtvingande av SharePoint-webbplatsgrupp.

5. Kontrollera

Bekräfta att SharePoint-grupp-ID:n har kommit in i indexet genom att köra en elevated-read-fråga med GroupIds och leta efter värden med prefixet spg: i svaret.

Synkronisera behörigheter mellan indexerat innehåll och källinnehåll

Från och med 2026-05-01-preview REST API identifieras och uppdateras ACL-ändringar för objekt med unika behörigheter på varje lyckad indexerarekörning. Indexeraren använder SharePoints ändringstoken för att fånga upp tillägg och borttagningar av rolltilldelningar inkrementellt, på samma sätt som den fångar upp innehållsändringar.

Vissa scenarier kräver fortfarande en explicit uppdatering:

Återställa specifika dokument

Du kan återställa specifika dokument för att helt mata in innehåll och ACL:er igen.

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

Synkronisera om ACL:er över hela datakällan

Du kan synkronisera om det fullständiga ACL-innehållet för datauppsättningen efter ursprunglig inläsning. För att åtgärden ska lyckas helt måste en indexerare köras efter slutförandet.

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

När du har indexerat dina data och ACL:er kan du fråga indexet.

Troubleshooting

Information om saknade, oväntade eller misslyckade frågetidsresultat efter att ACL-metadata har indexerats finns i Felsöka SharePoint behörighetsfiltrering.

Relaterat innehåll

• Indexera SharePoint innehåll i Azure AI-sökning (förhandsversion)
• Frågetids-ACL-tillämpning