Avvio rapido Ricerca di parole chiave con REST

Articolo
11/29/2024

Le API REST in Ricerca intelligenza artificiale di Azure offrono accesso a livello di codice a tutte le funzionalità, incluse le funzionalità di anteprima e sono un modo semplice per apprendere il funzionamento delle funzionalità. Questa guida introduttiva illustra come chiamare le API REST di ricerca per creare, caricare ed eseguire query su un indice di ricerca in Azure AI Search.

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

Prerequisiti

Visual Studio Code con un client REST.
Azure AI Search. Creare o trovare una risorsa di Azure AI Search esistente nella sottoscrizione corrente. È possibile usare un servizio gratuito per questo avvio rapido.

Scaricare i file

Scaricare un esempio REST da GitHub per inviare le richieste in questa guida introduttiva. Le istruzioni sono disponibili in Download di file da GitHub.

È anche possibile avviare un nuovo file nel sistema locale e creare richieste manualmente seguendo le istruzioni riportate in questo articolo.

Ottenere un endpoint del servizio di ricerca

È possibile trovare l'endpoint del servizio di ricerca nel portale di Azure.

Accedere al portale di Azure e trovare il servizio di ricerca.
Nella home page Panoramica trovare l'URL. Un endpoint di esempio potrebbe essere simile a https://mydemo.search.windows.net.

Questo endpoint viene incollato nel file .rest o .http in un passaggio successivo.

Configurare l'accesso

Le richieste all'endpoint di ricerca devono essere autenticate e autorizzate. È possibile usare chiavi API o ruoli per questa attività. Le chiavi sono più facili da iniziare, ma i ruoli sono più sicuri.

Per una connessione basata su ruoli, le istruzioni seguenti contengono la connessione a Ricerca di intelligenza artificiale di Azure con l'identità, non l'identità di un'app client.

Opzione 1: Usare le chiavi

Selezionare Impostazioni>Chiavi e quindi copiare una chiave di amministratore. Le chiavi di amministrazione vengono usate per aggiungere, modificare ed eliminare oggetti. Sono disponibili due chiavi amministratore intercambiabili. Copiarne una. Per altre informazioni, vedere Connettersi a Azure AI Search usando l'autenticazione con chiave.

Questa chiave viene incollata nel file .rest o .http in un passaggio successivo.

Opzione 2: Usare i ruoli

Assicurarsi che il servizio di ricerca sia configurato per l'accesso basato sul ruolo. È necessario avere assegnazioni di ruolo preconfigurate per l'accesso agli sviluppatori. Le assegnazioni di ruolo devono concedere l'autorizzazione per creare, caricare ed eseguire query su un indice di ricerca.

In questa sezione ottenere il token di identità personale usando l'interfaccia della riga di comando di Azure, Azure PowerShell o il portale di Azure.

Accedere all'interfaccia della riga di comando di Azure.
```
az login
```

Ottenere il token di identità personale.

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

Il token di identità personale viene incollato nel file .rest o .http in un passaggio successivo.

Nota

Questa sezione presuppone che si stia usando un client locale che si connette a Ricerca di intelligenza artificiale di Azure per conto dell'utente. Un approccio alternativo consiste nell'ottenere un token per l'app client, presupponendo che l'applicazione sia registrata con Microsoft Entra ID.

Configurare Visual Studio Code

Se non si ha familiarità con il client REST per Visual Studio Code, questa sezione include la configurazione in modo da poter completare le attività in questa guida introduttiva.

Avviare Visual Studio Code e selezionare il riquadro Estensioni.
Cercare il client REST e selezionare Installa.
Aprire o creare un nuovo file denominato con un'estensione .rest o .http.

Incollare l'esempio seguente se si usano chiavi API. Sostituire i @baseUrl segnaposto e @apiKey con i valori copiati in precedenza, senza virgolette.

@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}}

In alternativa, incollare questo esempio se si usano ruoli. Sostituire i @baseUrl segnaposto e @token con i valori copiati in precedenza, senza virgolette.

@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}}

Selezionare Invia richiesta. Una risposta dovrebbe essere visualizzata in un riquadro adiacente. Se sono presenti indici esistenti, vengono elencati. In caso contrario, l'elenco è vuoto. Se il codice HTTP è 200 OK, si è pronti per i passaggi successivi.

Se si ottiene WWW-Authenticate: Bearer realm="Azure Cognitive Search" error="invalid_token" error_description="Authentication token failed validation.", rimuovere le virgolette intorno al token, salvare il file e ripetere la richiesta.

Punti chiave:
- I parametri vengono specificati usando un prefisso @.
- ### designa una chiamata REST. La riga successiva contiene la richiesta, che deve includere HTTP/1.1.
- Send request dovrebbe essere visualizzato sopra la richiesta.

Creare un indice

Aggiungere una seconda richiesta al file .rest. Creare un indice (REST) crea un indice di ricerca e configura le strutture di dati fisici nel servizio di ricerca.

Incollare l'esempio seguente per creare l'indice hotels-quickstart nel servizio di ricerca.

### 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}
                ]
            }
        ]
    }

Selezionare Invia richiesta. È necessario avere una risposta HTTP/1.1 201 Created e il corpo della risposta deve includere la rappresentazione JSON dello schema dell'indice.

Se viene visualizzato un errore di Header name must be a valid HTTP token ["{"], assicurarsi che sia presente una riga vuota tra api-key e il corpo della richiesta. Se viene restituita una risposta HTTP 504, verificare che nell'URL sia specificato HTTPS. Se viene visualizzata la risposta HTTP 400 o 404, esaminare il corpo della richiesta per verificare che le operazioni di copia e incolla sono state eseguite correttamente. Un HTTP 403 indica in genere un problema con la chiave API. Si tratta di una chiave non valida o di un problema di sintassi con la modalità di specifica della chiave API.

Sono ora presenti diverse richieste nel file. Tenere presente che ### avvia una nuova richiesta e ogni richiesta viene eseguita in modo indipendente.

Informazioni sulla definizione dell'indice

All'interno dello schema dell'indice, l'insieme fields definisce la struttura del documento. Ogni documento caricato deve avere questi campi. Ogni campo deve essere assegnato a un tipo di dati EDM (Entity Data Model). Nella ricerca full-text vengono usati campi stringa. Se si desidera che i dati numerici siano ricercabili, assicurarsi che il tipo di dati sia Edm.String. Altri tipi di dati, ad esempio Edm.Int32, sono filtrabili, ordinabili, visualizzabili e recuperabili, ma non ricercabili full-text.

Gli attributi nel campo determinano l'azione consentita. Le API REST consentono numerose azioni per impostazione predefinita. Ad esempio, tutte le stringhe sono ricercabili e recuperabili per impostazione predefinita. Per le API REST, è possibile avere attributi solo se è necessario disattivare un comportamento.

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

Caricare i documenti

La creazione e il caricamento dell'indice sono passaggi separati. In Ricerca di intelligenza artificiale di Azure l'indice contiene tutti i dati e le query ricercabili eseguiti nel servizio di ricerca. Per le chiamate REST, i dati vengono forniti come documenti JSON. Usare l'API REST Documents- Index per questa attività.

L'URI è stato esteso per includere le raccolte docs e l'operazione index.

Incollare l'esempio seguente per caricare documenti JSON nell'indice di ricerca.

### 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"
            }
        }
      ]
    }

Selezionare Invia richiesta. Entro pochi secondi si dovrebbe visualizzare una risposta HTTP 201 nel riquadro adiacente.

Se viene restituito un codice 207, significa che il caricamento di almeno uno dei documenti non è riuscito. Se viene restituito un codice 404 significa che è presente un errore di sintassi nell'intestazione o nel corpo della richiesta. Verificare di aver modificato l'endpoint in modo da includere /docs/index.

Esegui query

Ora che i documenti vengono caricati, è possibile eseguire query su di essi usando Documenti - Post di ricerca (REST).

L'URI viene esteso per includere un'espressione di query, specificata tramite l'operatore /docs/search.

Incollare nell'esempio seguente per eseguire una query sull'indice di ricerca. Successivamente, selezionare Invia richiesta. Una richiesta di ricerca di testo include sempre un parametro search. Questo esempio include un parametro facoltativo searchFields che vincola la ricerca di testo a campi specifici.

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

Esaminare la risposta nel riquadro adiacente. È necessario disporre di un conteggio che indica il numero di corrispondenze trovate nell'indice, un punteggio di ricerca che indica la pertinenza e i valori per ogni campo elencato nell'istruzione 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"
      ]
    }
  ]
}

Ottenere le proprietà dell'indice

È anche possibile usare Get Statistics per eseguire query sui conteggi dei documenti e sulle dimensioni dell'indice.

Incollare nell'esempio seguente per eseguire una query sull'indice di ricerca. Successivamente, selezionare Invia richiesta.

### Get index statistics
GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

Rivedere la risposta. Questa operazione è un modo semplice per ottenere informazioni dettagliate sull'archiviazione degli indici.

{
  "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics",
  "documentCount": 4,
  "storageSize": 34707,
  "vectorIndexSize": 0
}

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 nella portale di Azure usando il collegamento Tutte le risorse o Gruppi di risorse nel riquadro più a sinistra.

È anche possibile provare questo comando DELETE:

### Delete an index
DELETE  {{baseUrl}}/indexes/hotels-quickstart?api-version=2024-07-01 HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Passaggio successivo

Ora che si ha familiarità con il client REST e si effettuano chiamate REST a Azure AI Search, provare un'altra guida introduttiva che illustra il supporto vettoriale.

Avvio rapido: Ricerca vettoriale con REST

Condividi tramite