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

Pozyskiwanie metadanych uprawnień programu SharePoint (wersja zapoznawcza) wykorzystuje indeksator usługi Wyszukiwanie AI platformy Azure, aby zachować metadane uprawnień, takie jak listy kontroli dostępu (ACL), razem z inną zawartością programu SharePoint w usłudze Microsoft 365. Indeksator przechowuje uprawnienia jako metadane dla każdego indeksowanego dokumentu. W czasie wykonywania zapytania użytkownicy otrzymują tylko dokumenty, do których mają uprawnienia dostępu.

Wymagania wstępne

• Wyszukiwanie AI platformy Azure w warstwie rozliczanej (Podstawowa lub nowsza) 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 w wersji 2026-08-01-preview lub równoważny pakiet zestawu SDK w wersji zapoznawczej.

Ograniczenia

• Przyrostowe aktualizacje listy ACL wymagają interfejsu API REST 2026-05-01-preview lub nowszego. We wcześniejszych wersjach zapoznawczych interfejsu API system rejestruje listy ACL tylko przy pierwszym pozyskaniu każdego elementu. Późniejsze zmiany uprawnień wymagają jawnego ponownego indeksowania. Aby uzyskać instrukcje migracji, zobacz Synchronizowanie uprawnień między indeksowaną i źródłową zawartością.

• Zmiany uprawnień zakresu nadrzędnego nie są automatycznie uwzględniane podczas kolejnych uruchomień indeksatora. Aby zapoznać się z opcjami 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 w tej wersji zapoznawczej:

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

  • Linki z możliwością udostępniania są ograniczone do zakresu "Każdy" lub "Osoby w organizacji". Obsługiwane są tylko linki o zakresie "Określone osoby".

  • Grupy programu SharePoint (takie jak grupy Właściciele, Członkowie i Odwiedzający) są obsługiwane od wersji 2026-05-01-preview interfejsu API REST. Zobacz Konfigurowanie obsługi grup SharePoint. We wcześniejszych wersjach zapoznawczych interfejsu API obsługiwane są tylko grupy SharePoint mapowane na grupy Microsoft Entra.

• Następujące funkcje indeksatora nie obsługują dziedziczenia uprawnień w indeksowanych dokumentach pochodzących z SharePoint. Jeśli używasz żadnej z tych funkcji w zestawie umiejętności lub indeksatorze, uprawnienia na poziomie dokumentu nie są uwzględniane w indeksowanej zawartości.

  • Dostosowana umiejętność Web API

  • Repozytorium wiedzy, w tym magazyn zasobów wymagany do udostępniania obrazów (wersja zapoznawcza) w wyszukiwaniu agentowym. W związku z tym udostępnianie obrazów nie jest obsługiwane dla źródeł wiedzy, które pobierają listy kontroli dostępu (ACL) z usługi SharePoint.

  • Wzbogacona pamięć podręczna indeksatora

  • Sesje debugowania

Obsługa modelu uprawnień SharePoint

Ta wersja zapoznawcza obsługuje podstawowe listy kontroli dostępu (ACL) dla dokumentów, elementów listy i nowoczesnych stron ASPX w witrynie.

Obsługiwane relacje grup

Przechodniość grup w usłudze Microsoft Entra ma zastosowanie w obrębie usługi Microsoft Entra. Nie rozwija grup Microsoft Entra, które są członkami grup programu SharePoint.

Jak oceniane są uprawnienia hierarchiczne

SharePoint uprawnienia dziedziczą hierarchię witryna → biblioteka → folder → plik, chyba że dziedziczenie zostanie przerwane.

Podczas pozyskiwania indeksator zbiera identyfikatory użytkowników i grup (ID) na każdym poziomie i oblicza obowiązującą listę ACL dla każdego pliku.

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.

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 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 Wyszukiwanie AI platformy Azure.
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 wyszukiwania lub wklej Identyfikator obiektu (podmiotu) 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.

Skonfiguruj usługę wyszukiwania pod kątem pozyskiwania danych ACL i egzekwowania podczas wykonywania zapytań

Te kroki konfigurują usługę wyszukiwania do przetwarzania list ACL i zapewniają respektowanie uprawnień ACL podczas 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.

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

Ta sekcja stanowi uzupełnienie bazowej instrukcji Krok 4: Tworzenie źródła danych. Ustaw w definicji źródła danych , aby umożliwić indeksowanie i z dokumentów SharePoint.

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

2. Dodawanie pól uprawnień do definicji indeksu

Dodaj pola do definicji schematu indeksu, aby przechowywać ACL i obsługiwać filtrowanie w czasie zapytań.

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

Ustaw atrybut retrievable na true tylko podczas procesu tworzenia, aby zweryfikować wartości. Można zmienić możliwość pobierania z wartości true na false bez wymagania 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, pamiętaj o mapowaniu właściwości listy ACL na każdy fragment przy użyciu projekcji indeksu. Linie // w poniższym przykładzie są jedynie ilustracyjnymi adnotacjami i nie stanowią poprawnego kodu JSON. Usuń je przed przesłaniem żądania.

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

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. Jeśli zestaw umiejętności dzieli dokumenty na fragmenty do jednego docelowego indeksu za pomocą projectionMode: skipIndexingParentDocuments, mapowania pól pokazane tutaj zastępuje indexProjections.mappings z poprzedniego kroku dla indeksu fragmentów.

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

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

5. Uruchamianie indeksatora

Metadane ACL są pobierane podczas działania indeksatora. Po utworzeniu lub zaktualizowaniu indeksatora (zobacz Krok 6: Tworzenie indeksatora) uruchom go, aby pobierał listy ACL wraz z zawartością.

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

Jeśli włączono pozyskiwanie ACL dla istniejącego indeksatora, który ma już zindeksowane elementy, wywołaj /resync z parametrem options: ["permissions"], aby uzupełnić listy ACL dla tych elementów, lub użyj /resetdocs, aby ponownie wyodrębnić określone elementy.

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 podniesionymi uprawnieniami odczytu, które wybiera UserIds i GroupIds, a następnie potwierdź, że kolekcje nie są puste. W przypadku scenariuszy podzielonych na fragmenty upewnij się, że każdy fragment zawiera oba pola.
3. Wróć retrievable do false po weryfikacji.

Konfigurowanie obsługi grup SharePoint

Począwszy od wersji 2026-05-01-preview interfejsu API REST, indeksator SharePoint może pozyskiwać informacje o członkostwie w grupach witryny SharePoint (Właściciele, Członkowie, Odwiedzający i niestandardowe grupy witryny). Uwzględnia te grupy w trakcie wykonywania zapytania. Identyfikatory grup SharePoint są umieszczane w polu metadata_group_ids z prefiksem spg:, aby odróżnić je od identyfikatorów obiektów grup w usłudze Microsoft Entra.

Ten przewodnik jest samowystarczalny: wykonaj kroki w podanej kolejności, aby skonfigurować indeks, mapowania pól indeksatora oraz wykonywać zapytania względem indeksu z wymuszaniem dla grup witryny programu SharePoint.

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

1. Wymagania wstępne

• Indeksator usługi SharePoint został już skonfigurowany do pozyskiwania uprawnień ACL. Zobacz Konfigurowanie mapowań pól indeksatora dla ACL.
• Rejestracja aplikacji Microsoft Entra z poświadczeniem tożsamości federacyjnej. Zobacz Konfigurowanie zarejestrowanej aplikacji przy użyciu tożsamości zarządzanej.
• REST API 2026-05-01-preview lub nowszy.

2. Konfigurowanie indeksu

Dodaj konfigurację sharePointConnectorAppRegistration oraz pole SharePointSiteUrl obok pól filtru uprawnień UserIds i GroupIds, aby pełna struktura indeksu była w jednym miejscu. Zachowaj 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. 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.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 wyszukiwania ustala członkostwo w grupach programu SharePoint po stronie serwera 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 grup SharePoint trafiły do indeksu, uruchom zapytanie elevated-read, które wybiera GroupIds, i poszukaj w odpowiedzi wartości z prefiksem spg:.

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

Począwszy od interfejsu API REST 2026-05-01-preview, zmiany listy ACL elementów z unikatowymi uprawnieniami są wykrywane i odświeżane po każdym pomyślnym uruchomieniu indeksatora. Indeksator używa tokenów zmian programu SharePoint do przyrostowego wykrywania dodawania i usuwania przypisań ról, w taki sam sposób, w jaki wykrywa zmiany zawartości.

Niektóre scenariusze nadal wymagają jawnego odświeżania:

Resetowanie określonych dokumentów

Możesz zresetować określone dokumenty, aby ponownie w pełni przeanalizować zawartość i listy kontroli dostępu (ACL).

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

Ponowne zsynchronizowanie list ACL w całym źródle danych

Po początkowym wprowadzeniu danych można ponownie zsynchronizować pełną zawartość ACL zbioru danych. Aby w pełni zakończyć pracę, ta operacja wymaga uruchomienia indeksatora po zakończeniu.

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

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

Troubleshooting

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.

Powiązana zawartość

• Indeksować zawartość SharePoint w Wyszukiwanie AI platformy Azure (wersja zapoznawcza)
• Egzekwowanie ACL w momencie zapytania