Dokumentacja interfejsu API REST usługi Azure AI Search

  • Artykuł

azure AI Search (wcześniej znana jako Azure Cognitive Search) to w pełni zarządzana usługa wyszukiwania w chmurze, która zapewnia pobieranie informacji za pośrednictwem zawartości należącej do użytkownika.

Interfejsy API REST płaszczyzny danych służą do indeksowania i wykonywania zapytań oraz są udokumentowane w tej sekcji.

Operacje płaszczyzny sterowania na potrzeby administrowania usługami są omówione w osobnym interfejsie API REST usługi Management.

Dokumentacja wersji interfejsu API

Dokumentacja interfejsu API REST jest teraz wersjonowana. Po otwarciu strony dokumentacji interfejsu API nad spisem treści pojawi się selektor wersji. Upewnij się, że dokumentacja interfejsu API pochodzi z folderu Reference > Data Plane.

Zrzut ekranu przedstawiający selektor wersji.

Kluczowe pojęcia

Usługa Azure AI Search ma pojęcia dotyczące usług wyszukiwania , indeksów , dokumentów , indeksatorów źródeł danych, zestawów umiejętności i map synonimów .

  • Usługa wyszukiwania hostuje indeksy, indeksatory, źródła danych, zestawy umiejętności i mapy synonimów jako obiekty najwyższego poziomu.
  • Indeks wyszukiwania zapewnia trwały magazyn dokumentów wyszukiwania. Dokumenty wyszukiwania to dane, określone jako kolekcja pól, ładowane ze źródeł zewnętrznych i wypychane do indeksu, aby umożliwić wyszukiwanie.
  • Indeksator wyszukiwania dodaje automatyzację, odczytuje dane w formatach natywnych i serializuje je w formacie JSON.
  • Indeksator ma źródło danych i wskazuje indeks.
  • Indeksator może również mieć zestaw umiejętności, który dodaje wzbogacanie sztucznej inteligencji i zintegrowanej wektoryzacji do potoku indeksowania. Zestawy umiejętności są zawsze dołączane do indeksatora. Wywołują one uczenie maszynowe w celu wyodrębniania lub fragmentowania tekstu, wektoryzacji zawartości, wnioskowania funkcji lub dodawania struktury do zawartości w celu ulepszenia indeksowania przez usługę wyszukiwania.

W sumie można utworzyć następujące obiekty w usłudze wyszukiwania:

Obiektów Opis
Źródła danych Połączenie ze źródłem danych używane przez indeksator do pobierania i odświeżania dokumentów na potrzeby indeksowania. Źródła danych mają type. Możesz użyć połączeń udostępnianych przez firmę Microsoft dla platformy Azure lub łączników partnerskich. Aby uzyskać pełną listę, zobacz galerię źródeł danych .
Dokumentów Koncepcyjnie dokument jest jednostką w indeksie. Mapowanie tej koncepcji na bardziej znane odpowiedniki bazy danych: indeks wyszukiwania odpowiada tabeli, a dokumenty są w przybliżeniu równoważne wierszom w tabeli. Dokumenty istnieją tylko w indeksie i są pobierane tylko za pośrednictwem zapytań przeznaczonych dla kolekcji dokumentów (/docs) indeksu. Wszystkie operacje wykonywane w kolekcji, takie jak przekazywanie, scalanie, usuwanie lub wykonywanie zapytań dotyczących dokumentów odbywa się w kontekście pojedynczego indeksu, dlatego operacje dokumentu w formacie adresu URL zawsze zawierają /indexes/[index name]/docs dla danej nazwy indeksu.
Indeksy Indeks jest przechowywany w usłudze wyszukiwania i wypełniany dokumentami JSON, które są indeksowane i tokenizowane na potrzeby pobierania informacji. Kolekcja pól indeksu definiuje strukturę dokumentu wyszukiwania. Pola mają nazwę, typy danych i atrybuty, które określają użycie. Na przykład pola searchable są używane w wyszukiwaniu pełnotekstowym, a tym samym tokenizowane podczas indeksowania. Indeks definiuje również inne konstrukcje, takie jak profile oceniania na potrzeby dostrajania istotności, sugestory, konfiguracje semantyczne i analizatory niestandardowe.
Indeksatory Indeksatory zapewniają automatyzację indeksowania. Indeksator łączy się ze źródłem danych, odczytuje dane i przekazuje je do aparatu wyszukiwania w celu indeksowania do docelowego indeksu wyszukiwania. Indeksatory odczytują ze źródła zewnętrznego przy użyciu informacji o połączeniu w źródle danych i serializują dane przychodzące do dokumentów wyszukiwania JSON. Oprócz źródła danych indeksator wymaga również indeksu. Indeks określa pola i atrybuty dokumentów wyszukiwania.
Zestawy umiejętności Zestaw umiejętności dodaje zewnętrzne kroki przetwarzania do wykonywania indeksatora i służy do stosowania modeli sztucznej inteligencji lub uczenia głębokiego do analizowania lub przekształcania zawartości w celu zwiększenia możliwości wyszukiwania w indeksie. Zawartość zestawu umiejętności to co najmniej jedna umiejętności, którą można wbudowanych umiejętności utworzonych przez firmę Microsoft, umiejętności niestandardowe lub kombinację obu tych umiejętności. Istnieją wbudowane umiejętności do analizy obrazów, w tym rozpoznawania znaków OCR i przetwarzania języka naturalnego. Inne przykłady wbudowanych umiejętności obejmują rozpoznawanie jednostek, wyodrębnianie kluczowych fraz, dzielenie tekstu na strony logiczne, między innymi. Zestaw umiejętności jest obiektem autonomicznym wysokiego poziomu, który istnieje na poziomie równoważnym indeksom, indeksatorom i źródłom danych, ale działa tylko w ramach przetwarzania indeksatora. Jako obiekt wysokiego poziomu można zaprojektować zestaw umiejętności raz, a następnie odwołać się do niego w wielu indeksatorach.
Mapy synonimów Mapa synonimów to obiekt poziomu usługi, który zawiera synonimy zdefiniowane przez użytkownika. Ten obiekt jest utrzymywany niezależnie od indeksów wyszukiwania. Po przekazaniu można wskazać dowolne pole z możliwością wyszukiwania do mapy synonimów (jedno na pole).

Uprawnienia i kontrola dostępu

Uwierzytelnianie oparte na kluczach lub oparte na rolach można użyć za pomocą identyfikatora Entra firmy Microsoft.

  • uwierzytelnianie oparte na kluczach opiera się na kluczach interfejsu API generowanych dla usługi wyszukiwania. Posiadanie prawidłowego klucza ustanawia relację zaufania dla poszczególnych żądań między aplikacją wysyłającą żądanie a usługą, która go obsługuje. Klucz interfejsu API administratora można użyć dla operacji odczytu i zapisu lub klucza interfejsu API zapytań w celu uzyskania dostępu do odczytu do kolekcji dokumentów indeksu wyszukiwania.

  • uwierzytelnianie identyfikatora Entra firmy Microsoft i kontrolę dostępu opartą na rolach wymaga posiadania dzierżawy w usłudze Microsoft Entra ID z jednostkami zabezpieczeń i przypisaniami ról. Członkowie następujących ról mają dostęp do płaszczyzny danych. Role niestandardowe można tworzyć, jeśli wbudowane role są niewystarczające.

    Rola Dostęp
    Współautor usługi wyszukiwania Dostęp do obiektów, ale brak dostępu do zawartości indeksu. Ta rola tworzy indeks wyszukiwania i inne obiekty najwyższego poziomu, ale nie może wykonywać zapytań dotyczących indeksu wyszukiwania ani dodawać, usuwać ani aktualizować dokumentów w indeksie wyszukiwania. Ta rola dotyczy deweloperów, którzy tworzą, aktualizują i usuwają definicje obiektów. Jest to również przeznaczone dla administratorów, którzy muszą zarządzać obiektami, ale bez możliwości wyświetlania lub uzyskiwania dostępu do danych obiektów.
    Współautor indeksu danych wyszukiwania Dostęp do odczytu i zapisu do zawartości indeksu. Ta rola jest dla deweloperów lub właścicieli indeksów, którzy muszą importować, odświeżać lub wykonywać zapytania dotyczące kolekcji dokumentów indeksu.
    Czytnik indeksów danych wyszukiwania Odczyt dostępu do zawartości indeksu. Ta rola dotyczy aplikacji i użytkowników, którzy uruchamiają zapytania.

W przypadku korzystania z ról w połączeniu aplikacja kliencka przedstawia token elementu nośnego w nagłówku autoryzacji. Aby uzyskać pomoc dotyczącą konfigurowania, zobacz Autoryzuj dostęp do aplikacji wyszukiwania przy użyciu Microsoft Entra ID.

Możesz wyłączyć uwierzytelnianie oparte na kluczach lub uwierzytelnianie oparte na rolach. Jeśli wyłączysz uwierzytelnianie oparte na rolach, dotyczy to tylko operacji płaszczyzny danych. Operacje płaszczyzny sterowania, takie jak administrowanie usługami, zawsze używają uwierzytelniania opartego na rolach. Aby uzyskać szczegółowe informacje, zobacz uwierzytelnianie identyfikatora entra firmy Microsoft i kontrolę dostępu opartą na rolach dla usługi Azure AI Search.

Wywoływanie interfejsów API

Interfejsy API opisane w tej sekcji zapewniają dostęp do operacji dotyczących danych wyszukiwania, takich jak tworzenie indeksu i populacja, przekazywanie dokumentów i zapytania. Podczas wywoływania interfejsów API należy pamiętać o następujących kwestiach:

  • Żądania muszą być wystawiane za pośrednictwem protokołu HTTPS (na domyślnym porcie 443).

  • Identyfikatory URI żądań muszą zawieraćapi-version . Wartość musi być ustawiona na obsługiwaną wersję sformatowaną, jak pokazano w tym przykładzie: GET https://[search service name].search.windows.net/indexes?api-version=2023-11-01

  • nagłówki żądań muszą zawierać api-key lub token elementu nośnego dla uwierzytelnionych połączeń. Opcjonalnie możesz ustawić nagłówek Akceptuj http. Jeśli nagłówek typu zawartości nie jest ustawiony, przyjmuje się, że wartość domyślna to application/json.

Zobacz też