Dokumentacja interfejsu API REST usługi Azure AI Search
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żywane do indeksowania i wykonywania zapytań przepływów pracy. Są one udokumentowane w tej sekcji.
Operacje płaszczyzny sterowania na potrzeby administrowania usługami są omówione w osobnym interfejsie API REST zarządzania.
Dokumentacja wersji interfejsu API
Dokumentacja interfejsu API REST jest teraz w wersji. Po otwarciu strony referencyjnej interfejsu API selektor wersji pojawi się nad spisem treści. Upewnij się, że dokumentacja interfejsu API pochodzi z folderu Płaszczyzna danych referencyjnych>.
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 indeks, indeksatory, źródła danych, zestawy umiejętności i synonimy mapy jako obiekty najwyższego poziomu.
- Indeks wyszukiwania zapewnia trwały magazyn dokumentów wyszukiwania. Dokumenty wyszukiwania to dane, wyrażane jako kolekcja pól, ładowane ze źródeł zewnętrznych i wypychane do indeksu, aby można je było przeszukiwać.
- Indeksator wyszukiwania dodaje automatyzację, odczytywanie danych w formatach natywnych i serializowanie ich 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 w celu wyodrębniania lub fragmentowania tekstu, wektoryzacji zawartości, wnioskowania funkcji lub dodawania struktury do zawartości w celu indeksowania jej 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 źródła danych używane przez indeksator do pobierania i odświeżania dokumentów na potrzeby indeksowania. Źródła danych mają element type. Połączenia udostępniane przez firmę Microsoft można używać 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 jest równa 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ń do 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 w celu 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 go do wyszukiwarki do indeksowania w indeksie wyszukiwania docelowego. Indeksatory odczytywane 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 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 jedno umiejętności, które mogą być wbudowane umiejętności utworzone przez firmę Microsoft, umiejętności niestandardowe lub kombinację obu tych umiejętności. Wbudowane umiejętności istnieją do analizy obrazów, w tym 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łam 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 zawierający 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 (jeden na pole). |
Uprawnienia i kontrola dostępu
Uwierzytelnianie oparte na kluczach lub oparte na rolach można użyć za pomocą 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 umożliwia operacje odczytu i zapisu lub klucz 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 posiadania ustalonej 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 utworzyć, jeśli wbudowane role są niewystarczające.
Rola Access Współautor usługi wyszukiwania Dostęp do obiektów, ale nie ma dostępu do zawartości indeksu. Ta rola tworzy indeks wyszukiwania i inne obiekty najwyższego poziomu, ale nie może wykonywać zapytań względem indeksu wyszukiwania ani dodawać, usuwać ani aktualizować dokumentów w indeksie wyszukiwania. Ta rola jest przeznaczona dla 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 ani 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 przeznaczona 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 Dostęp do odczytu do zawartości indeksu. Ta rola jest przeznaczona dla 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 tej funkcji, 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, dotyczy 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 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=2023-11-01Nagłówki żądań muszą zawierać klucz 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, zakłada się, że wartość domyślna to
application/json.