Szybki start: wyszukiwanie słów kluczowych przy użyciu interfejsu REST

Artykuł
10/31/2024

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. Instrukcje można znaleźć w temacie 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.

Pobieranie punktu końcowego usługi wyszukiwania

Punkt końcowy usługi wyszukiwania można znaleźć w witrynie Azure Portal.

Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.
Na stronie głównej Przegląd znajdź adres URL. Przykładowy punkt końcowy może wyglądać podobnie jak https://mydemo.search.windows.net.

Wklejasz ten punkt końcowy do .rest pliku lub .http w późniejszym kroku.

Konfigurowanie dostępu

Żądania do punktu końcowego wyszukiwania muszą być uwierzytelnione i autoryzowane. W tym zadaniu można użyć kluczy interfejsu API lub ról. Klucze są łatwiejsze do rozpoczęcia od, ale role są bezpieczniejsze.

W przypadku połączenia opartego na rolach poniższe instrukcje zawierają połączenie z usługą Azure AI Search w ramach tożsamości, a nie tożsamością aplikacji klienckiej.

Opcja 1. Używanie kluczy

Wybierz pozycję Klucze ustawień>, a następnie skopiuj klucz administratora. Klucze administracyjne służą do dodawania, modyfikowania i usuwania obiektów. Istnieją dwa zamienne klucze administratora. Skopiuj jedną z nich. Aby uzyskać więcej informacji, zobacz Nawiązywanie połączenia z usługą Azure AI Search przy użyciu uwierzytelniania klucza.

Wklejasz ten klucz do .rest pliku lub .http w późniejszym kroku.

Opcja 2. Używanie ról

Upewnij się, że usługa wyszukiwania jest skonfigurowana pod kątem dostępu opartego na rolach. Aby uzyskać dostęp dewelopera, musisz mieć wstępnie skonfigurowane przypisania ról. Przypisania ról muszą udzielać uprawnień do tworzenia, ładowania i wykonywania zapytań względem indeksu wyszukiwania.

W tej sekcji uzyskaj osobisty token tożsamości przy użyciu interfejsu wiersza polecenia platformy Azure, programu Azure PowerShell lub witryny Azure Portal.

Zaloguj się do interfejsu wiersza polecenia platformy Azure.
```
az login
```

Pobierz osobisty token tożsamości.

az account get-access-token --scope https://search.azure.com/.default

Wklejasz osobisty token tożsamości do .rest pliku lub .http w późniejszym kroku.

Uwaga

W tej sekcji założono, że używasz klienta lokalnego, który łączy się z usługą Azure AI Search w Twoim imieniu. Alternatywną metodą jest uzyskanie tokenu dla aplikacji klienckiej, przy założeniu, że aplikacja jest zarejestrowana w identyfikatorze Microsoft Entra.

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 .rest rozszerzeniem lub .http .

Wklej poniższy przykład, jeśli używasz kluczy interfejsu API. @baseUrl Zastąp symbole zastępcze i @apiKey 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=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

Możesz też wkleić ten przykład, jeśli używasz ról. @baseUrl Zastąp symbole zastępcze i @token wartościami skopiowanymi wcześniej.

@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

 ### List existing indexes by name
 GET  {{baseUrl}}/indexes?api-version=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

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 request powinien pojawić się powyżej żądania.

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-quickstart indeks w usłudze wyszukiwania.

### Create a new index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

    {
        "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 Created odpowiedź, 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ędzy api-key i 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=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

    {
        "value": [
        {
        "@search.action": "upload",
        "HotelId": "1",
        "HotelName": "Stay-Kay City Hotel",
        "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": "Old Century Hotel",
        "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": "Gastronomic 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 Palace Hotel",
        "Description": "Sublime Palace 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 Palace 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 search parametr. Ten przykład zawiera opcjonalny searchFields parametr, który ogranicza wyszukiwanie tekstu do określonych pól.

### Run a query
POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  {
      "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 Palace Hotel",
      "Description": "Sublime Palace 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 Palace 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=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

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=2024-07-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.

Szybki start: wyszukiwanie wektorów przy użyciu interfejsu REST

Udostępnij za pośrednictwem