Dokumentacja interfejsu API REST usługi Azure AI Search
Usługa 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 na temat zawartości należącej do użytkownika.
Interfejsy API REST płaszczyzny danych są używane do indeksowania i wykonywania zapytań przepływów pracy. Są one udokumentowane w tej sekcji.
Dostęp do operacji płaszczyzny sterowania jest uzyskiwany za pośrednictwem oddzielnego interfejsu API REST zarządzania.
Dokumentacja interfejsu API w wersji
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 Płaszczyzna danych referencyjnych>.
Kluczowe pojęcia
Usługa Azure AI Search zawiera 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 indeks, 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. Search dokumenty to dane, wyrażone 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 sztucznejinteligencji i zintegrowaną wektoryzację do potoku indeksowania. Zestawy umiejętności są zawsze dołączane do indeksatora. Wywołują one uczenie maszynowe, aby wyodrębniać lub fragmentować tekst, wektoryzować zawartość, wnioskować funkcje lub dodawać strukturę do zawartości, aby można było indeksować ją przez usługę wyszukiwania.
W sumie można utworzyć następujące obiekty w usłudze wyszukiwania:
| Obiekty | 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ą typ type. Możesz użyć połączeń udostępnianych przez firmę Microsoft dla platformy Azure lub łączników innych firm za pośrednictwem partnerów. Aby uzyskać pełną listę, zobacz Galeria źródeł danych . |
| Dokumenty | 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, więc operacje dokumentu w formacie adresu URL będą zawsze uwzględniane /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ą sposób ich użycia. Na przykład searchable pola 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. |
| Indexers (Indeksatory) | Indeksatory zapewniają automatyzację indeksowania. Indeksator łączy się ze źródłem danych, odczytuje je w danych i przekazuje je do wyszukiwarki w celu indeksowania do docelowego indeksu wyszukiwania. Indeksatory odczytują dane z zewnętrznego źródła 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 jest zwykle używany do dodawania modeli sztucznej inteligencji lub uczenia głębokiego do analizowania lub przekształcania zawartości, aby umożliwić wyszukiwanie w indeksie. Zawartość zestawu umiejętności to co najmniej jeden zestaw umiejętności, który może być wbudowanymi umiejętnościami utworzonymi przez firmę Microsoft, umiejętnościami niestandardowymi lub kombinacją obu tych umiejętności. Istnieją wbudowane umiejętności do analizy obrazów, w tym OCR i przetwarzania języka naturalnego. Inne przykłady wbudowanych umiejętności to między innymi rozpoznawanie jednostek, wyodrębnianie kluczowych fraz, dzielenie tekstu na strony logiczne. Zestaw umiejętności to obiekt autonomiczny wysokiego poziomu, który istnieje na poziomie równoważnym z indeksami, indeksatorami i źródłami 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 na poziomie 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 (po jednym dla każdego pola). |
Uprawnienia i kontrola dostępu
Uwierzytelnianie oparte na kluczach lub oparte na rolach można użyć za pośrednictwem Tożsamość Microsoft Entra.
Uwierzytelnianie oparte na kluczach opiera się na kluczach interfejsu API generowanych dla usługi wyszukiwania. Prawidłowy klucz ustanawia relację zaufania dla danego żądania między aplikacją wysyłającą żądanie i usługą, która je obsługuje. Klucz interfejsu API Administracja służy do operacji odczytu i zapisu lub klucza interfejsu API zapytań w celu uzyskania dostępu do odczytu do kolekcji dokumentów indeksu wyszukiwania.
Tożsamość Microsoft Entra uwierzytelnianie i kontrola dostępu oparta na rolach wymaga ustanowienia dzierżawy w Tożsamość Microsoft Entra z przypisaniami zabezpieczeń i rolami. 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 Access Współautor usługi Search Dostęp do obiektów, ale brak dostępu do zawartości indeksu. Ta rola nie może wykonywać zapytań dotyczących indeksu wyszukiwania ani dodawać, usuwać ani aktualizować dokumentów w indeksie wyszukiwania. Ta rola jest przeznaczony 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 Search 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 Search Dostęp do odczytu do zawartości indeksu. Ta rola jest rolą dla aplikacji i użytkowników, którzy uruchamiają zapytania.
W przypadku korzystania z ról w połączeniu aplikacja kliencka prezentuje token elementu nośnego w nagłówku autoryzacji. Aby uzyskać pomoc dotyczącą konfigurowania, zobacz Autoryzowanie dostępu do aplikacji wyszukiwania przy użyciu Tożsamość Microsoft Entra.
Możesz wyłączyć uwierzytelnianie oparte na kluczach lub uwierzytelnianie oparte na rolach. Jeśli wyłączysz uwierzytelnianie oparte na rolach, niektóre wbudowane role nadal będą miały dostęp. Aby uzyskać szczegółowe informacje, zobacz Tożsamość Microsoft Entra uwierzytelnianie 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 na 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ć wersję interfejsu API. 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=2020-06-30Nagłówki żądań muszą zawierać klucz api-key lub token elementu nośnego dla uwierzytelnionych połączeń. Opcjonalnie możesz ustawić nagłówek Accept HTTP (Akceptuj nagłówek HTTP). Jeśli nagłówek typu zawartości nie jest ustawiony, przyjmuje się, że wartość domyślna to
application/json.