Szybki start: wyszukiwanie tekstu przy użyciu interfejsu REST
Interfejsy API REST w usłudze Azure AI Search zapewniają programowy dostęp do wszystkich jego funkcji, w tym funkcji w wersji zapoznawczej, i są one łatwym sposobem na poznanie sposobu działania funkcji. Z tego przewodnika Szybki start dowiesz się, jak wywoływać interfejsy API REST wyszukiwania w celu tworzenia, ładowania i wykonywania zapytań względem indeksu wyszukiwania w usłudze Azure AI Search.
Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.
Wymagania wstępne
- Program Visual Studio Code z klientem REST.
- Azure AI Search. Utwórz lub znajdź istniejący zasób usługi Azure AI Search w ramach bieżącej subskrypcji. W tym przewodniku Szybki start możesz skorzystać z bezpłatnej usługi.
Pobieranie plików
Pobierz przykład REST z usługi GitHub, aby wysłać żądania w tym przewodniku Szybki start. Aby uzyskać więcej informacji, zobacz Pobieranie plików z usługi GitHub.
Możesz również uruchomić nowy plik w systemie lokalnym i ręcznie utworzyć żądania, korzystając z instrukcji w tym artykule.
Kopiowanie klucza i adresu URL usługi wyszukiwania
Wywołania REST wymagają punktu końcowego usługi wyszukiwania i klucza interfejsu API dla każdego żądania. Te wartości można uzyskać w witrynie Azure Portal.
Zaloguj się w witrynie Azure Portal. Następnie przejdź do strony Przegląd usługi wyszukiwania i skopiuj adres URL. Przykładowy punkt końcowy może wyglądać podobnie jak
https://mydemo.search.windows.net.Wybierz pozycję Ustawienia> Klucze, a następnie skopiuj klucz administratora. Administracja klucze służą do dodawania, modyfikowania i usuwania obiektów. Istnieją dwa zamienne klucze administratora. Skopiuj jedną z nich.
Konfigurowanie programu Visual Studio Code
Jeśli nie znasz klienta REST programu Visual Studio Code, ta sekcja zawiera konfigurację, aby można było wykonać zadania w tym przewodniku Szybki start.
Uruchom program Visual Studio Code i wybierz kafelek Rozszerzenia .
Wyszukaj klienta REST i wybierz pozycję Zainstaluj.
Otwórz lub utwórz nowy plik o nazwie z
.restrozszerzeniem lub.http.Wklej poniższy przykład. Zastąp podstawowy adres URL i klucz interfejsu API wartościami skopiowanymi wcześniej.
@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE @apiKey = PUT-YOUR-SEARCH-SERVICE-API-KEY-HERE ### List existing indexes by name GET {{baseUrl}}/indexes?api-version=2023-11-01&$select=name HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}Wybierz pozycję Wyślij wniosek. Odpowiedź powinna pojawić się w sąsiednim okienku. Jeśli masz istniejące indeksy, są one wyświetlane. W przeciwnym razie lista jest pusta. Jeśli kod HTTP to
200 OK, możesz przystąpić do następnych kroków.
Najważniejsze kwestie:
- Parametry są określane przy użyciu prefiksu
@. ###wyznacza wywołanie REST. Następny wiersz zawiera żądanie, które musi zawieraćHTTP/1.1element .Send requestpowinien pojawić się powyżej żądania.
- Parametry są określane przy użyciu prefiksu
Tworzenie indeksu
Dodaj drugie żądanie do .rest pliku. Tworzenie indeksu (REST) tworzy indeks wyszukiwania i konfiguruje fizyczne struktury danych w usłudze wyszukiwania.
Wklej poniższy przykład, aby utworzyć
hotels-quickstartindeks w usłudze wyszukiwania.### Create a new index POST {{baseUrl}}/indexes?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "name": "hotels-quickstart", "fields": [ {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true}, {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false}, {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"}, {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true}, {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true}, {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true}, {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true}, {"name": "Address", "type": "Edm.ComplexType", "fields": [ {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true}, {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true} ] } ] }Wybierz pozycję Wyślij wniosek. Powinna zostać wyświetlona
HTTP/1.1 201 Createdodpowiedź, a treść odpowiedzi powinna zawierać reprezentację JSON schematu indeksu.Jeśli wystąpi
Header name must be a valid HTTP token ["{"]błąd, upewnij się, że istnieje pusty wiersz międzyapi-keyi treścią żądania. Jeśli otrzymasz protokół HTTP 504, sprawdź, czy adres URL określa protokół HTTPS. Jeśli zobaczysz odpowiedź 400 lub 404 protokołu HTTP, sprawdź treść żądania, aby zweryfikować, czy nie było żadnych błędów podczas kopiowania i wklejania. Protokół HTTP 403 zwykle wskazuje problem z kluczem interfejsu API. Jest to nieprawidłowy klucz lub problem ze składnią sposobu określenia klucza interfejsu API.Masz teraz kilka żądań w pliku. Pamiętaj, że
###uruchamia nowe żądanie, a każde żądanie jest uruchamiane niezależnie.
Informacje o definicji indeksu
W schemacie indeksu kolekcja pól definiuje strukturę dokumentu. Każdy przekazany dokument musi mieć te pola. Każde pole musi być przypisane do typu danych modelu danych JEDNOSTKI (EDM). Pola ciągów są używane w wyszukiwaniu pełnotekstowym. Jeśli chcesz, aby dane liczbowe można wyszukiwać, upewnij się, że typ danych to Edm.String. Inne typy danych, takie jak Edm.Int32 można filtrować, sortować, tworzyć aspekty i pobierać, ale nie można wyszukiwać pełnotekstowego.
Atrybuty w polu określają dozwolone akcje. Interfejsy API REST domyślnie zezwalają na wiele akcji. Na przykład wszystkie ciągi można wyszukiwać i pobierać domyślnie. W przypadku interfejsów API REST atrybuty mogą być dostępne tylko wtedy, gdy trzeba wyłączyć zachowanie.
{
"name": "hotels-quickstart",
"fields": [
{"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
{"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
{"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
{"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
{"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
{"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
{"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
{"name": "Address", "type": "Edm.ComplexType",
"fields": [
{"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true},
{"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
]
}
]
}
Ładowanie dokumentów
Tworzenie i ładowanie indeksu to oddzielne kroki. W usłudze Azure AI Search indeks zawiera wszystkie dane z możliwością wyszukiwania i zapytania uruchamiane w usłudze wyszukiwania. W przypadku wywołań REST dane są udostępniane jako dokumenty JSON. Użyj interfejsu API REST indeksu dokumentów dla tego zadania.
Identyfikator URI został rozszerzony w celu uwzględnienia docs kolekcji i index operacji.
Wklej poniższy przykład, aby przekazać dokumenty JSON do indeksu wyszukiwania.
### Upload documents POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "value": [ { "@search.action": "upload", "HotelId": "1", "HotelName": "Secret Point Motel", "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.", "Category": "Boutique", "Tags": [ "pool", "air conditioning", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1970-01-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "677 5th Ave", "City": "New York", "StateProvince": "NY", "PostalCode": "10022", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "2", "HotelName": "Twin Dome Motel", "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.", "Category": "Boutique", "Tags": [ "pool", "free wifi", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1979-02-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "140 University Town Center Dr", "City": "Sarasota", "StateProvince": "FL", "PostalCode": "34243", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "3", "HotelName": "Triple Landscape Hotel", "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.", "Category": "Resort and Spa", "Tags": [ "air conditioning", "bar", "continental breakfast" ], "ParkingIncluded": true, "LastRenovationDate": "2015-09-20T00:00:00Z", "Rating": 4.80, "Address": { "StreetAddress": "3393 Peachtree Rd", "City": "Atlanta", "StateProvince": "GA", "PostalCode": "30326", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "4", "HotelName": "Sublime Cliff Hotel", "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.", "Category": "Boutique", "Tags": [ "concierge", "view", "24-hour front desk service" ], "ParkingIncluded": true, "LastRenovationDate": "1960-02-06T00:00:00Z", "Rating": 4.60, "Address": { "StreetAddress": "7400 San Pedro Ave", "City": "San Antonio", "StateProvince": "TX", "PostalCode": "78216", "Country": "USA" } } ] }Wybierz pozycję Wyślij wniosek. W ciągu kilku sekund powinna zostać wyświetlona odpowiedź HTTP 201 w sąsiednim okienku.
Jeśli otrzymasz odpowiedź 207, przekazanie co najmniej jednego dokumentu nie powiodło się. Jeśli otrzymasz odpowiedź 404, wystąpił błąd składniowy w nagłówku lub w treści żądania. Sprawdź, czy zmieniono punkt końcowy tak, aby zawierał
/docs/indexelement .
Uruchamianie zapytań
Teraz, gdy dokumenty są ładowane, możesz wysyłać zapytania względem nich przy użyciu funkcji Dokumenty — wyszukiwanie w wpisie (REST).
Identyfikator URI jest rozszerzony w celu uwzględnienia wyrażenia zapytania, które jest określane przy użyciu /docs/search operatora .
Wklej poniższy przykład, aby wysłać zapytanie do indeksu wyszukiwania. Następnie wybierz pozycję Wyślij żądanie. Żądanie wyszukiwania tekstu zawsze zawiera
searchparametr. Ten przykład zawiera opcjonalnysearchFieldsparametr, który ogranicza wyszukiwanie tekstu do określonych pól.### Run a query POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "search": "lake view", "select": "HotelId, HotelName, Tags, Description", "searchFields": "Description, Tags", "count": true }Przejrzyj odpowiedź w sąsiednim okienku. Powinna istnieć liczba wskazująca liczbę dopasowań znalezionych w indeksie, wynik wyszukiwania wskazujący istotność i wartości dla każdego pola wymienionego w instrukcji
select.{ "@odata.context": "https://my-demo.search.windows.net/indexes('hotels-quickstart')/$metadata#docs(*)", "@odata.count": 1, "value": [ { "@search.score": 0.6189728, "HotelId": "4", "HotelName": "Sublime Cliff Hotel", "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.", "Tags": [ "concierge", "view", "24-hour front desk service" ] } ] }
Pobieranie właściwości indeksu
Możesz również użyć funkcji Pobierz statystyki , aby wykonać zapytanie dotyczące liczby dokumentów i rozmiaru indeksu.
Wklej poniższy przykład, aby wysłać zapytanie do indeksu wyszukiwania. Następnie wybierz pozycję Wyślij żądanie.
### Get index statistics GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}Przejrzyj odpowiedź. Ta operacja jest łatwym sposobem uzyskania szczegółowych informacji o magazynie indeksów.
{ "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics", "documentCount": 4, "storageSize": 34707, "vectorIndexSize": 0 }
Czyszczenie zasobów
Jeśli pracujesz w ramach własnej subskrypcji, dobrym pomysłem po zakończeniu projektu jest sprawdzenie, czy dalej potrzebujesz utworzonych zasobów. Uruchomione zasoby mogą generować koszty. Zasoby możesz usuwać pojedynczo lub jako grupę zasobów, usuwając cały zestaw zasobów.
Zasoby można znaleźć w portalu i zarządzać nimi, korzystając z linku Wszystkie zasoby lub Grupy zasobów w okienku po lewej stronie.
Możesz również wypróbować następujące DELETE polecenie:
### Delete an index
DELETE {{baseUrl}}/indexes/hotels-quickstart?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
Następny krok
Teraz, gdy znasz klienta REST i wykonujesz wywołania REST do usługi Azure AI Search, wypróbuj kolejny przewodnik Szybki start, który demonstruje obsługę wektorów.