Rychlý start: Vytvoření indexu vyhledávání v PowerShellu pomocí rozhraní REST API

Článek
03/25/2024

V tomto rychlém startu azure AI Search se naučíte vytvářet, načítat a dotazovat index vyhledávání pomocí PowerShellu a rozhraní REST API služby Azure AI Search. Tento článek vysvětluje, jak interaktivně spouštět příkazy PowerShellu. Alternativně si můžete stáhnout a spustit skript PowerShellu, který provádí stejné operace.

Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet.

Požadavky

Pro účely tohoto rychlého startu se vyžadují následující služby a nástroje:

PowerShell 7.3 nebo novější s využitím invoke-RestMethod pro postupné a interaktivní kroky
Vytvořte Search Azure AI nebo vyhledejte existující službu v rámci vašeho aktuálního předplatného. Pro účely tohoto rychlého startu můžete použít bezplatnou službu.

Zkopírování klíče a adresy URL vyhledávací služby

V tomto rychlém startu zahrnují volání REST adresu URL služby a přístupový klíč pro každý požadavek. Vyhledávací služba se vytvoří s oběma službami, takže pokud jste do svého předplatného přidali Azure AI Search, získejte potřebné informace pomocí těchto kroků.

Přihlaste se k portálu Azure. Na stránce Přehled vyhledávací služby získejte adresu URL. Příkladem koncového bodu může být https://mydemo.search.windows.net.
Vyberte Nastavení> Klíče a pak získejte klíč správce pro úplná práva ke službě. Pokud potřebujete převést jeden klíč, jsou k dispozici dva zaměnitelné klíče správce pro zajištění kontinuity podnikových procesů. Primární nebo sekundární klíč můžete použít u požadavků pro přidávání, úpravy a odstraňování objektů.

Všechny požadavky vyžadují klíč rozhraní API pro každý požadavek odeslaný do vaší služby. Když bude platný klíč navazovat vztah důvěryhodnosti na základě jednotlivých požadavků, mezi aplikací, která požadavek odešle, a službou, která ji zpracovává.

Připojení do služby Azure AI Search

V PowerShellu vytvořte $headers objekt pro uložení typu obsahu a klíče rozhraní API. Nahraďte klíč rozhraní API pro správu (YOUR-ADMIN-API-KEY) klíčem, který je platný pro vaši vyhledávací službu. Tuto hlavičku stačí nastavit jenom jednou po dobu trvání relace, ale přidáte ji do každého požadavku.
```
$headers = @{
'api-key' = '<YOUR-ADMIN-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }
```
Vytvořte $url objekt, který určuje kolekci indexů služby. Nahraďte název služby (YOUR-SEARCH-SERVICE-NAME) platnou vyhledávací službou.
```
$url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2023-11-01&`$select=name"
```
Spuštěním příkazu Invoke-RestMethod GET odešlete do služby požadavek GET a ověřte připojení. Přidejte ConvertTo-Json , abyste mohli zobrazit odpovědi odeslané ze služby.
```
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
```
Pokud je služba prázdná a nemá žádné indexy, výsledky se podobají následujícímu příkladu. V opačném případě se zobrazí reprezentace definic indexu JSON.
```
{
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes",
    "value":  [

            ]
}
```

Vytvoření indexu

Pokud nepoužíváte portál, musí ve službě existovat index, abyste mohli načíst data. Tento krok definuje index a nasdílí ho do služby. V tomto kroku se používá rozhraní REST API pro vytvoření indexu.

Požadované prvky indexu obsahují název a kolekci polí. Kolekce polí definuje strukturu dokumentu. Každé pole má název, typ a atributy, které určují, jak se používá (například jestli je ve výsledcích hledání možné fulltextové vyhledávání, filtrování nebo načítání). V indexu musí být jedno z polí typu Edm.String označeno jako klíč pro identitu dokumentu.

Tento index má název hotels-quickstart a obsahuje definice polí, které vidíte v následujícím kódu. Jedná se o podmnožinu většího indexu hotelů, který se používá v jiných článcích s návodem. Definice polí jsou oříznuté v tomto rychlém startu pro stručnost.

Vložte tento příklad do PowerShellu $body a vytvořte objekt, který obsahuje schéma indexu.

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

Nastavte identifikátor URI na kolekci indexů ve vaší službě a indexu hotels-quickstart .

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

Spusťte příkaz s příkazem $url, $headersa $body vytvořte index ve službě.

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

Výsledky by měly vypadat podobně jako v tomto příkladu, který zobrazuje pouze první dvě pole pro stručnost:

{
    "@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":  ""
                },
                . . .
    ]
}

Tip

Pro ověření můžete také zkontrolovat seznam indexů na portálu.

Nahrání dokumentů

K nasdílení dokumentů použijte požadavek HTTP POST do koncového bodu adresy URL indexu. Rozhraní REST API pro tuto úlohu je Přidat, Aktualizovat nebo Odstranit dokumenty.

Vložte tento příklad do PowerShellu $body a vytvořte objekt obsahující dokumenty, které chcete nahrát.

Tento požadavek zahrnuje dva úplné záznamy a jeden částečný záznam. Částečný záznam ukazuje, že můžete nahrát neúplné dokumenty. Parametr @search.action určuje, jak se indexování provádí. Platné hodnoty zahrnují upload, merge, mergeOrUploada delete. Chování mergeOrUpload buď vytvoří nový dokument, hotelId = 3 nebo aktualizuje obsah, pokud již existuje.

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

Nastavte koncový bod na hotels-quickstart kolekci dokumentů a zahrňte operaci indexu (indexes/hotels-quickstart/docs/index).
```
$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2023-11-01"
```

Spusťte příkaz s příkazem $url, $headersa $body načtěte dokumenty do indexu hotels-quickstart .

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

Výsledky by měly vypadat podobně jako v následujícím příkladu. Měl by se zobrazit stavový kód 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
                }
            ]
}

Prohledání indexu

Tento krok ukazuje, jak dotazovat index pomocí rozhraní API pro vyhledávání dokumentů.

Nezapomeňte při hledání $urlspoužít jednoduché uvozovky . Řetězce dotazu obsahují $ znaky a pokud je celý řetězec uzavřený do jednoduchých uvozovek, můžete je vynechat.

Nastavte koncový bod na hotels-quickstart kolekci docs a přidejte search parametr pro předání řetězce dotazu.

Tento řetězec spustí prázdné hledání (search=*), které vrátí neřaděný seznam (skóre hledání = 1,0) libovolných dokumentů. Azure AI Search ve výchozím nastavení vrací 50 shod najednou. Jak je strukturováno, tento dotaz vrátí celou strukturu a hodnoty dokumentu. Pokud chcete získat počet všech dokumentů ve výsledcích, přidejte $count=true ho.
```
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$count=true'
```

Spuštěním příkazu odešlete $url službu.

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

Výsledky by měly vypadat podobně jako v následujícím výstupu:

{
"@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}"
              },
            . . .
    ]
}

Vyzkoušejte několik dalších příkladů dotazů, abyste získali pocit syntaxe. Můžete provádět vyhledávání řetězců, doslovné $filter dotazy, omezit sadu výsledků, omezit hledání na konkrétní pole a provádět další akce.

# 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'

Vyčištění prostředků

Pokud pracujete s vlastním předplatným, je vhodné vždy na konci projektu zkontrolovat, jestli budete vytvořené prostředky ještě potřebovat. Prostředky, které necháte spuštěné, vás stojí peníze. Prostředky můžete odstraňovat jednotlivě nebo můžete odstranit skupinu prostředků, a odstranit tak celou sadu prostředků najednou.

Prostředky můžete najít a spravovat na portálu pomocí odkazu Všechny prostředky nebo skupiny prostředků v levém podokně.

Pokud používáte bezplatnou službu, mějte na paměti, že jste omezeni na tři indexy, indexery a zdroje dat. Jednotlivé položky na portálu můžete odstranit, abyste zůstali pod limitem.

Další kroky

V tomto rychlém startu jste pomocí PowerShellu prošli základním pracovním postupem pro vytváření a přístup k obsahu ve službě Azure AI Search. S ohledem na koncepty doporučujeme přejít k pokročilejším scénářům, jako je indexování ze zdrojů dat Azure:

Kurz REST: Indexování a vyhledávání částečně strukturovaných dat (objektů blob JSON) ve službě Azure AI Search