Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Note
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.
W przypadku rozwiązań wyszukiwania, które nie mogą używać wbudowanej obsługi listy kontroli dostępu (ACL) na potrzeby autoryzacji na poziomie dokumentu, Foundry IQ (Wyszukiwanie AI platformy Azure) obsługuje tworzenie filtru, który przycina wyniki wyszukiwania na podstawie ciągu zawierającego grupę lub tożsamość użytkownika.
W tym artykule opisano wzorzec filtrowania zabezpieczeń, wykonując następujące czynności:
- Zmontuj dokumenty źródłowe z wymaganą zawartością, w tym ciąg znaków do przechowywania tożsamości
- Tworzenie pola w indeksie wyszukiwania dla identyfikatorów głównych
- Wypychanie dokumentów do indeksu wyszukiwania na potrzeby indeksowania
- Wykonaj zapytanie w indeksie za pomocą funkcji
search.infilter
Zawiera on linki do pokazów i przykładów, które zapewniają praktyczne uczenie się. Zalecamy zapoznanie się z tym artykułem najpierw, aby zrozumieć wzorzec.
Informacje o wzorcu filtru zabezpieczeń
Wzorzec filtru zabezpieczeń symuluje autoryzację na poziomie dokumentu poprzez użycie zwykłego filtru OData, który włącza lub wyklucza wynik wyszukiwania na podstawie ciągu znaków reprezentującego podmiot zabezpieczeń. Nie ma uwierzytelniania ani autoryzacji za pośrednictwem podmiotu zabezpieczeń. Główna wartość to tylko ciąg znaków używany w wyrażeniu filtru, aby włączyć lub wykluczyć dokument z wyników wyszukiwania.
Ten wzorzec zarządzany na poziomie aplikacji różni się od natywnego filtrowania uprawnień. Aplikacja musi uwierzytelniać użytkowników, pozyskiwać zaufane wartości podmiotu zabezpieczeń i uprawnień, stosować filtry do wszystkich zapytań oraz zapobiegać obchodzeniu tych zabezpieczeń. Ani nazwa pola powiązanego z uprawnieniami, ani klucz dokumentu nie dowodzi, że uprawnienia są autoryzowane dla skojarzonej zawartości. Zwykła zawartość i dane wyjściowe wzbogacania nie są automatycznie uznawane za wiążące uprawnienia. W przypadku pozyskiwania obiektów blob zapoznaj się z tożsamością dokumentu i pochodzeniem uprawnień.
Istnieje kilka sposobów na filtrowanie bezpieczeństwa. Jednym ze sposobów jest skomplikowane rozwarcie wyrażeń równości: na przykład Id eq 'id1' or Id eq 'id2', i tak dalej. Takie podejście jest podatne na błędy, trudne do utrzymania i w przypadkach, gdy lista zawiera setki lub tysiące wartości, spowalnia czas odpowiedzi zapytania o wiele sekund.
Lepszym rozwiązaniem jest użycie search.in funkcji dla filtrów zabezpieczeń zgodnie z opisem w tym artykule. Jeśli używasz search.in(Id, 'id1, id2, ...') zamiast wyrażenia równości, możesz oczekiwać czasów odpowiedzi poniżej jednej sekundy.
Wymagania wstępne
Pole ciągu zawierające tożsamość grupy lub użytkownika, takie jak identyfikator obiektu Entra firmy Microsoft.
Inne pola w tym samym dokumencie powinny zawierać zawartość dostępną dla tej grupy lub użytkownika. W poniższych dokumentach JSON pola "security_id" zawierają tożsamości używane w filtrze zabezpieczeń, a nazwa, wynagrodzenie i stan cywilny są uwzględniane, jeśli tożsamość obiektu wywołującego pasuje do "security_id" dokumentu.
{ "Employee-1": { "employee_id": "100-1000-10-1-10000-1", "name": "Abram", "salary": 75000, "married": true, "security_id": "alphanumeric-object-id-for-employee-1" }, "Employee-2": { "employee_id": "200-2000-20-2-20000-2", "name": "Adams", "salary": 75000, "married": true, "security_id": "alphanumeric-object-id-for-employee-2" } }
Tworzenie pola zabezpieczeń
W indeksie wyszukiwania w kolekcji pól potrzebne jest jedno pole zawierające tożsamość grupy lub użytkownika, podobne do fikcyjnego pola "security_id" w poprzednim przykładzie.
Dodaj pole zabezpieczeń jako
Collection(Edm.String).Ustaw atrybut pola
filterablena wartośćtrue.Ustaw atrybut pola
retrievablenafalse, aby nie był zwracany jako część odpowiedzi wyszukiwania.Indeksy wymagają klucza dokumentu. Pole "file_id" spełnia to wymaganie.
Indeksy powinny również zawierać zawartość z możliwością wyszukiwania i pobierania. Pola "file_name" i "file_description" reprezentują to w tym przykładzie.
Poniższy schemat indeksu spełnia wymagania dotyczące pól. Dokumenty indeksujące w dokumentacji IQ usługi Foundry powinny zawierać wartości dla wszystkich tych pól, w tym .
group_idsZapytanie zwraca dokument zfile_namesecured_file_b, jeśli jego filtr bezpieczeństwa zawieragroup_id1lubgroup_id2.POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2026-10-01 { "name": "securedfiles", "fields": [ {"name": "file_id", "type": "Edm.String", "key": true, "searchable": false }, {"name": "file_name", "type": "Edm.String", "searchable": true }, {"name": "file_description", "type": "Edm.String", "searchable": true }, {"name": "group_ids", "type": "Collection(Edm.String)", "filterable": true, "retrievable": false } ] }
Note
Ustawienie retrievable na false uniemożliwia zwracanie group_ids jako części dokumentu w wynikach wyszukiwania. Nie jest to mechanizm maskowania treści ani zabezpieczeń na poziomie pól. W tym wzorcu autoryzacja na poziomie dokumentu jest wymuszana przez zastosowanie filtru zabezpieczeń do każdego zapytania. Nie należy polegać wyłącznie na retrievable w celu ochrony poufnych informacji przed wszystkimi funkcjami zapytań i formatami odpowiedzi.
Wysyłanie danych do indeksu za pomocą interfejsu API REST
Zapełnij indeks wyszukiwania dokumentami, które udostępniają wartości dla każdego pola w kolekcji pól, w tym wartości pola zabezpieczeń. Usługa Foundry IQ nie udostępnia interfejsów API ani funkcji konkretnie do wypełniania pola zabezpieczeń. Jednak kilka przykładów wymienionych na końcu tego artykułu wyjaśnia techniki wypełniania tego pola.
W usłudze Foundry IQ metody ładowania danych to:
- Pojedyncza operacja wypychania lub ściągania (indeksatora), która importuje dokumenty wypełnione wszystkimi polami
- Wiele operacji wypychania lub ściągania. Tak długo, jak operacje importu pomocniczego są przeznaczone dla odpowiedniego identyfikatora dokumentu, można ładować pola indywidualnie za pomocą wielu importów.
Poniższy przykład przedstawia pojedyncze żądanie HTTP POST do kolekcji dokumentów punktu końcowego adresu URL indeksu (zobacz Dokumenty — indeks). Treść żądania HTTP to renderowanie JSON dokumentów do indeksowania:
POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2026-10-01
{
"value": [
{
"@search.action": "upload",
"file_id": "1",
"file_name": "secured_file_a",
"file_description": "File access is restricted to Human Resources.",
"group_ids": ["group_id1"]
},
{
"@search.action": "upload",
"file_id": "2",
"file_name": "secured_file_b",
"file_description": "File access is restricted to Human Resources and Recruiting.",
"group_ids": ["group_id1", "group_id2"]
},
{
"@search.action": "upload",
"file_id": "3",
"file_name": "secured_file_c",
"file_description": "File access is restricted to Operations and Logistics.",
"group_ids": ["group_id5", "group_id6"]
}
]
}
Jeśli musisz zaktualizować istniejący dokument zawierający listę grup, możesz skorzystać z akcji merge lub mergeOrUpload.
{
"value": [
{
"@search.action": "mergeOrUpload",
"file_id": "3",
"group_ids": ["group_id7", "group_id8", "group_id9"]
}
]
}
Stosowanie filtru zabezpieczeń w zapytaniu
Aby przyciąć dokumenty na group_ids podstawie dostępu, należy wydać zapytanie wyszukiwania z filtrem group_ids/any(g:search.in(g, 'group_id1, group_id2,...')) , w którym "group_id1, group_id2,..." to grupy, do których należy wystawca żądania wyszukiwania.
Ten filtr pasuje do wszystkich dokumentów, dla których group_ids pole zawiera jeden z podanych identyfikatorów.
Aby uzyskać szczegółowe informacje na temat wyszukiwania dokumentów przy użyciu funkcji IQ rozwiązania Foundry, możesz przeczytać artykuł Search Documents (Przeszukaj dokumenty).
W tym przykładzie pokazano, jak skonfigurować zapytanie przy użyciu żądania POST.
Wydaj żądanie HTTP POST, określając filtr w treści żądania:
POST https://[service name].search.windows.net/indexes/securedfiles/docs/search?api-version=2026-10-01
{
"filter":"group_ids/any(g:search.in(g, 'group_id1, group_id2'))"
}
Należy odzyskać dokumenty, w przypadku których group_ids zawiera "group_id1" lub "group_id2". Innymi słowy, uzyskujesz dokumenty, do których wystawca żądań ma dostęp do odczytu.
{
[
{
"@search.score":1.0,
"file_id":"1",
"file_name":"secured_file_a",
},
{
"@search.score":1.0,
"file_id":"2",
"file_name":"secured_file_b"
}
]
}
Następne kroki
W tym artykule opisano wzorzec filtrowania wyników na podstawie tożsamości użytkownika i search.in() funkcji. Możesz użyć tej funkcji, aby przekazać identyfikatory główne dla użytkownika składającego żądanie, aby dopasować je do identyfikatorów głównych skojarzonych z każdym dokumentem docelowym. Po obsłużeniu żądania wyszukiwania funkcja search.in filtruje wyniki wyszukiwania, dla których użytkownik nie ma żadnych uprawnień do odczytu. Identyfikatory podmiotów zabezpieczeń mogą reprezentować takie elementy jak grupy zabezpieczeń, role, a nawet tożsamość użytkownika.
Aby uzyskać więcej przykładów, demonstracji i filmów: