Použití indexeru SharePoint k příjmu metadat oprávnění a filtrování výsledků hledání na základě uživatelských přístupových práv (Preview)

Přijímání metadat oprávnění ze SharePointu (Preview) využívá indexer ve službě Azure AI Vyhledávač k uchování metadat oprávnění, jako jsou seznamy řízení přístupu (ACL), spolu s dalším obsahem ze SharePointu v Microsoftu 365. Indexer ukládá oprávnění jako metadata pro každý indexovaný dokument. V době dotazu dostanou uživatelé jenom dokumenty, ke kterým mají oprávnění k přístupu.

Požadavky

• Azure AI Vyhledávač na fakturovatelné úrovni (Basic nebo vyšší) v libovolné oblasti.

• SharePoint v Microsoft 365 webech, knihovnách, složkách a souborech s nakonfigurovanými oprávněními.

• Dokončete všechny kroky konfigurace v dokumentaci k indexeru SharePoint a uplatněte požadavky specifické pro Seznam řízení přístupu (ACL), jak je popsáno v tomto článku.

• Nakonfigurujte Microsoft Entra oprávnění aplikace a přihlašovací údaje vhodné pro váš scénář. Viz scénář oprávnění podle seznamu ACL. Příjem ACL vyžaduje oprávnění aplikace. Delegovaná oprávnění se nepodporují. Informace o aplikaci a delegovaném rozhodnutí najdete v tématu Volba nastavení oprávnění.

• REST API verze 2026-08-01-preview nebo odpovídající balíček sady SDK ve verzi Preview.

Omezení

• Přírůstkové aktualizace seznamu ACL vyžadují rozhraní REST API verze 2026-05-01-Preview nebo novější. Ve starších verzích rozhraní API ve verzi Preview systém zaznamenává seznamy ACL pouze při prvním příjmu dat každé položky. Pozdější změny oprávnění vyžadují explicitní přeindexování. Postup migrace najdete v tématu Synchronizace oprávnění mezi indexovaným a zdrojovým obsahem.

• Změny oprávnění nadřazeného oboru se při následných spuštěních indexeru automaticky nevybízejí. Možnosti aktualizace najdete v tématu Synchronizace oprávnění mezi indexovaným a zdrojovým obsahem.

• Tuto funkci nepodporuje portál Azure.

• V této verzi Preview nejsou podporované následující funkce:

  • SharePoint zásady správy informací použitelné pro přístup uživatelů. Systém tyto zásady během zpracování dotazu nevyhodnocuje, nepřijímá ani neuplatňuje.

  • Sdíletelné odkazy s vymezeným oborem "Kdokoli" nebo "Lidé ve vaší organizaci". Podporují se jenom odkazy omezené na konkrétní osoby.

  • Skupiny SharePointu (například skupiny Vlastníci, Členové a Návštěvníci) jsou podporovány od verze 2026-05-01-preview rozhraní REST API. Viz Konfigurace podpory skupin SharePointu. Ve starších verzích rozhraní API ve verzi Preview se podporují jenom skupiny SharePoint, které se překládají na skupiny Microsoft Entra.

• Následující funkce indexeru nepodporují dědičnost oprávnění v indexovaných dokumentech pocházejících z SharePoint. Pokud některou z těchto funkcí použijete v sadě dovedností nebo indexeru, nebudou oprávnění na úrovni dokumentu zahrnuta do indexovaného obsahu.

  • Vlastní funkce webového API

  • Úložiště znalostí, včetně úložiště prostředků vyžadovaného pro poskytování obrázků (preview) v agentním vyhledávání. Proto se pro zdroje znalostí, které přebírají seznamy řízení přístupu (ACL) ze SharePointu, nepodporuje poskytování obrázků.

  • Mezipaměť rozšiřování indexeru

  • Ladicí relace

Podpora modelu oprávnění SharePoint

Tato verze Preview podporuje základní seznamy ACL pro dokumenty, položky seznamu a moderní stránky webu ASPX.

Podporované vztahy mezi skupinami

Tranzitivita skupin Microsoft Entra platí v rámci Microsoft Entra. Nerozbaluje Microsoft Entra skupiny, které jsou členy SharePoint skupin.

Jak se vyhodnocují hierarchická oprávnění

SharePoint oprávnění dědí hierarchii webu → knihovny → složky → souboru, pokud není přerušena dědičnost.

Během příjmu dat indexer shromažďuje identifikátory uživatelů a skupin na každé úrovni a vypočítá efektivní seznam ACL pro každý soubor.

Oprávnění podle scénáře ACL

Oprávnění aplikace Microsoft Entra a typ přihlašovacích údajů vyžadovaný pro příjem dat seznamu ACL závisí na tom, které typy položek a typy skupin indexujete. V registraci aplikace se všechna oprávnění přidají v rámci oprávnění> rozhraní APIPřidat oprávnění a federované přihlašovací údaje se přidají do certifikátů a tajných>kódů federovaných přihlašovacích údajů. Podrobné pokyny a snímky obrazovky najdete v tématu Step 3: Vytvoření registrace Microsoft Entra aplikace a Konfigurování registrované aplikace se spravovanou identitou.

Federované přihlašovací údaje ověřují aplikaci pomocí důvěryhodné spravované identity místo tajného klíče klienta. Stejné federované přihlašovací údaje pokrývají příjem dat (indexer) i vyhodnocení doby dotazování SharePoint skupin webů. Postup nastavení najdete v tématu Konfigurace registrované aplikace se spravovanou identitou.

Než povolíte načítání seznamů ACL

Pro zaregistrovanou aplikaci Microsoft Entra proveďte tyto kroky:

1. V předchozí tabulce určete odpovídající scénář podle toho, co plánujete indexovat (soubory v knihovně dokumentů, položky seznamu, stránky webu ASPX) a zda je nutné respektovat skupiny webu služby SharePoint.
2. Otevřete registraci aplikace v Centrum pro správu Microsoft Entra a přejděte na oprávnění API>Přidat oprávnění.
3. Přidejte oprávnění Microsoft Graph uvedená pro váš scénář. Udělení souhlasu správce
4. Pokud váš scénář také vyžaduje oprávnění SharePoint, vyberte Přidat oprávnění znovu, zvolte rozhraní API SharePoint a přidejte Sites.FullControl.All (nebo Sites.Selected). Udělení souhlasu správce
5. Konfigurace přihlašovacích údajů:
   • Pro scénáře pouze pro Microsoft Graph můžete použít buď tajný klíč klienta (Certificates & secrets>Tajné kódy klienta) nebo federovaný přihlašovací údaj.
   • Pro jakýkoli scénář, který zahrnuje oprávnění SharePoint, přidejte federované přihlašovací údaje do Certificates & secretsFederated credentials. Viz Konfigurace registrované aplikace se spravovanou identitou.
6. Udělte aplikaci přístup k cílovým webům SharePoint (zvlášť důležité, pokud pro přístup s vymezeným oborem používáte Sites.Selected), aby mohl číst obsah a oprávnění, která chcete indexovat.

Vyhledání správných identifikátorů Microsoft Entra

Každý identifikátor se na portálu Azure zobrazuje na jiném místě a odpovídá konkrétnímu konfiguračnímu poli. Tuto část použijte jako referenční materiál při konfiguraci ingestace SharePoint ACL s federovaným přihlašovacím údajem. Na tyto identifikátory se odkazuje v Konfiguraci podpory skupin SharePointu a v připojovacím řetězci zdroje dat.

ID federované aplikace přihlašovacích údajů

Pro FederatedCredentialApplicationId v připojovacím řetězci zdroje dat a federatedCredentialId v definici indexu použijte vlastní ID aplikace (klienta) spravované identity, nikoli ID ingestní aplikace.

Spravovaná identita přiřazená systémem:

1. Přejděte do služby Azure AI Vyhledávač.
2. Vyberte Zabezpečení a síťová>identita.
3. Na kartě Přiřazeno systémem si poznamenejte ID objektu (instančního objektu).
4. Přejděte do Microsoft Entra ID>Spravovat>Podnikové aplikace.
5. Vyhledejte název vyhledávací služby nebo vložte ID objektu (instančního objektu) do vyhledávacího pole.
6. Vyberte výsledek a otevřete vlastnosti. Zkopírujte ZDE uvedené ID aplikace , což je hodnota ve FederatedCredentialApplicationId zdroji dat a federatedCredentialId v indexu.

Spravovaná identita přiřazená uživatelem:

1. Přejděte k prostředku spravované identity přiřazené uživatelem.
2. Vyberte Nastavení>Vlastnosti.
3. Zkopírujte ID klienta, což je hodnota ve FederatedCredentialApplicationId zdroji dat a federatedCredentialId v indexu.

Konfigurace vyhledávací služby pro příjem ACL a vynucení doby dotazu

Tyto kroky nakonfigurují zpracování seznamu ACL pro vyhledávací službu a povolí respektování seznamu ACL během dotazování.

Vyberte, kde se mají vyplnit pole ACL

To, kam namapujete pole metadat ACL, závisí na tom, zda indexer zapisuje jeden dokument pro každou zdrojovou položku, nebo více částí pro každou zdrojovou položku.

Ve všech scénářích s dělením na bloky musí každý blok obsahovat pole ACL. Filtry přístupových oprávnění se uplatňují na každý dokument, takže blok, kterému chybějí pole ACL, nelze vrátit správnému volajícímu.

1. Konfigurace zdroje dat

Tato část rozšiřuje základní postup Krok 4: Vytvoření zdroje dat. Nastavte indexerPermissionOptions v definici zdroje dat , aby bylo možné indexovat userIds a groupIds z dokumentů SharePoint.

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

2. Přidání polí oprávnění do definice indexu

Přidejte do definice schématu indexu pole pro ukládání seznamů ACL a podporu filtrování času dotazu.

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

Nastavte atribut retrievable na true pouze během vývoje pro ověření hodnot. Můžete změnit načítání z true na false bez požadavku na opětovné sestavení indexu.

3. Konfigurace projekcí indexu v sadě dovedností (pokud je k dispozici)

Při povolení bloků dat není nadřazený dokument zapsán do indexu, pokud projectionMode je skipIndexingParentDocuments. Přenášejte metadata ACL do každého bloku prostřednictvím indexProjections.selectors[].mappings.

Pokud váš indexer používá sadu dovedností s blokem dat, jako je například dovednost Rozdělení textu při povolování integrované vektorizace, nezapomeňte vlastnosti seznamu ACL namapovat na každý blok dat pomocí projekce indexu. Řádky // v následujícím příkladu jsou ilustrativní anotace a nejsou platné JSON. Před odesláním žádosti je odeberte.

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

Mapování UserIds, GroupIds a SharePointSiteUrl načítá metadata na úrovni zdroje generované indexerem SharePoint (/document/metadata_*) a zapisují hodnoty do jednotlivých bloků dat.

4. Nakonfigurujte mapování polí indexeru pro řízení přístupu (ACL)

Použijte mapování polí indexeru, když indexer zapisuje jeden dokument pro každou zdrojovou položku (bez dělení na bloky) nebo když udržujete samostatný rodičovský index vedle indexu bloků. Pokud vaše sada dovedností rozdělí dokumenty do jednoho cílového indexu pomocí projectionMode: skipIndexingParentDocuments, mapování polí zde zobrazená jsou nahrazena mapováními indexProjections.mappings z předchozího kroku pro index fragmentů.

Kromě požadované konfigurace indexeru namapujte nezpracovaná pole ACL metadat ze SharePointu na vaše pole indexu.

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

5. Spusťte indexer.

Metadata ACL se načítají při běhu indexeru. Po vytvoření nebo aktualizaci indexeru (viz krok 6: Vytvoření indexeru) aktivujte spuštění, aby indexer ingestoval seznamy ACL společně s obsahem.

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

Pokud jste u existujícího indexeru, který už zaindexoval položky, povolili ingestaci ACL, zavolejte /resync s options: ["permissions"], aby se pro tyto položky doplnily seznamy ACL, nebo znovu extrahujte konkrétní položky pomocí /resetdocs.

6. Ověření příjmu seznamu ACL

Chcete-li ověřit, že hodnoty ACL byly správně vyplněny:

1. Dočasně nastavte retrievable na true u UserIds a GroupIds ve vaší definici indexu. Změna retrievable nevyžaduje opětovné sestavení indexu.
2. Spusťte dotaz se zvýšenými oprávněními pro čtení, který vybere UserIds a GroupIds, a ověřte, že kolekce nejsou prázdné. U segmentovaných scénářů ověřte, že každý blok obsahuje obě pole.
3. Vrátit retrievable zpět na false po ověření.

Konfigurace podpory skupin SharePoint

Počínaje verzí REST API 2026-05-01-preview může indexer SharePointu indexovat členství ve skupinách webu SharePoint (vlastníci, členové, návštěvníci a vlastní skupiny webu). Tyto skupiny zohledňuje při dotazování. ID skupin SharePointu se v poli metadata_group_ids uvádějí s předponou spg:, aby se odlišila od ID objektů skupin Microsoft Entra.

Tento návod je samostatný: proveďte kroky pro konfiguraci indexu, mapování polí indexeru a dotazování indexu pomocí vynucení skupiny webů SharePoint.

Následující komponenty spolupracují a umožňují SharePoint řešení skupin webů:

1. Požadavky

• SharePoint indexer už je nakonfigurovaný pro příjem ACL. Viz Konfigurace mapování polí indexeru pro ACL.
• Registrace aplikace Microsoft Entra s přihlašovacími údaji federované identity. Viz Konfigurace registrované aplikace se spravovanou identitou.
• REST API 2026-05-01-preview nebo novější.

2. Konfigurace indexu

Přidejte konfiguraci sharePointConnectorAppRegistration a pole SharePointSiteUrl vedle polí filtru oprávnění UserIds a GroupIds, aby byla úplná struktura indexu na jednom místě. Zachovat 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. Konfigurace mapování polí indexeru

Namapujte pole metadat SharePoint na pole indexu v jednom kombinovaném bloku mapování. První dvě mapování jsou stejná jako pro standardní příjem seznamů ACL; třetí mapování aktivuje SharePoint řešení skupin.

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

Pokud vaše sada dovedností rozděluje dokumenty na bloky (například pomocí dovednosti Text Split pro integrovanou vektorizaci), promítejte místo toho SharePointSiteUrl do každého bloku pomocí indexProjections.mappings. Viz Výběr umístění pro vyplnění polí ACL.

4. Dotazování indexu

Nevyžaduje se žádná změna na straně klienta. Stejný token x-ms-query-source-authorization aktivuje vynucení skupiny webů Microsoft Entra i SharePoint. Vyhledávací služba vyhodnocuje členství ve skupinách SharePointu na straně serveru pomocí sharePointConnectorAppRegistration v indexu.

Strukturu požadavku najdete v obecném příkladu dotazu a v příkladu specifickém pro SharePoint s vynucením skupiny webů SharePoint.

5. Ověření

Chcete-li ověřit, že se ID skupin SharePointu dostala do indexu, spusťte dotaz se zvýšenými oprávněními ke čtení, ve kterém vyberete GroupIds, a v odpovědi hledejte hodnoty s předponou spg:.

Synchronizace oprávnění mezi indexovaným a zdrojovým obsahem

Počínaje rozhraním REST API verze 2026-05-01-Preview se zjistí a aktualizují změny seznamu ACL pro položky s jedinečnými oprávněními při každém úspěšném spuštění indexeru. Indexer používá tokeny změn SharePointu k inkrementálnímu zachycování přidání a odebrání přiřazení rolí, stejným způsobem, jakým zachycuje změny obsahu.

Některé scénáře stále vyžadují explicitní aktualizaci:

Resetování konkrétních dokumentů

Konkrétní dokumenty můžete resetovat, aby se obsah a ACL znovu plně ingestovaly.

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

Resynchronizace seznamů ACL v celém zdroji dat

Po počátečním příjmu dat můžete obsah seznamu ACL úplné sady dat znovu synchronizovat . K úplnému úspěchu vyžaduje tato operace spuštění indexeru po dokončení.

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

Po indexování vašich dat a seznamů řízení přístupu můžete provádět dotazy na index.

Řešení problémů

Informace o chybějících, neočekávaných nebo neúspěšných výsledcích dotazu po indexování metadat seznamu ACL najdete v tématu Řešení potíží s filtrováním oprávnění SharePoint.

Související obsah

• Indexovat obsah SharePoint v Azure AI Vyhledávač (Preview)
• Vynucení ACL v době vykonání dotazu