Guida introduttiva: Ricerca di testo con REST

  • Articolo

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 Ricerca di intelligenza artificiale di Azure.

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

Prerequisiti

Scaricare i file

Scaricare un esempio REST da GitHub per inviare le richieste in questa guida introduttiva. Per altre informazioni, vedere 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.

Copiare una chiave e un URL del servizio di ricerca

Le chiamate REST richiedono l'endpoint del servizio di ricerca e una chiave API per ogni richiesta. È possibile ottenere questi valori dalla portale di Azure.

  1. Accedere al portale di Azure. Passare quindi alla pagina Panoramica del servizio di ricerca e copiare l'URL. Un endpoint di esempio potrebbe essere simile a https://mydemo.search.windows.net.

  2. Selezionare Impostazioni> Chiavi e quindi copiare una chiave di amministratore. Amministrazione chiavi vengono usate per aggiungere, modificare ed eliminare oggetti. Sono disponibili due chiavi di amministrazione intercambiabili. Copiarne uno.

    Screenshot che mostra l'URL e le chiavi API nel portale di Azure.

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.

  1. Avviare Visual Studio Code e selezionare il riquadro Estensioni .

  2. Cercare il client REST e selezionare Installa.

    Screenshot che mostra il pulsante Installa client REST.

  3. Aprire o creare un nuovo file denominato con un'estensione .rest o .http .

  4. Incollare l'esempio seguente. Sostituire l'URL di base e la chiave API con i valori copiati in precedenza.

    @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=2023-11-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

  5. 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.

    Screenshot che mostra un client REST configurato per una richiesta del servizio di ricerca.

    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 .rest file. Creare un indice (REST) crea un indice di ricerca e configura le strutture di dati fisici nel servizio di ricerca.

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

    ### Create a new index
POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

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

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

    Se viene visualizzato un Header name must be a valid HTTP token ["{"] errore, assicurarsi che sia presente una riga vuota tra api-key e il corpo della richiesta. Se si ottiene HTTP 504, verificare che l'URL specifichi 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.

    Screenshot che mostra il client REST con più richieste.

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 Entity Data Model (EDM). Nella ricerca full-text vengono usati campi stringa. Se si vuole che i dati numerici siano ricercabili, assicurarsi che il tipo di dati sia Edm.String. Altri tipi di dati, ad Edm.Int32 esempio, sono filtrabili, ordinabili, visualizzabili e recuperabili, ma non ricercabili full-text.

Gli attributi nel campo determinano le azioni consentite. Le API REST consentono molte 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 viene esteso per includere le raccolte e index l'operazionedocs.

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

    ### Upload documents
POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

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

  2. Selezionare Invia richiesta. In pochi secondi verrà visualizzata 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 .

  1. Incollare nell'esempio seguente per eseguire una query sull'indice di ricerca. Selezionare quindi Invia richiesta. Una richiesta di ricerca di testo include sempre un search parametro. 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=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "search": "lake view",
        "select": "HotelId, HotelName, Tags, Description",
        "searchFields": "Description, Tags",
        "count": true
    }

  2. 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 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.",
      "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.

  1. Incollare nell'esempio seguente per eseguire una query sull'indice di ricerca. Selezionare quindi Invia richiesta.

    ### Get index statistics
GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

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

È anche possibile provare questo DELETE comando:

### Delete an index
DELETE  {{baseUrl}}/indexes/hotels-quickstart?api-version=2023-11-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 Ricerca di intelligenza artificiale di Azure, provare un'altra guida introduttiva che illustra il supporto vettoriale.

Guida introduttiva: Ricerca vettoriale con REST