Filtry zabezpieczeń na potrzeby przycinania wyników w usłudze Wyszukiwanie AI platformy Azure

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, usługa 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:

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.

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.

1. Dodaj pole zabezpieczeń jako Collection(Edm.String).

2. Ustaw atrybut pola filterable na wartośćtrue.

3. Ustaw atrybut pola retrievable na false , aby nie był zwracany jako część odpowiedzi wyszukiwania.

4. Indeksy wymagają klucza dokumentu. Pole "file_id" spełnia to wymaganie.

5. 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 indeksowane w usłudze Wyszukiwanie AI platformy Azure powinny mieć wartości we wszystkich tych polach, w tym group_ids. Zapytanie zwraca dokument z file_namesecured_file_b, jeśli jego filtr bezpieczeństwa zawiera group_id1 lub group_id2.

   POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2026-04-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 }
        ]
    }
   

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 Wyszukiwanie AI platformy Azure nie oferuje interfejsów API ani funkcji do specjalnego 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 Wyszukiwanie AI platformy Azure 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-04-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 usługi Wyszukiwanie AI platformy Azure, możesz przeczytać artykuł Search Documents (Wyszukiwanie dokumentów).

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-04-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:

• Wprowadzenie do zabezpieczeń dokumentów czatu w języku Python
• Konfigurowanie opcjonalnej kontroli dostępu na poziomie dokumentu i logowania (modyfikacje aplikacji AzureOpenAIDemo)
• Wideo: Zabezpieczanie inteligentnych aplikacji za pomocą firmy Microsoft Entra