Szybki start: tworzenie indeksu wyszukiwania w programie PowerShell przy użyciu interfejsów API REST

Artykuł
03/27/2024

W tym przewodniku Szybki start usługi Azure AI Search dowiesz się, jak tworzyć, ładować i wykonywać zapytania dotyczące indeksu wyszukiwania przy użyciu programu PowerShell i interfejsów API REST usługi Azure AI Search. W tym artykule wyjaśniono, jak interaktywnie uruchamiać polecenia programu PowerShell. Alternatywnie możesz pobrać i uruchomić skrypt programu PowerShell, który wykonuje te same operacje.

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.

Wymagania wstępne

W tym przewodniku Szybki start są wymagane następujące usługi i narzędzia:

Program PowerShell 7.3 lub nowszy z użyciem metody Invoke-RestMethod na potrzeby kroków sekwencyjnych i interaktywnych.
Utwórz usługa wyszukiwania usługi Azure AI lub znajdź istniejącą usługę w ramach bieżącej subskrypcji. W tym przewodniku Szybki start możesz skorzystać z bezpłatnej usługi.

Kopiowanie klucza i adresu URL usługi wyszukiwania

W tym przewodniku Szybki start wywołania REST obejmują adres URL usługi i klucz dostępu dla każdego żądania. Usługa wyszukiwania jest tworzona przy użyciu obu tych elementów, więc jeśli usługa Azure AI Search została dodana do subskrypcji, wykonaj następujące kroki, aby uzyskać niezbędne informacje.

Zaloguj się w witrynie Azure Portal. Na stronie Przegląd usługi wyszukiwania pobierz 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 uzyskaj klucz administratora dla pełnych praw w usłudze. W przypadku konieczności przerzucania jednego klucza administracyjnego dostępne są dwa zamienne klucze administracyjne. Możesz użyć klucza podstawowego lub pomocniczego na żądaniach dodawania, modyfikowania i usuwania obiektów.

Wszystkie żądania wymagają klucza interfejsu API dla każdego żądania wysłanego do usługi. 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.

Połączenie do usługi Azure AI Search

W programie PowerShell utwórz $headers obiekt do przechowywania typu zawartości i klucza interfejsu API. Zastąp klucz interfejsu API administratora (YOUR-ADMIN-API-KEY) kluczem prawidłowym dla usługi wyszukiwania. Musisz ustawić ten nagłówek tylko raz na czas trwania sesji, ale dodajesz go do każdego żądania.
```
$headers = @{
'api-key' = '<YOUR-ADMIN-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }
```
$url Utwórz obiekt określający kolekcję indeksów usługi. Zastąp nazwę usługi (YOUR-SEARCH-SERVICE-NAME) prawidłową usługą wyszukiwania.
```
$url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2023-11-01&`$select=name"
```
Uruchom polecenie Invoke-RestMethod , aby wysłać żądanie GET do usługi i zweryfikować połączenie. Dodaj ConvertTo-Json , aby wyświetlić odpowiedzi wysyłane z powrotem z usługi.
```
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
```
Jeśli usługa jest pusta i nie ma indeksów, wyniki są podobne do poniższego przykładu. W przeciwnym razie zostanie wyświetlona reprezentacja definicji indeksu w formacie JSON.
```
{
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes",
    "value":  [

            ]
}
```

Tworzenie indeksu

Jeśli nie używasz portalu, indeks musi istnieć w usłudze, zanim będzie można załadować dane. Ten krok definiuje indeks i wypycha go do usługi. W tym kroku jest używany interfejs API REST tworzenia indeksu.

Wymagane elementy indeksu obejmują nazwę i kolekcję pól. Kolekcja pól definiuje strukturę dokumentu. Każde pole ma nazwę, typ i atrybuty, które określają sposób jego użycia (na przykład to, czy jest to wyszukiwanie pełnotekstowe, filtrowanie lub pobieranie w wynikach wyszukiwania). W indeksie jeden z pól typu Edm.String musi być wyznaczony jako klucz tożsamości dokumentu.

Ten indeks ma nazwę hotels-quickstart i zawiera definicje pól widoczne w poniższym kodzie. Jest to podzbiór większego indeksu hotels używanego w innych artykułach przewodnika. Definicje pól są przycinane w tym przewodniku Szybki start w celu uzyskania zwięzłości.

Wklej ten przykład do programu PowerShell, aby utworzyć $body obiekt zawierający schemat indeksu.

$body = @"
{
    "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}
        ]
     }
  ]
}
"@

Ustaw identyfikator URI na kolekcję indeksów w usłudze i indeksie hotels-quickstart .

$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart?api-version=2023-11-01"

Uruchom polecenie za pomocą $urlpolecenia , $headersi $body , aby utworzyć indeks w usłudze.

Invoke-RestMethod -Uri $url -Headers $headers -Method Put -Body $body | ConvertTo-Json

Wyniki powinny wyglądać podobnie do tego przykładu, co pokazuje tylko dwa pierwsze pola dla zwięzłości:

{
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes/$entity",
    "@odata.etag":  "\"0x8D6EDE28CFEABDA\"",
    "name":  "hotels-quickstart",
    "defaultScoringProfile":  null,
    "fields":  [
                {
                    "name":  "HotelId",
                    "type":  "Edm.String",
                    "searchable":  true,
                    "filterable":  true,
                    "retrievable":  true,
                    "sortable":  true,
                    "facetable":  true,
                    "key":  true,
                    "indexAnalyzer":  null,
                    "searchAnalyzer":  null,
                    "analyzer":  null,
                    "synonymMaps":  ""
                },
                {
                    "name":  "HotelName",
                    "type":  "Edm.String",
                    "searchable":  true,
                    "filterable":  false,
                    "retrievable":  true,
                    "sortable":  true,
                    "facetable":  false,
                    "key":  false,
                    "indexAnalyzer":  null,
                    "searchAnalyzer":  null,
                    "analyzer":  null,
                    "synonymMaps":  ""
                },
                . . .
    ]
}

Napiwek

W celu weryfikacji możesz również sprawdzić listę Indeksy w portalu.

Ładowanie dokumentów

Aby wypchnąć dokumenty, użyj żądania HTTP POST do punktu końcowego adresu URL indeksu. Interfejs API REST dla tego zadania to Dodawanie, aktualizowanie lub usuwanie dokumentów.

Wklej ten przykład do programu PowerShell, aby utworzyć $body obiekt zawierający dokumenty, które chcesz przekazać.

To żądanie zawiera dwa pełne rekordy i jeden rekord częściowy. W rekordzie częściowym pokazano, że można przekazać niekompletne dokumenty. Parametr @search.action określa sposób wykonywania indeksowania. Prawidłowe wartości to upload, , mergeOrUploadmergei delete. Zachowanie mergeOrUpload powoduje utworzenie nowego dokumentu dla hotelId = 3 lub zaktualizowanie zawartości, jeśli już istnieje.

$body = @"
{
    "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"
        }
    }
]
}
"@

Ustaw punkt końcowy na hotels-quickstart kolekcję dokumentacji i dołącz operację indeksu (indexes/hotels-quickstart/docs/index).
```
$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2023-11-01"
```

Uruchom polecenie za pomocą $urlpolecenia , $headersi $body , aby załadować dokumenty do indeksu hotels-quickstart .

Invoke-RestMethod -Uri $url -Headers $headers -Method Post -Body $body | ConvertTo-Json

Wyniki powinny wyglądać podobnie do poniższego przykładu. Powinien zostać wyświetlony kod stanu 201.

{
    "@odata.context":  "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#Collection(Microsoft.Azure.Search.V2019_05_06.IndexResult)",
    "value":  [
                {
                    "key":  "1",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "2",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "3",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "4",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                }
            ]
}

Przeszukiwanie indeksu

W tym kroku pokazano, jak wykonywać zapytania dotyczące indeksu przy użyciu interfejsu API wyszukiwania dokumentów.

Pamiętaj, aby używać pojedynczych cudzysłowów w wyszukiwaniu $urls. Ciągi zapytania zawierają $ znaki i można pominąć konieczność ich ucieczki, jeśli cały ciąg jest ujęta w pojedynczy cudzysłów.

Ustaw punkt końcowy na hotels-quickstart kolekcję dokumentacji i dodaj search parametr, aby przekazać ciąg zapytania.

Ten ciąg wykonuje puste wyszukiwanie (search=*), zwracając nie sklasyfikowaną listę (wynik wyszukiwania = 1,0) dowolnych dokumentów. Domyślnie usługa Azure AI Search zwraca 50 dopasowań jednocześnie. Jako ustrukturyzowane zapytanie zwraca całą strukturę i wartości dokumentu. Dodaj $count=true , aby uzyskać liczbę wszystkich dokumentów w wynikach.
```
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$count=true'
```

Uruchom polecenie , aby wysłać element $url do usługi.

Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

Wyniki powinny wyglądać podobnie do następujących danych wyjściowych:

{
"@odata.context":  "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#docs(*)",
"@odata.count":  4,
"value":  [
              {
                  "@search.score":  0.1547872,
                  "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.6,
                  "Address":  "@{StreetAddress=140 University Town Center Dr; City=Sarasota; StateProvince=FL; PostalCode=34243; Country=USA}"
              },
              {
                  "@search.score":  0.009068266,
                  "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\u0027s restaurant services.",
                  "Category":  "Resort and Spa",
                  "Tags":  "air conditioning bar continental breakfast",
                  "ParkingIncluded":  true,
                  "LastRenovationDate":  "2015-09-20T00:00:00Z",
                  "Rating":  4.8,
                  "Address":  "@{StreetAddress=3393 Peachtree Rd; City=Atlanta; StateProvince=GA; PostalCode=30326; Country=USA}"
              },
            . . .
    ]
}

Wypróbuj kilka innych przykładów zapytań, aby poznać składnię. Wyszukiwanie ciągów, zapytania dosłowne $filter , ograniczanie zestawu wyników, określanie zakresu wyszukiwania do określonych pól i nie tylko.

# Query example 1
# Search the entire index for the terms 'restaurant' and 'wifi'
# Return only the HotelName, Description, and Tags fields
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=restaurant wifi&$count=true&$select=HotelName,Description,Tags'

# Query example 2 
# Apply a filter to the index to find hotels rated 4 or higher
# Returns the HotelName and Rating. Two documents match.
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$filter=Rating gt 4&$select=HotelName,Rating'

# Query example 3
# Take the top two results, and show only HotelName and Category in the results
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=boutique&$top=2&$select=HotelName,Category'

# Query example 4
# Sort by a specific field (Address/City) in ascending order

$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating'

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.

Jeśli używasz bezpłatnej usługi, pamiętaj, że masz ograniczenie do trzech indeksów, indeksatorów i źródeł danych. Możesz usunąć poszczególne elementy w portalu, aby pozostać w limicie.

Następne kroki

W tym przewodniku Szybki start użyto programu PowerShell do przejścia przez podstawowy przepływ pracy na potrzeby tworzenia i uzyskiwania dostępu do zawartości w usłudze Azure AI Search. Mając na uwadze pojęcia, zalecamy przejście do bardziej zaawansowanych scenariuszy, takich jak indeksowanie ze źródeł danych platformy Azure:

Samouczek REST: indeksowanie i wyszukiwanie częściowo ustrukturyzowanych danych (obiektów blob JSON) w usłudze Azure AI Search