Indeksowanie list ACL dokumentów przy użyciu interfejsów API REST push

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 uprawnień na poziomie dokumentu za pośrednictwem push REST APIs jest ogólnie dostępne. Interfejsy API REST wypychania umożliwiają indeksowanie zawartości przy użyciu identyfikatorów użytkowników i grup oraz zakresów RBAC kontenera magazynu Microsoft Entra. Usługa Foundry IQ (Wyszukiwanie AI platformy Azure) używa tych metadanych do filtrowania dokumentów w czasie wykonywania zapytania.

Najważniejsze funkcje obejmują:

  • Elastyczna kontrola nad potokami pozyskiwania.
  • Ustandaryzowany schemat metadanych uprawnień.
  • Obsługa uprawnień hierarchicznych, takich jak listy ACL na poziomie folderu.

W tym artykule wyjaśniono, jak używać interfejsu API REST wypychania do indeksowania metadanych uprawnień na poziomie dokumentu w usłudze Foundry IQ. Ten proces przygotowuje indeks do wykonywania zapytań i wymuszania uprawnień użytkownika końcowego w wynikach wyszukiwania.

Wymagania wstępne

  • Zawartość z metadanymi listy ACL z Microsoft Entra ID lub innego systemu listy ACL w stylu POSIX-owym. W przypadku pól ACL userIds i groupIds użyj identyfikatorów obiektów Microsoft Entra (identyfikatorów GUID), a nie nazw UPN ani adresów e-mail. Stabilne identyfikatory obiektów zapewniają niezawodne dopasowywanie tożsamości w czasie zapytania, nawet jeśli atrybuty katalogu się zmieniają.

  • Wersja 2026-10-01 interfejsu API REST.

  • Schemat indeksu ze włączonym permissionFilterOption, oraz atrybuty pól permissionFilter, które przechowują uprawnienia dokumentu.

  • Wymagane jest istniejące uprawnienie do tworzenia definicji indeksu, przekazywania dokumentów i wykonywania zapytań względem indeksu. Aby uzyskać dostęp oparty na rolach, zobacz Łączenie przy użyciu ról.

  • Do przykładów zapytań potrzebne są token dostępu użytkownika delegowanego i identyfikator obiektu Microsoft Entra tego samego użytkownika. Zobacz Role tokenu w czasie wykonywania zapytania i przepływy uprawnień.

Ograniczenia

  • Pole listy ACL z typem userIds filtru uprawnień lub groupIds może przechowywać co najwyżej 1000 wartości.

  • Indeks może przechowywać co najwyżej pięć odrębnych rbacScope wartości we wszystkich dokumentach.

  • Adnotacje natywne permissionFilter można dodawać lub usuwać z istniejących zgodnych pól. Nie można zmienić istniejącej adnotacji bezpośrednio na inny typ filtru uprawnień.

  • W indeksie może istnieć tylko jedno pole każdego permissionFilter typu (każde z groupIds, userIdsi rbacScope).

  • Każde permissionFilter pole musi być filterable i najwyższego poziomu. Nie może to być pole klucza ani pole wektorowe. Pola uprawnień nie mogą zawierać analizatorów, normalizatorów ani map synonimów.

  • Wymuszanie uprawnień w czasie wykonywania zapytania odzwierciedla wartości ACL ostatnio zapisane do indeksu. Jeśli uprawnienia w źródle ulegną zmianie, zmiany te nie będą widoczne, dopóki nie ponownie zaimportujesz lub nie zaktualizujesz dokumentów, których to dotyczy. Zaplanuj przyrostowe ponowne pobieranie lub częściowe aktualizacje, aby utrzymać aktualność list ACL.

  • Ta funkcja nie jest obecnie obsługiwana w portalu Azure.

Tworzenie indeksu z polami filtru uprawnień

Indeksowanie list ACL dokumentów i metadanych RBAC przy użyciu interfejsu API REST wymaga skonfigurowania schematu indeksu, który umożliwia filtrowanie uprawnień i zawiera pola z przypisaniami filtrów uprawnień.

Ustaw jawnie permissionFilterOption na wartość enabled. Prawidłowe wartości to enabled i disabled. W nowym indeksie z adnotacjami pól uprawnień pominięcie opcji ustawia ją domyślnie na enabled. W przypadku aktualizacji pominięcie zachowuje istniejącą opcję, jeśli istnieje.

Użyj userIds dla Collection(Edm.String) i groupIds, a Edm.String dla rbacScope. Indeks może mieć jedno pole każdego typu adnotacji.

Poniższy 2026-10-01 przepływ pracy tworzy oddzielny przykładowy indeks z polem userIds uprawnień. Pole z możliwością content wyszukiwania obsługuje również przykłady moreLikeThis. Zastąp <SEARCH_SERVICE_ENDPOINT> element punktem końcowym i <SEARCH_ACCESS_TOKEN> tokenem wywołującym, który ma wymagane role wyszukiwania. Użyj nazwy przykładu tylko dla nowego indeksu, ponieważ żądanie aktualizuje istniejący indeks o tej samej nazwie.

PUT <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')?api-version=2026-10-01
Authorization: Bearer <SEARCH_ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json

{
  "name": "secured-content-index",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "searchable": false,
      "filterable": true,
      "sortable": true
    },
    {
      "name": "content",
      "type": "Edm.String",
      "searchable": true,
      "filterable": false,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "category",
      "type": "Edm.String",
      "searchable": false,
      "filterable": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "userIds",
      "type": "Collection(Edm.String)",
      "filterable": true,
      "retrievable": false,
      "searchable": false,
      "sortable": false,
      "facetable": false,
      "permissionFilter": "userIds"
    }
  ],
  "permissionFilterOption": "enabled"
}

Odwołanie: Tworzenie lub aktualizowanie indeksu.

Poniższy 2026-10-01 fragment schematu ilustruje wszystkie trzy natywne typy pól uprawnień dla przykładu indeksowania w dalszej części tego artykułu:

{  
  "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": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false },
    { "name": "DocumentId", "type": "Edm.String", "key": true }  
  ],
  "permissionFilterOption": "enabled"
}

W przypadku repozytoriów przedsiębiorstwa, takich jak SharePoint Online, przed wywołaniem interfejsu API push należy na etapie pozyskiwania odwzorować uprawnienia na poziomie dokumentu lub folderu na identyfikatory obiektów użytkowników i grup w usłudze Microsoft Entra. Następnie należy przechowywać te identyfikatory w odpowiednich polach uprawnień.

Ustanawianie zaufanej tożsamości dokumentu i uprawnień

Ogranicz publikowanie dokumentów do tożsamości autoryzowanych do utrzymywania docelowej zawartości i uprawnień. Wydawca musi uzyskać uprawnienia z autorytatywnej polityki dostępu dla tej samej tożsamości dokumentu, zamiast kopiować właściwości podobne do uprawnień ze zwykłej zawartości.

Przed przesłaniem przekazywania lub scalania przejrzyj klucz i uprawnienia dokumentu. Ponowne użycie klucza odnosi się do tego samego indeksowanego rekordu; uprawnienia do zapisu zawartości same w sobie nie stanowią uprawnienia do zmiany zawartości lub uprawnień innego rekordu. Gdy wiele zaufanych źródeł celowo współużytkuje rekord, uzgodnijcie kwestię jego własności i ostateczne zasady uprawnień. Scalanie zastępuje podaną kolekcję zamiast łączyć swoje wpisy z istniejącymi wartościami.

W przypadku potoku zarządzanego przez klienta należy kontrolować, która wartość źródłowa dostarcza wartość dla DocumentId, a które zasady zapewniają uprawnienia dla tej tożsamości. Zachowaj oddzielne identyfikatory biznesowe, jeśli nie są unikatowe w źródłach dostarczających dane. Nie pozwól, aby zawartość o niższym zaufaniu wybierała klucz lub wartości uprawnień innego rekordu. Te obowiązki należą do autoryzowanego wydawcy, a nie do nowego ustawienia wymuszania własności.

Adnotacje pól uprawnień umożliwiają ocenę przechowywanych wartości w zapytaniu; nie ustalają, że autor zawartości jest upoważniony do dostarczania tych uprawnień. Użyj listy kontrolnej konfiguracji pozyskiwania danych, aby zachować wybór tożsamości i uprawnień w ramach zaufanego procesu publikowania.

Przykład indeksowania interfejsu API REST

Wypełnij pola uprawnień, takie jak inne pola dokumentu. W przypadku utworzonego wcześniej indeksu 2026-10-01 przekaż następujące cztery dokumenty. Zastąp <USER_OBJECT_ID> identyfikatorem obiektu Microsoft Entra delegowanego użytkownika, którego token podajesz w przykładzie zapytania. Dokumenty 21, 101 i control przyznają temu użytkownikowi dostęp; hidden nie ma uprawnień.

POST <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')/docs/search.index?api-version=2026-10-01
Authorization: Bearer <SEARCH_ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json

{
  "value": [
    {
      "@search.action": "upload",
      "id": "21",
      "content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
      "category": "astronomy",
      "userIds": [
        "<USER_OBJECT_ID>"
      ]
    },
    {
      "@search.action": "upload",
      "id": "101",
      "content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
      "category": "astronomy",
      "userIds": [
        "<USER_OBJECT_ID>"
      ]
    },
    {
      "@search.action": "upload",
      "id": "hidden",
      "content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
      "category": "astronomy",
      "userIds": [
        "none"
      ]
    },
    {
      "@search.action": "upload",
      "id": "control",
      "content": "Botanical gardens cultivate orchids and roses. Gardeners prune flowering plants and water their roots. A greenhouse protects young seedlings from cold weather.",
      "category": "gardening",
      "userIds": [
        "<USER_OBJECT_ID>"
      ]
    }
  ]
}

Odwołanie: Indeksowanie dokumentów.

Kontynuuj pracę z przykładem zapytania, aby potwierdzić, że dokumenty użytkownika są zwracane, gdy hidden jest wykluczone.

2026-10-01 Poniższy przykład ilustruje inne opcje.

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-10-01
{
  "value": [
    {
      "@search.action": "upload",
      "DocumentId": "1",
      "UserIds": ["00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"],
      "GroupIds": ["none"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-01"
    },
    {
      "@search.action": "merge",
      "DocumentId": "2",
      "UserIds": ["none"],
      "GroupIds": ["33dd33dd-ee44-ff55-aa66-77bb77bb77bb", "44ee44ee-ff55-aa66-bb77-88cc88cc88cc"]
    },
    {
      "@search.action": "mergeOrUpload",
      "DocumentId": "3",
      "UserIds": ["1cdd8521-38cf-49ab-b483-17ddaa48f68f"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-03"
    }
  ]
}

Zaktualizować listy ACL wypchnięte przed zmianą normalizacji z października 2026 r.

Usługa Foundry IQ normalizuje wartości identyfikatorów uprawnień do małych liter podczas przesyłania dokumentów. To zachowanie dotyczy pól z adnotacjami permissionFilter: "userIds" lub permissionFilter: "groupIds", ale nie ma zastosowania do nazw pól ani niepowiązanych pól dokumentów.

Aktualizacja usługi z października 2026 r. wprowadza tę normalizację dla 2026-05-01-preview i 2026-08-01-preview. Ta zmiana obowiązuje również w interfejsie API REST 2026-10-01 GA. Usługa nie nadpisuje automatycznie wcześniej przechowywanych wartości. Zmiana samej wersji interfejsu API nie powoduje ich aktualizacji.

Jeśli bezpośrednio wypchniesz listy ACL przy użyciu jednej z dwóch wersji zapoznawczych przed zmianą normalizacji, istniejące identyfikatory uprawnień zapisane wielkimi literami lub mieszane pod względem wielkości liter mogą nie być zgodne z tożsamościami używanymi podczas wykonywania zapytania. Autoryzowani użytkownicy mogą otrzymywać mniej wyników niż oczekiwano.

Ta migracja dotyczy tylko list ACL przesłanych bezpośrednio za pośrednictwem interfejsu API wypychania. Nie jest to wymagane dla wbudowanych indeksatorów ani indeksowanych źródeł wiedzy.

Aby ponownie indeksować wartości ACL, których dotyczy problem:

  1. Zidentyfikuj dokumenty i fragmenty z identyfikatorami uprawnień wypchniętymi przed zmianą. Wartości, które są już przechowywane w małych literach, nie wymagają tej aktualizacji wielkości liter.
  2. Prześlij ponownie bieżące wartości listy ACL dla każdego rekordu, którego to dotyczy. merge Użyj akcji z kluczem dokumentu i ukończ kolekcje uprawnień, aby zaktualizować listy ACL bez zastępowania zawartości. Scalanie zastępuje podaną kolekcję; uwzględnij każde bieżące uprawnienie, a nie tylko wpisy, w których zmieniono wielkość liter.
  3. Sprawdź odpowiedź na indeksowanie każdego rekordu i ponów próbę nieudanych aktualizacji. Kontynuuj, dopóki nie zaktualizujesz wszystkich rekordów, których dotyczy problem. Migracja częściowa może pozostawić niespójne dopasowania.
  4. Przetestuj zapytania jako użytkownik, który powinien mieć dostęp, i użytkownik, który nie powinien. Używaj elevated read wyłącznie do diagnostyki, a nie do ujawniania wartości ACL w zwykłych wynikach użytkownika.

Reguły ustalania dostępu listy kontroli dostępu (ACL)

Natywne filtrowanie uprawnień ocenia userIds, groupIds i rbacScope jako alternatywne przyznania uprawnień, połączone operatorem OR. Dopasowanie w dowolnym polu udziela dostępu do dokumentu; wartość niezgodna w innym polu nie zastępuje tego przyznania. To zachowanie typu any-grant wymaga pomyślnej oceny uprawnień.

Użytkownik uzyskuje dostęp za pośrednictwem pasującego identyfikatora użytkownika lub grupy albo autoryzacji odczytu obiektu blob magazynu w zakresie indeksowanego kontenera. Sprawdzanie zakresu magazynu używa delegowanego użytkownika w x-ms-query-source-authorization, a nie poświadczenia operacji. Autoryzacja operacji jest nadal wymagana. Aby uzyskać szczegółowe informacje o zachowaniu w przypadku niepowodzenia oceny uprawnień, zobacz Wymuszanie listy ACL i kontroli dostępu opartej na rolach w czasie zapytania.

Specjalna wartość listy ACL "none"

Pola listy ACL, takie jak userIds i groupIds, zwykle zawierają Microsoft Entra identyfikatory obiektów (GUID), które identyfikują użytkowników i grupy z dostępem do dokumentu. Użyj specjalnej wartości ciągu none lub pustej tablicy, aby wskazać, że pole listy ACL nie udziela dostępu.

Wartość listy ACL Znaczenie
["none"] Żaden użytkownik nie może uzyskać dostępu do dokumentu, pasując do tego typu listy ACL
[] (pusta tablica) Żaden użytkownik nie może uzyskać dostępu do dokumentu, pasując do tego typu listy ACL

Ustawienie userIds na ["none"] lub pustą tablicę oznacza, że żaden użytkownik nie ma dostępu do dokumentu na podstawie identyfikatora użytkownika. Mogą one nadal mieć dostęp dzięki odpowiadającemu identyfikatorowi grupy lub metadanym RBAC.

Przykład kontroli dostępu

Ten przykład ilustruje, jak reguły dostępu do dokumentów są określane na podstawie wartości pól uprawnień w userIds, groupIds i rbacScope. Dla czytelności w tym scenariuszu użyto aliasów, takich jak „user1” i „group1”, zamiast identyfikatorów GUID; w środowisku produkcyjnym używaj identyfikatorów obiektów Microsoft Entra (GUID).

Dokument # identyfikatory użytkowników groupIds Zakres RBAC Lista dozwolonych użytkowników Uwaga
1 ["none"] [] Pusty Żaden użytkownik nie ma dostępu Wartości ["none"] i [] zachowują się dokładnie tak samo
2 ["none"] [] zakres/do/kontener1 Użytkownicy z uprawnieniami RBAC do kontenera1 Wartość "none" nie blokuje dostępu, gdy inne pola uprawnień (groupIds lub rbacScope) udzielają dostępu
3 ["none"] ["group1", "group2"] Pusty Członkowie grupy1 lub grupy2
4 ["user1", "user2"] ["group1"] Pusty Użytkownik1, użytkownik2 lub dowolny członek grupy1
5 ["user1", "user2"] [] Pusty Użytkownik1 lub użytkownik2