Guida introduttiva: Creare un indice di ricerca in PowerShell usando le API REST

Articolo
03/28/2024

Questa guida introduttiva di Ricerca intelligenza artificiale di Azure illustra come creare, caricare ed eseguire query su un indice di ricerca usando PowerShell e le API REST di Ricerca di intelligenza artificiale di Azure. L'articolo descrive come eseguire i comandi di PowerShell in modo interattivo. In alternativa, è possibile scaricare ed eseguire uno script di PowerShell che esegue le stesse operazioni.

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Prerequisiti

Per questa guida introduttiva sono necessari i servizi e gli strumenti seguenti:

PowerShell 7.3 o versione successiva, usando Invoke-RestMethod per i passaggi sequenziali e interattivi.
Creare un servizio di ricerca di intelligenza artificiale di Azure o trovare un servizio esistente nella sottoscrizione corrente. È possibile usare un servizio gratuito per questo avvio rapido.

Copiare una chiave e un URL del servizio di ricerca

In questa guida introduttiva, le chiamate REST includono l'URL del servizio e una chiave di accesso per ogni richiesta. Un servizio di ricerca viene creato con entrambi, quindi, se alla sottoscrizione è stata aggiunta Ricerca di intelligenza artificiale di Azure, seguire questa procedura per ottenere le informazioni necessarie.

Accedere al portale di Azure. Nella pagina Panoramica del servizio di ricerca ottenere l'URL. Un endpoint di esempio potrebbe essere simile a https://mydemo.search.windows.net.
Selezionare Impostazioni> Chiavi e quindi ottenere una chiave di amministratore per i diritti completi nel servizio. Se è necessario eseguire il rollover di due chiavi di amministrazione intercambiabili, vengono fornite per la continuità aziendale. È possibile usare la chiave primaria o secondaria nelle richieste per l'aggiunta, la modifica e l'eliminazione di oggetti.

Tutte le richieste richiedono una chiave API per ogni richiesta inviata al servizio. La presenza di una chiave valida stabilisce un trust, per ogni richiesta, tra l'applicazione che invia la richiesta e il servizio che lo gestisce.

Connessione a Ricerca di intelligenza artificiale di Azure

In PowerShell creare un $headers oggetto per archiviare il tipo di contenuto e la chiave API. Sostituire la chiave API amministratore (YOUR-ADMIN-API-KEY) con una chiave valida per il servizio di ricerca. È necessario impostare questa intestazione una sola volta per la durata della sessione, ma aggiungerla a ogni richiesta.
```
$headers = @{
'api-key' = '<YOUR-ADMIN-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }
```
Creare un $url oggetto che specifica l'insieme di indici del servizio. Sostituire il nome del servizio (YOUR-SEARCH-SERVICE-NAME) con un servizio di ricerca valido.
```
$url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2023-11-01&`$select=name"
```
Eseguire Invoke-RestMethod per inviare una richiesta GET al servizio e verificare la connessione. Aggiungere ConvertTo-Json in modo da poter visualizzare le risposte inviate dal servizio.
```
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
```
Se il servizio è vuoto e non contiene alcun indice, i risultati saranno simili all'esempio seguente. In caso contrario, viene visualizzata una rappresentazione JSON delle definizioni di indice.
```
{
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes",
    "value":  [

            ]
}
```

Creare un indice

A meno che non si usi il portale, è necessario che nel servizio esista un indice prima di poter caricare i dati. Questo passaggio definisce l'indice e ne effettua il push nel servizio. Per questo passaggio viene usata l'API REST per la creazione di indici.

Gli elementi obbligatori di un indice includono un nome e una raccolta di campi. La raccolta di campi (fields) definisce la struttura di un documento. Ogni campo ha un nome, un tipo e attributi che determinano la modalità di utilizzo, ad esempio se è ricercabile, filtrabile o recuperabile nei risultati della ricerca full-text. All'interno di un indice, uno dei campi di tipo Edm.String deve essere designato come chiave (key) per l'identità del documento.

Questo indice è denominato hotels-quickstart e ha le definizioni di campo visualizzate nel codice seguente. Si tratta di un subset di un indice hotels più grande usato in altri articoli della procedura dettagliata. Le definizioni dei campi vengono tagliate in questa guida introduttiva per brevità.

Incollare questo esempio in PowerShell per creare un $body oggetto contenente lo schema dell'indice.

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

Impostare l'URI sulla raccolta di indici nel servizio e nell'indice hotels-quickstart .

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

Eseguire il comando con $url, $headerse $body per creare l'indice nel servizio.

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

I risultati dovrebbero essere simili a questo esempio, che mostra solo i primi due campi per brevità:

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

Suggerimento

Per la verifica, è anche possibile controllare l'elenco Indici nel portale.

Caricare i documenti

Per effettuare il push di documenti, usare una richiesta HTTP POST all'endpoint URL dell'indice. L'API REST per questa attività è illustrata in Aggiungere, aggiornare o eliminare documenti.

Incollare questo esempio in PowerShell per creare un $body oggetto contenente i documenti da caricare.

Questa richiesta include due record completi e un record parziale. Il record parziale dimostra che è possibile caricare documenti incompleti. Il parametro @search.action specifica come viene eseguita l'indicizzazione. I valori validi includono upload, merge, mergeOrUploade delete. Il mergeOrUpload comportamento crea un nuovo documento per hotelId = 3 o aggiorna il contenuto, se già esistente.

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

Impostare l'endpoint sulla hotels-quickstart raccolta docs e includere l'operazione sull'indice (indexes/hotels-quickstart/docs/index).
```
$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2023-11-01"
```

Eseguire il comando con $url, $headerse $body per caricare i documenti nell'indice hotels-quickstart .

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

I risultati dovrebbero essere simili all'esempio seguente. Verrà visualizzato un codice di stato 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
                }
            ]
}

Eseguire la ricerca in un indice

Questo passaggio illustra come eseguire query su un indice usando l'API Cerca documenti.

Assicurarsi di usare virgolette singole nella ricerca $urls. Le stringhe di query includono $ caratteri ed è possibile ometterne l'escape se l'intera stringa è racchiusa tra virgolette singole.

Impostare l'endpoint sulla hotels-quickstart raccolta docs e aggiungere un search parametro per passare una stringa di query.

Questa stringa esegue una ricerca vuota (search=*), restituendo un elenco non classificato (punteggio di ricerca = 1,0) di documenti arbitrari. Per impostazione predefinita, Ricerca intelligenza artificiale di Azure restituisce 50 corrispondenze alla volta. Così come strutturata, questa query restituisce un'intera struttura di documenti e i valori. Aggiungere $count=true per ottenere un conteggio di tutti i documenti nei risultati.
```
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$count=true'
```

Eseguire il comando per inviare l'oggetto $url al servizio.

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

I risultati dovrebbero essere simili all'output seguente:

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

Provare altri esempi di query per fare pratica con la sintassi. È possibile eseguire una ricerca di stringhe, query verbatim $filter , limitare il set di risultati, definire l'ambito della ricerca in campi specifici e altro ancora.

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

Pulire le risorse

Quando si lavora nella propria sottoscrizione, al termine di un progetto è buona norma determinare se le risorse create sono ancora necessarie. Le risorse che rimangono in esecuzione hanno un costo. È possibile eliminare risorse singole oppure gruppi di risorse per eliminare l'intero set di risorse.

È possibile trovare e gestire le risorse nel portale usando il collegamento Tutte le risorse o Gruppi di risorse nel riquadro più a sinistra.

Se si usa un servizio gratuito, tenere presente che sono limitati a tre indici, indicizzatori e origini dati. Per non superare il limite, è possibile eliminare i singoli elementi nel portale.

Passaggi successivi

In questa guida introduttiva è stato usato PowerShell per esaminare il flusso di lavoro di base per la creazione e l'accesso al contenuto in Ricerca di intelligenza artificiale di Azure. Tenendo presenti i concetti, è consigliabile passare a scenari più avanzati, ad esempio l'indicizzazione da origini dati di Azure:

Esercitazione REST: Indicizzare e cercare dati semistrutturati (BLOB JSON) in Ricerca di intelligenza artificiale di Azure