Używanie indeksatora programu SharePoint do pozyskiwania metadanych uprawnień i filtrowania wyników wyszukiwania na podstawie praw dostępu użytkowników

Uwaga

Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.

Pozyskiwanie metadanych uprawnień SharePoint używa indeksatora Foundry IQ (Wyszukiwanie AI platformy Azure) do przechowywania obsługiwanych list kontroli dostępu (ACL) wraz z indeksowaną zawartością z SharePoint. Filtry uprawnień stosowane podczas wykonywania zapytania uwzględniają te zaindeksowane metadane oraz tożsamość użytkownika wykonującego zapytanie. Zmiany uprawnień w źródle trafiają do indeksu dzięki synchronizacji uprawnień, a nie poprzez zapytania.

Diagram przedstawiający zawartość SharePoint i pozyskiwanie ACL w usłudze Foundry IQ, a następnie pobieranie filtrowane uprawnieniami.

Ważne

Filtrowanie uprawnień indeksowanych nie jest oceną w czasie rzeczywistym pełnego modelu dostępu do SharePoint i zasad. Aby poznać alternatywy pobierania w czasie żądania i pozyskiwania zarządzanego przez klienta po stronie źródłowej, zobacz Wybieranie podejścia do pobierania pod kątem aktualności.

Wymagania wstępne

  • Foundry IQ w planie płatnym (Podstawowy lub wyższy) w dowolnym regionie.

  • SharePoint w witrynach Microsoft 365, bibliotekach, folderach i plikach ze skonfigurowanymi uprawnieniami.

  • Wykonaj wszystkie kroki konfiguracji w dokumentacji indeksatora SharePoint, stosując wszystkie wymagania specyficzne dla ACL opisane w tym artykule.

  • Skonfiguruj Microsoft Entra uprawnienia aplikacji i poświadczenia odpowiednie dla danego scenariusza. Zobacz Scenariusz uprawnień według listy ACL. Importowanie ACL wymaga uprawnień aplikacji. Delegowane uprawnienia nie są obsługiwane. Informacje na temat wyboru między uprawnieniami aplikacji a uprawnieniami delegowanymi znajdziesz w artykule Wybierz konfigurację uprawnień.

  • Interfejs API REST płaszczyzny danych 2026-10-01 dla ogólnie dostępnej konfiguracji uprawnień SharePoint opisanej w tym artykule.

Uwaga

Ponowna synchronizacja uprawnień jest ogólnie dostępna za pomocą interfejsu API 2026-10-01REST. Reset-docs pozostaje w wersji zapoznawczej i używa interfejsu API REST 2026-11-01-preview.

Ograniczenia

  • Użyj standardowego lub domyślnego analizowania dokumentów (parameters.configuration.parsingMode: "default") albo wyodrębniania opartego na usłudze Content Understanding, jeśli jest ono obsługiwane. Każdy wygenerowany fragment musi zachować wymagane metadane uprawnień i kontekst źródłowy. System nie obsługuje wyspecjalizowanych trybów analizowania wybranych przez klienta. Aby uzyskać informacje o trybach wykluczonych i ustawieniach źródła wiedzy, zobacz Obsługiwane parsowanie i wyodrębnianie zawartości na potrzeby pozyskiwania uprawnień.

  • Dzierżawcy z włączoną usługą Dostęp warunkowy usługi Microsoft Entra nie są obsługiwani. Ograniczenia indeksatora SharePoint mają również zastosowanie do pozyskiwania ACL.

  • Aktualizacje uprawnień zależą od powiadomień o zmianach w źródle i pomyślnego przetworzenia przez indeksator. Obsługiwane zmiany folderu biblioteki dokumentów innych niż główny mogą odświeżać niezmienione elementy podrzędne podczas zwykłego przetwarzania przyrostowego. Aby uzyskać informacje o zakresie i opcjach odświeżania, zobacz Synchronizowanie uprawnień między indeksowaną i źródłową zawartością.

  • Portal Azure nie obsługuje tej funkcji.

  • Następujące funkcje nie są obsługiwane:

    • SharePoint zasady zarządzania informacjami dotyczące dostępu użytkowników. Ten system nie ocenia, nie wczytuje ani nie uwzględnia tych zasad podczas wykonywania zapytań.

    • Linki do udostępniania o zakresie „Każdy” lub „Osoby w organizacji” oraz wymuszanie wygaśnięcia linków do udostępniania. Używaj obsługiwanych jawnych przypisań użytkowników lub grup, w tym obsługiwanych przypisań dziedziczych. Wygaśnięcie linku udostępniania nie powoduje odwołania oddzielnego jawnie nadanego uprawnienia.

  • Członkostwo w grupach zagnieżdżonych obsługuje maksymalnie pięć poziomów. W przypadku, gdy więcej niż 10 000 mających zastosowanie Microsoft Entra podmiotów zabezpieczeń grupy wymaga rozwiązywania zagnieżdżeń, obowiązuje oddzielny limit na poziomie lokacji. Zobacz Obsługiwane relacje między grupami.

  • Następujące funkcje nie są obsługiwane w przypadku pozyskiwania ACL SharePoint:

  • Wzbogacanie ukończenia czatu ma ograniczenia dotyczące punktów końcowych i uprawnień, gdy włączone jest pozyskiwanie listy ACL SharePoint.

Obsługa modelu uprawnień SharePoint

Pozyskiwanie uprawnień obsługuje następujący podzestaw modelu uprawnień SharePoint dla dokumentów, elementów listy i nowoczesnych stron witryny ASPX.

funkcja SharePoint Opis Wspierane Notatki
Dziedziczenie witryny, biblioteki, listy i strony Witryna → biblioteka/lista → folder → plik/element/strona. ✔️ Oceniane podczas importu; efektywne listy ACL są obliczane dla każdego elementu.
Unikatowe uprawnienia ACL folderu, pliku, elementu listy i strony Dostęp na poziomie elementu. ✔️ Uwzględniane podczas pierwszego zaimportowania oraz kolejnych uruchomień wykrywających zmiany na liście ACL dla elementów z unikatowymi uprawnieniami.
Elementy listy SharePoint Uprawnienia do elementów listy (allSiteLists i allSiteContent kontenerów). ✔️ Wymaga uprawnień wymienionych w scenariuszu Uprawnienia według listy ACL.
Strony witryny ASPX Uprawnienia na nowoczesnych stronach witryny (w kontenerach allSitePages i allSiteContent). ✔️ Wymaga uprawnień wymienionych w scenariuszu Uprawnienia według scenariusza ACL.
grupy Microsoft Entra (Microsoft 365 i zabezpieczenia) Dostęp oparty na grupach. ✔️ Identyfikatory grup są uwzględniane, jeśli można je przypisać do identyfikatora Microsoft Entra (ID).
SharePoint grup witryn Właściciele/Członkowie/Odwiedzający i niestandardowe grupy witryn. ✔️ Wymaga konfiguracji grup SharePoint. Identyfikatory grup są emitowane z prefiksem spg: .
Linki udostępniane dla "Dla każdego" lub "Osoby w Twojej organizacji" Dostęp w całej organizacji lub publiczny. ❌ Zamiast tego użyj obsługiwanych jawnych przypisań użytkowników/grup.
Wymuszanie wygaśnięcia łącza udostępniania Dostęp zmienia się w zależności od wygaśnięcia linku. ❌ Ponowne synchronizowanie uprawnień nie włącza tej nieobsługiwanej możliwości.
Użytkownicy zewnętrzni/goście Dostęp dla gości. ❌ Nie jest obsługiwane.
Zasady zarządzania informacjami Zasady definiujące określone wymagania dotyczące uprawnień. ❌ Nie jest obsługiwane.
Etykiety poufności Purview Zabezpieczenia na poziomie dokumentu dotyczące prywatności, kategoryzacji, uprawnień i szyfrowania ❌ Obsługiwane za pomocą oddzielnej funkcji: zachowywanie i honorowanie etykiet poufności.

Obsługiwane relacje grup

Obsługiwane rozpoznawanie grup obejmuje grupy Microsoft Entra zagnieżdżone w grupach witryn SharePoint, do pięciu zagnieżdżonych poziomów grup.

Relacja uprawnień Wspierane Wskazówki
Użytkownik lub grupa Microsoft Entra przypisana bezpośrednio do elementu SharePoint Yes Indeksator przechowuje identyfikator obiektu użytkownika lub grupy Microsoft Entra w metadanych uprawnień elementu.
Użytkownik osiąga przypisaną grupę Microsoft Entra za pomocą zagnieżdżonych grup Microsoft Entra Tak, do pięciu poziomów Członkostwo wykraczające poza obsługiwaną głębokość nie udziela dostępu za pośrednictwem tej ścieżki.
Użytkownik przypisany bezpośrednio do grupy witryn SharePoint, która ma dostęp do elementu Yes Konfigurowanie obsługi grup SharePoint.
grupa Microsoft Entra zagnieżdżona w grupie SharePoint Tak, do pięciu poziomów Konfigurowanie obsługi grup SharePoint. Poniższy limit podmiotu zabezpieczeń na poziomie witryny ma również zastosowanie.
Ścieżka członkostwa wymagająca zagnieżdżenia grup na więcej niż pięciu poziomach No Jeśli jest to jedyna ścieżka uprawnień użytkownika, odmówiono dostępu. Oddzielne obsługiwane bezpośrednie lub mieszczące się w limicie przyznanie może nadal udzielać dostępu.

Rozważmy na przykład grupa programu SharePoint, która ma dostęp do elementu. Grupa Entra G1 jest członkiem grupy grupa programu SharePoint; G2 jest członkiem G1, kontynuując przez G6. Użytkownik, który jest bezpośrednim członkiem G1, G2, G3, G4 lub G5, może otrzymać dostęp za pośrednictwem odpowiedniej ścieżki jeden do pięciu poziomów. Członkostwo tylko w G6 nie udziela dostępu za pośrednictwem tego łańcucha. Oddzielne bezpośrednie przypisanie użytkownikowi jest oceniane niezależnie.

Jeśli lokacja ma więcej niż 10 000 mających zastosowanie jednostek głównych grup Microsoft Entra na potrzeby rozwiązywania zagnieżdżeń, te zagnieżdżone członkostwa nie są rozwiązywane. Oddzielne obsługiwane przyznania uprawnień, takie jak bezpośrednie przypisania użytkowników lub bezpośrednie członkostwo w grupa programu SharePoint, mogą nadal mieć zastosowanie. Ten próg liczy odpowiednie podmioty zabezpieczeń witryny Entra, a nie grupy użytkownika, grupy SharePoint, indeksowane witryny lub głębokość zagnieżdżania. Dokładnie 10 000 nie jest wykluczone tylko przez ten próg. W przypadku brakujących wyników zobacz Rozwiązywanie problemów z filtrowaniem uprawnień SharePoint.

Jak oceniane są uprawnienia hierarchiczne

Uprawnienia w SharePoint są dziedziczone w hierarchii: witryna → biblioteka lub lista → folder → plik, element lub strona, chyba że dziedziczenie zostanie przerwane.

Podczas pozyskiwania indeksator zbiera identyfikatory użytkowników i grup oraz oblicza wynikowe uprawnienia ACL dla każdego elementu.

Uprawnienia w scenariuszu ACL

Uprawnienia aplikacji Microsoft Entra oraz typ poświadczeń wymagane do pozyskiwania danych ACL zależą od tego, jakie typy elementów i grup indeksujesz. W rejestracji aplikacji wszystkie uprawnienia są dodawane w obszarze Uprawnienia >Dodaj uprawnienie, a poświadczenia federacyjne są dodawane w obszarze Certyfikaty i wpisy tajne>Poświadczenia federacyjne. Aby uzyskać instrukcje krok po kroku i zrzuty ekranu, zobacz Krok 3: Tworzenie rejestracji aplikacji Microsoft Entra i Konfigurowanie zarejestrowanej aplikacji przy użyciu tożsamości zarządzanej.

Scenario Uprawnienia interfejsu API umożliwiające dodawanie Credential
Listy ACL plików w bibliotekach dokumentów, gdy dostęp jest przyznawany tylko za pośrednictwem użytkowników Microsoft Entra i grup standardowych (grup zabezpieczeń Microsoft Entra, grup Microsoft 365, grup zabezpieczeń obsługujących pocztę) Microsoft Graph: Files.Read.All, Sites.FullControl.All (lub Sites.Selected dla dostępu o ograniczonym zakresie) Klucz tajny klienta lub poświadczenie federacyjne
Listy kontroli dostępu (ACL) dla plików w bibliotekach dokumentów, gdy grupy witryn programu SharePoint (Właściciele, Członkowie, Odwiedzający lub niestandardowe grupy witryn) również muszą być uwzględniane Microsoft Graph: Files.Read.All, Sites.FullControl.All (lub Sites.Selected)
SharePoint: Sites.FullControl.All (lub Sites.Selected)
Poświadczenie federacyjne (wymagane)
Listy ACL w elementach listy SharePoint Microsoft Graph: Files.Read.All, Sites.FullControl.All (lub Sites.Selected), User.Read.All
SharePoint: Sites.FullControl.All (lub Sites.Selected)
Poświadczenie federacyjne (wymagane)
Zawartość i listy ACL na stronach witryny ASPX Microsoft Graph: Sites.FullControl.All (lub Sites.Selected) User.Read.All (zachowaj z Files.Read.All powyższych wierszy, jeśli indeksujesz również biblioteki lub listy dokumentów)
SharePoint: Sites.FullControl.All (lub Sites.Selected)
Poświadczenie federacyjne (wymagane)
Ustalanie grup witryny SharePoint w czasie wykonywania zapytania za pośrednictwem sharePointConnectorAppRegistration Dodaj SharePoint: User.Read.All do tej samej rejestracji aplikacji używanej przez indeksator Poświadczenie federacyjne (wymagane)

Uwaga

  • Po dodaniu uprawnienia można wybrać między dwoma powierzchniami interfejsu API: Microsoft Graph i SharePoint. Oba uwidaczniają podobnie nazwane uprawnienia. Na przykład Sites.FullControl.All istnieje w obu tych przypadkach. Dodaj każde uprawnienie w ramach powierzchni interfejsu API wskazanej w tabeli.

  • Użyj poświadczenia federacyjnego zawsze, gdy scenariusz dodaje uprawnienia interfejsu API programu SharePoint. Klucze tajne klienta działają tylko w przypadku wiersza biblioteki dokumentów przeznaczonego wyłącznie dla usługi Microsoft Graph.

  • User.Read.Alljest wymagany w przypadku elementów listy i stron witryny ASPX, ponieważ indeksator odczytuje te uprawnienia za pośrednictwem interfejsu API REST SharePoint, który zwraca tylko adres e-mail użytkownika. Następnie indeksator wywołuje Microsoft Graph, aby przyporządkować każdy adres e-mail do identyfikatora obiektu Microsoft Entra, a to wyszukiwanie wymaga User.Read.All.

  • Jeśli używasz Sites.Selected, przed indeksowaniem przyznaj aplikacji jawny dostęp do każdej witryny docelowej SharePoint.

Poświadczenie federacyjne uwierzytelnia aplikację przy użyciu zaufanej tożsamości zarządzanej zamiast klucza tajnego klienta. To samo poświadczenie federacyjne obejmuje zarówno pobieranie danych (indeksator), jak i ocenę grup witryn programu SharePoint w czasie wykonywania zapytania. Aby uzyskać instrukcje konfiguracji, zobacz Konfigurowanie zarejestrowanej aplikacji przy użyciu tożsamości zarządzanej.

Przed włączeniem importowania list ACL

Wykonaj następujące kroki w zarejestrowanej aplikacji Microsoft Entra:

  1. Zidentyfikuj swój scenariusz w poprzedniej tabeli na podstawie tego, co planujesz indeksować (pliki bibliotek dokumentów, elementy listy, strony witryny ASPX) oraz tego, czy grupy witryn programu SharePoint muszą być uwzględniane.
  2. Otwórz rejestrację aplikacji w centrum administracyjne Microsoft Entra i przejdź do pozycji API permissions>Dodaj uprawnienie.
  3. Dodaj uprawnienia Microsoft Graph wymienione dla danego scenariusza. Udziel zgody administratora.
  4. Jeśli twój scenariusz wymaga również uprawnień programu SharePoint, ponownie wybierz pozycję Dodaj uprawnienie, wybierz interfejs API SharePoint i dodaj Sites.FullControl.All (lub Sites.Selected). Udziel zgody administratora.
  5. Skonfiguruj poświadczenia:
    • W przypadku scenariuszy korzystających wyłącznie z Microsoft Graph można użyć klucza tajnego klienta (Certificates & secrets>Client secrets) lub poświadczenia federacyjnego.
    • W przypadku każdego scenariusza obejmującego uprawnienia SharePoint dodaj poświadczenie federacyjne pod Certificates & secrets>Federated credentials. Zobacz Konfigurowanie zarejestrowanej aplikacji przy użyciu tożsamości zarządzanej.
  6. Przyznaj aplikacji dostęp do docelowych witryn SharePoint (co jest szczególnie ważne w przypadku dostępu o określonym zakresie przy użyciu Sites.Selected), aby mogła odczytywać treści i uprawnienia, które chcesz zindeksować.

Znajdowanie prawidłowych identyfikatorów Microsoft Entra

Każdy identyfikator występuje w innym miejscu w portalu Azure i odpowiada określonemu polu konfiguracji. Użyj tej sekcji jako punktu odniesienia podczas konfigurowania pozyskiwania uprawnień ACL w SharePoint przy użyciu poświadczenia federacyjnego. Do tych identyfikatorów odwołano się w sekcji Konfigurowanie obsługi grup SharePoint oraz w parametrach połączenia źródła danych.

Identyfikator Lokalizacja portalu Stosowane tam, gdzie Notatki
Identyfikator aplikacji pozyskiwania (klienta) Rejestracje aplikacji><your-app>>Przegląd ApplicationIdw parametrach parametry połączenia źródła danych; applicationId w sharePointConnectorAppRegistration Ten identyfikator jest poprawny dla większości pól konfiguracji. Nazywany również "identyfikatorem klienta".
Identyfikator obiektu aplikacji Rejestracje aplikacji><your-app>>Overview (poniżej identyfikatora aplikacji (klienta)) Nieużywane w konfiguracji Foundry IQ Nie należy mylić tego z identyfikatorem aplikacji (klienta). Zostanie on wyświetlony w tym samym bloku bezpośrednio poniżej identyfikatora klienta.
Identyfikator obiektu jednostki usługi Microsoft Entra ID>Aplikacje dla przedsiębiorstw><your-app>>Zarządzaj>Właściwości Nieużywane w konfiguracji Foundry IQ To jest reprezentacja aplikacji w postaci jednostki usługi. To inny identyfikator GUID niż identyfikator obiektu rejestracji aplikacji.
Identyfikator podmiotu zabezpieczeń tożsamości zarządzanej zasób tożsamości zarządzanej > lub panel Tożsamość usługi IQ rozwiązania Foundry Nie jest używane bezpośrednio w konfiguracji źródła danych lub indeksu usługi Foundry IQ Używane wewnętrznie podczas konfigurowania poświadczenia tożsamości federacyjnej w ramach rejestracji aplikacji. Utworzone poświadczenie uwierzytelniające darzy tę tożsamość zaufaniem.
ID obiektu federacyjnego poświadczenia Rejestracje aplikacji><your-app>>Zarządzaj>certyfikatami i wpisami tajnymi>Poświadczenia federacyjne><credential-name> Nieużywane w konfiguracji Foundry IQ Nie używaj identyfikatora GUID wpisu poświadczenia federacyjnej tożsamości dla elementu federatedCredentialId.
Identyfikator aplikacji poświadczeń federacyjnych Przypisane przez system: Microsoft Entra ID>Aplikacje dla przedsiębiorstw><search-service>>; Przypisane przez użytkownika: <managed-identity-resource>>Właściwości FederatedCredentialApplicationIdw parametry połączenia; federatedCredentialId w sharePointConnectorAppRegistration Zobacz Identyfikator aplikacji poświadczeń federacyjnych , aby wyszukać tożsamość zarządzaną.

Identyfikator aplikacji poświadczeń federacyjnych

W przypadku FederatedCredentialApplicationId w parametrach połączenia ze źródłem danych oraz federatedCredentialId w definicji indeksu użyj własnego identyfikatora aplikacji (klienta) tożsamości zarządzanej, a nie identyfikatora aplikacji pozyskiwania danych.

Tożsamość zarządzana przypisana przez system:

  1. Przejdź do usługi Foundry IQ.
  2. Wybierz pozycję Zabezpieczenia i tożsamość sieciowa>.
  3. Na karcie Przypisane przez system zanotuj identyfikator obiektu (podmiotu zabezpieczeń).
  4. Przejdź do Microsoft Entra ID>Zarządzaj>Aplikacje dla przedsiębiorstw.
  5. Wyszukaj nazwę usługi Foundry IQ lub wklej identyfikator obiektu (podmiotu zabezpieczeń) w polu wyszukiwania.
  6. Wybierz wynik i otwórz pozycję Właściwości. Skopiuj pokazany tutaj identyfikator aplikacji , który jest wartością FederatedCredentialApplicationId w źródle danych i federatedCredentialId w indeksie.

Tożsamość zarządzana przypisana przez użytkownika:

  1. Przejdź do zasobu tożsamości zarządzanej przypisanej przez użytkownika.
  2. Wybierz pozycję Ustawienia>Właściwości.
  3. Skopiuj identyfikator klienta, który jest wartością FederatedCredentialApplicationId w źródle danych i federatedCredentialId w indeksie.

Konfigurowanie usługi Foundry IQ na potrzeby pozyskiwania list ACL i egzekwowania podczas wykonywania zapytania

Te kroki umożliwiają skonfigurowanie usługi Foundry IQ na potrzeby pozyskiwania ACL i włączenia uwzględniania ACL w czasie wykonywania zapytań.

Wybierz, gdzie wypełnić pola ACL

To, gdzie mapujesz pola metadanych ACL, zależy od tego, czy indeksator zapisuje jeden dokument dla każdego elementu źródłowego, czy wiele fragmentów dla każdego elementu źródłowego.

Scenario Wypełnij pola ACL za pomocą Dlaczego
Brak zestawu umiejętności lub zestaw umiejętności bez dzielenia na fragmenty; jeden dokument wyszukiwania dla każdego elementu źródłowego Mapowania pól indeksatora tylko (metadata_user_ids → UserIds, metadata_group_ids → GroupIds i dla grup SharePoint metadata_spo_site_url → SharePointSiteUrl). Indeksator zapisuje pojedynczy dokument w indeksie docelowym, a mapowania pól przenoszą metadane źródłowe do pól indeksu.
Zestaw umiejętności z fragmentowaniem (na przykład umiejętność dzielenia tekstu na potrzeby zintegrowanej wektoryzacji), pojedynczy indeks z polami nadrzędnymi powtarzanymi w każdym fragmentze (projectionMode: skipIndexingParentDocuments) Projekcje indeksu w zestawie umiejętności (mappings z /document/metadata_user_ids, /document/metadata_group_ids i dla grup SharePoint /document/metadata_spo_site_url). Dokument nadrzędny nie jest indeksowany; są tylko fragmenty. Wartości listy ACL muszą być rzutowane na każdy fragment, aby filtry czasu kwerendy miały zastosowanie do fragmentu zwróconego w wynikach. Mapowania pól indeksatora dla tych pól są pomijane w tym trybie.
Zestaw umiejętności z dzieleniem na fragmenty, wzorzec z dwoma indeksami (indeks nadrzędny + indeks fragmentu podrzędnego) Oba: mapowania pól indeksatora wypełniają pola listy ACL w indeksie nadrzędnym, projekcje indeksów wypełniają pola listy ACL w indeksie fragmentów podrzędnych. Oba indeksy można przeszukiwać za pomocą zapytań, a każdy z nich wymaga metadanych, według których filtruje.

We wszystkich scenariuszach z podziałem na fragmenty każdy fragment musi zawierać pola ACL. Filtry uprawnień obowiązują dla każdego dokumentu, więc fragment bez pól ACL nie może zostać zwrócony właściwemu wywołującemu.

1. Konfiguracja źródła danych

Dodaj indexerPermissionOptions do podstawowej konfiguracji źródła danych w celu przetwarzania userIds i groupIds. W tym przykładzie zostanie wybrana domyślna biblioteka dokumentów witryny. Użyj ustawień kontenera i zapytania łącznika dla innych wyborów.

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

2. Dodawanie pól uprawnień do definicji indeksu

Scal następujące pola i właściwości do definicji schematu indeksu. Ten fragment pomija wymagany klucz dokumentu i pola zawartości; zachowaj je w pełnej definicji.

Zachowaj metadane autoryzacji SharePoint oddzielone od tożsamości klucza indeksu. Poniższe wymagania dotyczące SharePoint rozszerzają metadane źródłowe łącznika oraz instrukcje dotyczące mapowania kluczy i kodowania.

Pole źródłowe Purpose Element docelowy i mapowanie
metadata_spo_item_path Ścieżka źródłowa dla wyszukiwania ACL i aktualizacji tylko uprawnień. Wymagane Edm.String pole o nazwie metadata_spo_item_path. Użyj niejawnego mapowania z tą samą nazwą dla całych dokumentów i /document/metadata_spo_item_path w każdej projekcji fragmentu.
metadata_user_ids Obsługiwane przypisania użytkownika. Zamapuj Collection(Edm.String) na pole z elementem permissionFilter: "userIds", takim jak UserIds. Project /document/metadata_user_ids na fragmenty.
metadata_group_ids Obsługiwane Microsoft Entra oraz skonfigurowane przypisania grup lokacji SharePoint. Zamapuj Collection(Edm.String) na pole przy użyciu permissionFilter: "groupIds", takie jak GroupIds. Rzutuj /document/metadata_group_ids na fragmenty.
metadata_spo_site_url Witryna źródłowa do natywnego rozpoznawania grupa programu SharePoint. Zamapuj Edm.String na pole używające sharepointSiteUrl: true, takie jak SharePointSiteUrl. Project /document/metadata_spo_site_url na fragmenty; zachowaj witrynę każdego elementu do wyborów między witrynami.
metadata_spo_site_library_item_id Identyfikator elementu biblioteki dla wyboru biblioteki lub folderu. Zamapuj na cały dokument lub klucz indeksu nadrzędnego, korzystając z instrukcji kodowania klucza łącznika. Projekcje generują klucze podrzędne i identyfikator elementu nadrzędnego.
metadata_spo_site_asset_item_id Identyfikator zasobu/elementu dla wyborów list, stron lub zawartości mieszanej. Użyj dla elementów allSiteLists, allSitePages i allSiteContent zamiast klucza elementu biblioteki. Postępuj zgodnie z tymi samymi instrukcjami kodowania klucza; nie mapuj kluczy generowanych przez projekcję ani tożsamości nadrzędnej.
{
  "fields": [
    { "name": "metadata_spo_item_path", "type": "Edm.String", "retrievable": false },
    { "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"
}

Ustaw retrievable na true tylko podczas programowania, aby zweryfikować wartości. Zmiana retrievable nie wymaga ponownego kompilowania indeksu.

3. Skonfiguruj projekcje indeksów w zestawie umiejętności (jeśli dotyczy)

Po włączeniu fragmentowania dokument nadrzędny nie jest zapisywany w indeksie, gdy projectionMode ma wartość skipIndexingParentDocuments. Przenieś metadane ACL do każdego fragmentu przez element indexProjections.selectors[].mappings.

Jeśli indeksator używa zestawu umiejętności z fragmentowaniem danych, takim jak umiejętność dzielenia tekstu podczas włączania zintegrowanej wektoryzacji, zamapuj pola uprawnień i wymaganą ścieżkę źródłową do każdego fragmentu przy użyciu projekcji indeksu. Aby zapoznać się ze schematem zestawu umiejętności, zobacz dokumentację interfejsu API REST płaszczyzny danych 2026-10-01.

W tym przykładzie przedstawiono konfigurację zestawu umiejętności dla docelowego indeksu fragmentów z polami uprawnień z poprzedniego kroku. Element docelowy wymaga również pola content, klucza dokumentu i pola ciągu parentId, które można filtrować, zgodnie z opisem w sekcji Definiowanie projekcji indeksu. Projekcje generują klucz dokumentu i identyfikator nadrzędny; nie mapuj tych pól samodzielnie. Uwzględnij SharePointSiteUrl tylko podczas konfigurowania obsługi grup SharePoint.

Komentarz // w poniższym przykładzie jest ilustracyjny i nie jest prawidłowym kodem JSON. Usuń go przed przesłaniem żądania.

PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2026-10-01
{
  "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",
        "sourceContext": "/document/chunks/*",
        "mappings": [
          { "name": "content", "source": "/document/chunks/*" },
          { "name": "metadata_spo_item_path", "source": "/document/metadata_spo_item_path" },
          { "name": "UserIds",  "source": "/document/metadata_user_ids" },
          { "name": "GroupIds",  "source": "/document/metadata_group_ids" },
          { "name": "SharePointSiteUrl", "source": "/document/metadata_spo_site_url" }
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

Mapowania UserIds, GroupIds i SharePointSiteUrl odczytują metadane na poziomie źródła emitowane przez indeksator SharePoint (/document/metadata_*) i zapisują te wartości w każdym fragmencie.

4. Konfigurowanie mapowań pól indeksatora dla list ACL

Użyj mapowań pól indeksatora, gdy indeksator zapisuje jeden dokument na element źródłowy (bez fragmentowania) lub gdy utrzymujesz oddzielny indeks nadrzędny obok indeksu fragmentu. W przypadku indeksu tylko do fragmentu z wartością projectionMode: skipIndexingParentDocumentszachowaj mapowania projekcji z poprzedniego kroku. Nie potrzebujesz żadnego dodatkowego indeksatora fieldMappings , aby wypełnić te pola fragmentów.

Oprócz wymaganej konfiguracji indexer zamapuj nieprzetworzone pola ACL metadanych z SharePoint do pól w indeksie.

W przypadku jednego dokumentu na element źródłowy pola źródłowe i indeksu o tych samych nazwach używają niejawnego metadata_spo_item_path mapowania pól. W przypadku fragmentów użyj mapowania projekcji bezpośredniej w poprzednim kroku.

Zastosuj te zmiany konfiguracji z włączonymi uprawnieniami do konfiguracji indeksatora łącznika podstawowego:

  • Wybory biblioteki lub folderu: Zachowaj mapowanie klucza metadata_spo_site_library_item_id i jego funkcję mapowania base64Encode.
  • Wybór listy lub stron: W przypadku allSiteLists elementu lub allSitePages zastąp źródło mapowania kluczy wartością metadata_spo_site_asset_item_id, zachowując funkcję kodowania. Zachowaj konfigurację zawartości opisaną w sekcji Indeksowanie list SharePoint lub Indeksowanie stron witryny ASPX.
  • Opcje mieszane: W przypadku allSiteContent użyj metadata_spo_site_asset_item_id jako źródła mapowania kluczy w obrębie zaznaczenia, z tą samą funkcją kodowania.

Dla każdego zaznaczenia włącz userIds i groupIds w źródle danych, zachowaj wymagane pole ścieżki i dodaj następujące mapowania ACL. Dodaj mapowanie adresu URL witryny podczas korzystania z natywnych grup SharePoint. W przypadku indeksów tylko dla fragmentów użyj pięciu mapowań projekcji w poprzednim kroku zamiast ręcznego mapowania wygenerowanych kluczy lub tożsamości elementu nadrzędnego.

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

5. Uruchamianie indeksatora

Indeksator pozysuje metadane listy ACL podczas jego uruchamiania. Po utworzeniu lub zaktualizowaniu indeksatora uruchom indeksator i monitoruj jego stan, aby zaimportować wpisy ACL wraz z zawartością.

Aby uzyskać informacje na temat cyklicznego odświeżania uprawnień i uzupełniania istniejącego indeksu, zobacz Odświeżanie zindeksowanych uprawnień. Kroki wypełniania wstecznego zależą od tego, czy istniejące rekordy już zawierają metadata_spo_item_path.

6. Weryfikowanie pozyskiwania listy ACL

Aby potwierdzić, że wartości listy ACL zostały wypełnione poprawnie:

  1. Tymczasowo ustaw retrievable na true dla UserIds i GroupIds w definicji indeksu. Zmiana retrievable nie wymaga ponownego kompilowania indeksu.
  2. Uruchom zapytanie z podwyższonym poziomem uprawnień odczytu , które wybiera UserIds i GroupIds. Porównaj wartości z przypisaniami źródeł obsługiwanymi przez element. Jedna kolekcja może być pusta, gdy dostęp zostanie udzielony za pośrednictwem drugiej. W przypadku scenariuszy fragmentowanych sprawdź oczekiwane przypisania dla każdego fragmentu.
  3. Wróć retrievable do false po weryfikacji.

Porównaj dozwolone i odrzucone wyniki testowego użytkownika, korzystając z kontroli rozwiązywania problemów z zapytaniami. Same wypełnione pola ACL nie weryfikują wymuszania w czasie wykonywania zapytania.

Konfigurowanie obsługi grup SharePoint

Indeksator SharePoint może pobierać uprawnienia grup witryny SharePoint (właściciele, członkowie, odwiedzający i niestandardowe grupy witryny) do filtrowania w czasie wykonywania zapytania. Indeksator emituje identyfikatory grupa programu SharePoint w metadata_group_ids polu z prefiksemspg:, aby odróżnić je od identyfikatorów obiektów grupy Microsoft Entra.

Po skonfigurowaniu pozyskiwania ACL wykonaj następujące kroki, aby dodać rozpoznawanie grup witryn SharePoint do konfiguracji indeksu i zapytań.

Następujące składniki współpracują ze sobą, aby umożliwić określanie grup witryn programu SharePoint:

Składnik Where Purpose
sharePointConnectorAppRegistration (z applicationId, federatedCredentialId, tenantId) Definicja indeksu Udostępnia konfigurację uwierzytelniania wymaganą, aby usługa Foundry IQ mogła wywoływać interfejs API REST SharePoint w imieniu użytkownika wywołującego i ustalać członkostwo w grupie witryny w czasie wykonywania kwerendy.
SharePointSiteUrl pole (z sharepointSiteUrl: true) Schemat indeksu i mapowanie pól indeksatora z metadata_spo_site_url Określa, do której witryny SharePoint należy dokument, dzięki czemu ustalanie grup SP odbywa się w prawidłowym zakresie.
spg:-prefiksowane wartości w GroupIds Metadane uprawnień dokumentu Rozróżnianie identyfikatorów SharePoint grup witryn od identyfikatorów obiektów grupy Microsoft Entra.

W przypadku wyboru źródła obejmującego wiele witryn metadata_spo_site_url identyfikuje witrynę źródłową każdego elementu, a nie stałą witrynę dla całego indeksu. Zachowaj tę wartość dla każdego dokumentu lub fragmentu i przyznaj skonfigurowanej aplikacji wymagany dostęp do każdej wybranej witryny. Zobacz Uprawnienia w scenariuszu ACL i Wybierz, gdzie wypełniać pola ACL.

Indeks z polem oznaczonym sharepointSiteUrl: true obsługuje co najwyżej pięć odrębnych wartości adresu URL witryny. Przed wybraniem witryn sprawdź limity witryn z uprawnieniami grupa programu SharePoint. W przypadku większych zakresów oceń oddzielne indeksy i źródła wiedzy, w tym pojemność bazy wiedzy i routing aplikacji.

1. Wymagania wstępne

Uwaga

FederatedCredentialApplicationId w parametry połączenia źródła danych oraz federatedCredentialId w sharePointConnectorAppRegistration używają identyfikatora aplikacji tożsamości zarządzanej. Właściwość applicationId w sharePointConnectorAppRegistration korzysta z identyfikatora klienta aplikacji pozyskującej. Aby znaleźć poprawne wartości, zobacz Znajdowanie prawidłowych identyfikatorów Microsoft Entra.

2. Konfigurowanie indeksu

Scal następującą konfigurację z pełną definicją indeksu, zachowując klucz dokumentu i pola zawartości. Dodaje elementy sharePointConnectorAppRegistration i SharePointSiteUrl obok pól listy ACL. Zachowaj permissionFilterOption: "enabled".

{
  "name": "my-sharepoint-acl-index",
  "sharePointConnectorAppRegistration": {
      "applicationId": "<ingestion-app-client-id>",
      "federatedCredentialId": "<managed-identity-application-id>",
      "tenantId": "<sharepoint-tenant-id>"
  },
  "fields": [
    { "name": "metadata_spo_item_path", "type": "Edm.String", "retrievable": false },
    { "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. Konfigurowanie mapowań pól indeksatora

Przypisz pola metadanych SharePoint do pól indeksu w jednym wspólnym bloku mapowania. Pierwsze dwa mapowania są takie same jak te używane do standardowej ingestii ACL; trzecie mapowanie włącza rozpoznawanie grup SharePoint.

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

Jeśli zestaw umiejętności dzieli dokumenty na fragmenty (na przykład za pomocą umiejętności Dzielenie tekstu na potrzeby zintegrowanej wektoryzacji), zamiast tego rzutuj SharePointSiteUrl na każdy fragment za pomocą indexProjections.selectors[].mappings. Zobacz Wybór miejsca wypełniania pól ACL.

4. Wykonywanie zapytań względem indeksu

Nie jest wymagana żadna zmiana po stronie klienta. Ten sam token x-ms-query-source-authorization aktywuje zarówno usługę Microsoft Entra, jak i wymuszanie dla grup witryn programu SharePoint. Usługa Foundry IQ ustala po stronie serwera członkostwo w grupach grupa programu SharePoint za pomocą sharePointConnectorAppRegistration w indeksie.

Informacje o strukturze żądania można znaleźć w przykładzie zapytania ogólnego oraz w specyficznym dla SharePoint przykładzie z wymuszaniem grup witryn SharePoint.

5. Sprawdź

Aby potwierdzić, że identyfikatory grupa programu SharePoint znajdują się w indeksie, uruchom zapytanie z podwyższonym poziomem uprawnień odczytu, które wybiera GroupIds i wyszukuje spg:-prefiksowane wartości w odpowiedzi.

Synchronizowanie uprawnień między indeksowaną i źródłową zawartością

Metadane zawartości i uprawnień są replikowane do usługi Search za pomocą oddzielnych etapów przetwarzania. Wybierz podejście do pobierania na podstawie miejsca autoryzacji i sposobu zarządzania aktualizacjami przez aplikację.

Wybierz podejście do pobierania pod kątem aktualności

Preferuj zdalny SharePoint, gdy aplikacja wymaga pobierania w czasie żądania przy użyciu modelu uprawnień SharePoint, a nie zreplikowanego podzbioru uprawnień w Search. Takie podejście zapewnia aktualność danych bardziej zbliżoną do tej w SharePoint za pośrednictwem mechanizmów kontroli ładu Microsoft 365, bez dodatkowego potoku synchronizacji wyszukiwania. Wybierz pobieranie indeksowane dla niestandardowego indeksu wyszukiwania lub Push do przesyłania kontrolowanego przez aplikację.

Decyzja Zdalny program SharePoint Indeksowany program SharePoint Interfejs Push API zarządzany przez klienta
Organ autoryzacji Pobieranie w Microsoft 365 w imieniu użytkownika przy użyciu modelu uprawnień SharePoint i mechanizmów nadzoru Microsoft 365. Filtrowanie w czasie wykonywania zapytań za pośrednictwem zreplikowanego podzestawu uprawnień SharePoint. Filtrowanie w czasie wykonywania zapytań względem wartości uprawnień dostarczanych przez aplikację; brak automatycznej synchronizacji ACL w SharePoint ani rozpoznawania grup natywnych.
Świeżość zawartości i uprawnień Brak dodatkowej synchronizacji indeksów wyszukiwania; zależy od przetwarzania w Microsoft 365 i ograniczeń źródła zdalnego. Powiadomienia źródłowe i pomyślne przetwarzanie indeksatora aktualizują replikę. Harmonogramy nie ustanawiają ściśle określonego przedziału aktualności. Aplikacja kontroluje czas przesyłania, a nie natychmiastową widoczność zapytania.
Odwołanie Zależne od przetwarzania w Microsoft 365; nie oznacza natychmiastowego działania. Nieaktualne indeksowane uprawnienia mogą być utrwalane do momentu przetworzenia odpowiedniej aktualizacji. Aplikacja wykrywa odwołane uprawnienia, aktualizuje rekordy i fragmenty, a także weryfikuje wyniki.
Obowiązki związane z tożsamością Podaj tożsamość użytkownika delegowanego wymaganą przez źródło zdalne. Skonfiguruj poświadczenia pozyskiwania, obsługiwane rozpoznawanie grup i token użytkownika do wykonywania zapytań. Podaj obsługiwane tożsamości uprawnień i autoryzację wykonywania zapytań; zaimplementuj tłumaczenie uprawnień typu source-to-index.
Dostosowywanie Ogranicz pobieranie za pomocą obsługiwanych filtrów i metadanych; zależnie od możliwości interfejsu Retrieval API. Konfigurowanie schematu indeksu, obsługiwanego wzbogacania, fragmentów i wektorów. Zaimplementuj wyodrębnianie, schemat indeksu, fragmentowanie, wektory i aktualizacje uprawnień w potoku pozyskiwania.
Operacje Monitorowanie wyszukiwania i zależności Microsoft 365; brak indeksatora wyszukiwania do zaplanowania. Monitoruj przebiegi indeksatora, odśwież uprawnienia oraz weryfikuj dokumenty i projekcje. Obsługuj potok pozyskiwania i obsługę błędów aktualizacji zgodnie z opisem w poniższej sekcji.
Granice sieci i zasad Postępuj zgodnie z wymaganiami wstępnymi i ograniczeniami źródła zdalnego; to nie jest obejście dostępu warunkowego. Obowiązują ograniczenia łącznika. SharePoint Online używa publicznych punktów końcowych. Aplikacja jest właścicielem swoich połączeń źródłowych i wyszukiwania; Wypychanie nie zmienia wymagań zasad SharePoint.
Zakres interfejsu API i wydania Zdalne źródła wiedzy i interfejs Copilot Retrieval API są dostępne w wersji zapoznawczej; postępuj zgodnie z wskazówkami dotyczącymi interfejsu Remote API. Importowanie i filtrowanie ACL w usłudze SharePoint są ogólnie dostępne w interfejsie REST 2026-10-01. Wytyczne dotyczące indeksowanych źródeł wiedzy mają odrębne wymagania dotyczące interfejsu API i wersji zapoznawczej. Pozyskiwanie uprawnień przez Push REST API jest ogólnie dostępne. Przewodnik, do którego prowadzi link, identyfikuje wersję interfejsu API REST używaną w przykładach i kwestie dotyczące wsparcia dla zestawu SDK. Aby uzyskać schemat filtru uprawnień, zobacz informacje referencyjne interfejsu API REST płaszczyzny danych 2026-10-01.

W przypadku indeksowanego pobierania, propagacji źródła, przetwarzania zawartości i listy ACL, propagacji członkostwa w grupach, odnawiania tokenu, buforowania członkostwa w czasie zapytania i odświeżania indeksu mogą wpływać na widoczność. Żądane lub zaplanowane uruchomienie nie oznacza zakończenia przetwarzania. Uruchomienia mogą przekraczać ich interwał lub napotkać ograniczanie przepustowości, ponawianie prób lub awarie. Harmonogramy, reset, reset-docs i ponowna synchronizacja uprawnień nie są mechanizmami natychmiastowej aktualizacji.

W modelu Push Twoja aplikacja odpowiada za wykrywanie zmian w SharePoint, synchronizację zawartości i uprawnień, wyodrębnianie, segmentację na fragmenty i wektory, usuwanie i czyszczenie nieaktualnych rekordów, ponawianie prób, ustalanie kolejności, uzgadnianie stanu i monitorowanie. Sam czas przesyłania nie gwarantuje ścisłej aktualności end-to-end.

Obsługa błędów autoryzacji i aktualizacji

Jeśli aplikacja nie może uzyskać prawidłowej autoryzacji użytkownika lub oceny uprawnień kończy się niepowodzeniem, zatrzymaj zwracanie chronionej zawartości dla tego żądania i wyświetlanie błędu. Nie należy ponawiać próby bez tokenu użytkownika, wyłączać filtrowania uprawnień ani używać podwyższonego poziomu dostępu diagnostycznego jako rozwiązania awaryjnego widocznego dla użytkownika. Zastosuj tę odpowiedzialność również do zawartości buforowanej przez aplikację i wygenerowanych odpowiedzi.

W przypadku potoku wypychania zarządzanego przez klienta:

  1. Sprawdź wynik indeksowania każdego dokumentu, w tym częściowe błędy w odpowiedzi HTTP 207 . Śledź klucze, które zakończyły się niepowodzeniem, i spróbuj ponownie ponowić próbę niepowodzenia z powrotem po załadowaniu indeksu wyszukiwania.
  2. Wykonuj aktualizacje sekwencyjnie dla tego samego klucza i wprowadź idempotentne ponawianie prób. Konsoliduj zmiany przed przesłaniem; Kolejność akcji wsadowej nie jest zdefiniowana. Zachowaj wersję źródłową lub punkt kontrolny w pipeline, aby starsze ponawianie nie przywracało cofniętego uprawnienia.
  3. Prześlij kompletną docelową kolekcję listy ACL podczas zastępowania pola permission. Aktualizacje kolekcji zastępują kolekcję, a nie dołączają poszczególnych uprawnień.
  4. Uzgodnij elementy źródłowe względem indeksowanych kluczy i ich fragmentów. Usuń nieaktualne dokumenty, przestarzałe fragmenty i rekordy poza wybranym zakresem źródłowym, korzystając ze wskazówek dotyczących usuwania dokumentów. Aktualizacja jednego klucza nie powoduje wyczyszczenia innych kluczy.
  5. Przed traktowaniem aktualizacji za uzgodnioną sprawdź wyniki indeksowania, widoczność zapytań oraz dozwolony i odrzucony dostęp użytkownika.

Odśwież zindeksowane uprawnienia

Skonfiguruj krótki harmonogram indeksatora cyklicznego zgodnie z potrzebami w zakresie odświeżania uprawnień. Interwał minimalny to pięć minut. Skorzystaj z istniejącej definicji harmonogramu i wskazówek dotyczących konfiguracji harmonogramu.

Interwał nie jest terminem ukończenia ani umową dotyczącą poziomu usług (SLA) w zakresie cofania uprawnień. Przebiegi mogą być opóźnione, a nakładające się przebiegi mogą spowodować pominięcie zaplanowanego rozpoczęcia. Zobacz Często zadawane pytania dotyczące harmonogramowania. Zmiany uprawnień docierają do indeksu po wykryciu i pomyślnym przetworzeniu, a nie automatycznie przy każdym zaplanowanym rozpoczęciu. Harmonogram cykliczny nie żąda ponownej synchronizacji pełnych uprawnień.

Po włączeniu pozyskiwania listy ACL zwykłe odświeżanie przetwarzania przyrostowego wykryło zmiany uprawnień na poziomie elementu. Obsługiwane powiadomienie o zmianie uprawnień dla folderu biblioteki dokumentów innych niż root powoduje również, że indeksator wylicza obiekty podrzędne w zakresie i odświeża źródłowe listy ACL każdego elementu podczas kolejnego pomyślnego uruchomienia, nawet jeśli zawartość podrzędna nie uległa zmianie. Element podrzędny z unikatowymi uprawnieniami zachowuje własne źródłowe reguły dostępu zamiast otrzymywać kopię listy ACL folderu.

Ta ścieżka uprawnień folderu jest niezależna od opcji zmiany nazwy i propagacji przenoszenia i nie wymaga oddzielnej pełnej synchronizacji uprawnień. Nie ustanawia tego samego zachowania propagacji dla zmian witryny, biblioteki, listy lub katalogu głównego dysku ani pominiętych powiadomień źródłowych.

Zmień zakres Wykryto automatycznie Zalecana akcja
Wykryto zmianę uprawnień w elemencie z unikatowymi uprawnieniami (plik, element listy lub strona) Yes Uruchom indeksator lub zezwól na uruchomienie harmonogramu, a następnie sprawdź odświeżone listy ACL.
Zmiana treści w określonym elemencie Yes Przetwarzanie zmienionego elementu również ponownie ocenia efektywne listy ACL.
Obsługiwane powiadomienie o zmianie uprawnień do folderu biblioteki dokumentów innego niż główny Yes Kolejne pomyślne uruchomienie odświeża obiekty podrzędne w zakresie, w tym niezmienione pliki. Elementy podrzędne z unikatowymi uprawnieniami zachowują własne źródłowe listy ACL.
Zmiana uprawnień witryny, biblioteki, listy lub katalogu głównego dysku; przeoczone powiadomienie Nieobjęte ścieżką aktualizacji folderu Użyj ponownej synchronizacji uprawnień , aby odświeżyć istniejące indeksowane listy ACL lub zresetować dokumenty, których dotyczy problem , aby ponownie przetworzyć zawartość i listy ACL. Sprawdź wyniki.
Pozyskiwanie listy ACL włączone dla istniejącego indeksatora Wymaga wypełnienia Jeśli istniejące rekordy już zawierają metadata_spo_item_path, użyj permissions resync. W przeciwnym razie dodaj wymagane pole i odpowiednie mapowanie projekcji, a następnie zresetuj i przeprocesuj elementy źródłowe, których dotyczy problem, aby wypełnić ich ścieżki i listy ACL.

Te operacje dotyczą również wygenerowanego indeksatora dla indeksowanego źródła wiedzy SharePoint. Dodanie pola schematu nie powoduje wypełnienia istniejących rekordów. W przypadku przewidywanych indeksów sprawdź uprawnienia i metadane źródłowe we fragmentach, których dotyczy problem.

Traktuj zmiany cyklu życia źródła niezależnie od odświeżania tylko uprawnień:

  • Zmiany zawartości: Ponownie przetwarza zawartość, której dotyczy problem, i jego fragmenty za pośrednictwem normalnego uruchomienia indeksatora lub zresetowania docelowego. Ponowne synchronizowanie uprawnień nie powoduje ponownego uruchomienia wyodrębniania ani embeddingów.
  • Przenoszenie i zmiana nazw: W razie potrzeby sprawdź ograniczenia indeksowania przyrostowego łącznika i zaktualizuj ścieżki wyboru źródła. Porównaj bieżącą ścieżkę źródłową i tożsamość indeksowaną z wcześniejszymi rekordami i fragmentami; nie traktuj uprawnień ponownie synchronizowanych jako migracja klucza.
  • Usunięcia: Łącznik wykrywa usunięcia źródła w kolejnych uruchomieniach. Po pomyślnym przetworzeniu sprawdź, czy indeksowane dokumenty i fragmenty elementu źródłowego są nieobecne.
  • Nieaktualne rekordy lub fragmenty: Porównaj oczekiwane elementy źródłowe i przewidywane elementy podrzędne z rzeczywistymi zindeksowanymi kluczami po przetworzeniu. Badanie pozostałych rekordów przy użyciu funkcji Usuń dokumenty; Pomyślne odświeżenie bieżących rekordów nie jest dowodem na to, że przestarzałe rekordy zostały usunięte.

Zapytania nie uruchamiają indeksatorów. Monitoruj stan wykonywania pod kątem ukończenia, ostrzeżeń, niepowodzeń i liczby elementów, a następnie sprawdź wyniki filtrowane według uprawnień. Sam przebieg zakończony powodzeniem nie potwierdza pełnej aktualności end-to-end.

Resetowanie określonych dokumentów

Użyj reset specific documents, aby ponownie przetworzyć zawartość i listy ACL dla znanych kluczy dokumentów, a następnie uruchomić indeksator. Ten proces różni się od odświeżania tylko uprawnień.

Resynchronizuj listy ACL w całym źródle danych

Użyj ponownej synchronizacji z interfejsem API 2026-10-01 REST i options: ["permissions"]. Następne ręczne lub zaplanowane wykonywanie indeksatora przetwarza żądanie; monitoruj je aż do zakończenia. Akceptacja żądania nie oznacza ukończenia przetwarzania. Ta operacja wymagająca tylko uprawnień używa istniejącego metadata_spo_item_path każdego rekordu do odświeżania indeksowanych dokumentów i projekowanych fragmentów bez ponownego uruchamiania zestawu umiejętności lub osadzania. W przypadku rekordów bez ścieżek postępuj zgodnie ze wskazówkami dotyczącymi wypełniania. Późniejsze normalne uruchomienie przetwarzania zawartości to osobna operacja.

Ponowna synchronizacja uprawnień to coś innego niż ponawianie synchronizacji, które może spowodować ponowne przetworzenie zawartości podczas normalnego działania indeksatora. Nie dodaje również obsługi linków do udostępniania w całej organizacji ani wygasania linków.

Do czasu przetworzenia odpowiedniej aktualizacji zapytania mogą używać nieaktualnych zindeksowanych list ACL. Po przetworzeniu porównaj wyniki testowego użytkownika z dostępem i testowego użytkownika bez dostępu, korzystając z kontroli rozwiązywania problemów z zapytaniami.

Po zaindeksowaniu danych i list ACL możesz wykonać zapytanie dotyczące indeksu.

Troubleshooting

Objaw Przyczyna i rozwiązanie
UserIds lub GroupIds są puste w dokumentach indeksowanych Jeśli twój zestaw umiejętności używa projectionMode: skipIndexingParentDocuments, indeksator pomija mapowania pól dla pól listy ACL. Zamiast tego ustaw pola ACL za pomocą indexProjections.selectors[].mappings w każdym fragmencie.
Brak identyfikatorów grup witryn SharePoint lub GroupIds wartości nie mają prefiksu spg: Upewnij się, że indeks ma konfigurację sharePointConnectorAppRegistration, pole SharePointSiteUrl istnieje z wartością sharepointSiteUrl: true, a mapowanie metadata_spo_site_url jest obecne w mapowaniach pól indeksatora lub w projekcjach indeksu.
SharePointSiteUrl wartość jest pusta lub ma wartość null po indeksowaniu, mimo że listy ACL są poprawnie wypełniane Indeksator emituje te metadane w obszarze metadata_spo_site_url, a nie metadata_sharepoint_site_url. Sprawdź, czy mapowanie pól indeksatora używa metody "sourceFieldName": "metadata_spo_site_url". Jeśli zestaw umiejętności używa projekcji indeksu dla dokumentów podzielonych na fragmenty, sprawdź, czy źródłem mapowania projekcji jest /document/metadata_spo_site_url.
Indeksator zwraca wartość 401 lub 403 Udziel zgody administratora zarówno na uprawnienia interfejsu API Microsoft Graph, jak i SharePoint dla danego scenariusza. Użyj poświadczeń federacyjnych (a nie klucza tajnego klienta), jeśli scenariusz go wymaga. Zobacz Scenariusz uprawnień według listy ACL.
Uprawnienia są nieaktualne po zmianie źródłowej listy ACL Sprawdź pomyślne przetwarzanie i zakres zmiany w sekcji Synchronizowanie uprawnień między indeksowaną i źródłową zawartością. Obsługiwane powiadomienia folderów używają normalnego przetwarzania przyrostowego; inne zakresy lub nieodebrane powiadomienia mogą wymagać jawnego odświeżania.
Pozyskiwanie listy ACL zgłasza brak ścieżki źródłowej Dodaj wymagane metadata_spo_item_path pole indeksu i odpowiednie mapowanie projekcji, a następnie zresetuj i przeprocesuj elementy źródłowe, których dotyczy problem. Dodanie pola nie powoduje wypełnienia istniejących rekordów, a ponowne synchronizowanie uprawnień nie powoduje wypełniania brakujących ścieżek. Zobacz Dodawanie pól uprawnień i wskazówki dotyczące uzupełniania brakujących danych.
federatedCredentialId jest odrzucany podczas konfigurowania sharePointConnectorAppRegistration Użyj identyfikatora aplikacji tożsamości zarządzanej, a nie identyfikatora obiektu poświadczeń tożsamości federacyjnej ani identyfikatora głównego tożsamości zarządzanej. Zobacz Identyfikator aplikacji poświadczeń federacyjnych.
Indeksator zwraca 401 Unauthorized, a FederatedCredentialApplicationId jest ustawione Sprawdź, czy użyto identyfikatora aplikacji tożsamości zarządzanej (znajdującego się w aplikacjach dla przedsiębiorstw), a nie identyfikatora aplikacji pozyskiwania (ApplicationIdklienta) lub dowolnego identyfikatora obiektu. W przypadku tożsamości zarządzanej przypisanej przez użytkownika użyj identyfikatora klienta na stronie Właściwości zasobu tożsamości zarządzanej. Zobacz Znajdowanie prawidłowych identyfikatorów Microsoft Entra.

Aby uzyskać brakujące, nieoczekiwane lub nieudane wyniki dotyczące czasu zapytania po indeksowaniu metadanych listy ACL, zobacz Rozwiązywanie problemów z filtrowaniem uprawnień SharePoint.