Estensione di Visual Studio Code per Ricerca cognitiva di Azure (ritirata)
L'estensione di Visual Studio Code per Ricerca cognitiva di Azure, in precedenza in anteprima, non ha spostato la disponibilità generale ed è ora ritirata a partire dal 1° novembre 2022.
Anche se l'estensione non è più disponibile in Azure Marketplace, il codice è open source in https://github.com/microsoft/vscode-azurecognitivesearch. È possibile clonare e modificare lo strumento per il proprio uso.
Se si usa l'estensione, questo articolo illustra come formulare le richieste API REST in modo interattivo usando le API REST Ricerca cognitiva di Azure.
Prerequisiti
Per usare l'estensione sono necessari i servizi e gli strumenti seguenti
Installare l'estensione
Vedere Readme in Github.
Eseguire la connessione alla sottoscrizione
Avviare Visual Studio COde.
Selezionare Accedi ad Azure e accedere all'account Azure.
Verranno visualizzate le sottoscrizioni. Nello screenshot seguente il nome della sottoscrizione è "Visual Studio Enterprise" e contiene un servizio di ricerca denominato "azsearch-service".
vs
Per limitare le sottoscrizioni visualizzate, aprire il riquadro comandi (CTRL+MAIUSC+P o CMD+MAIUSC+P) e cercare Azure o Selezionare le sottoscrizioni. Sono anche disponibili comandi per accedere e disconnettersi dall'account Azure.
Quando si espande il servizio di ricerca, verranno visualizzati elementi ad albero per ogni elemento di Ricerca cognitiva: indici, origini dati, indicizzatori, set di competenze, mappe sinonimi e alias.
Questi elementi ad albero possono essere espansi per visualizzare tutte le risorse disponibili nel servizio di ricerca.
1 - Creare un indice
Per creare un indice, usare l'API REST Crea indice.
Con l'estensione di VS Code, è necessario fare attenzione solo al corpo della richiesta. Questa guida di avvio rapido include una definizione di indice di esempio e i documenti corrispondenti.
Definizione di indice
La definizione di indice seguente è uno schema di esempio per hotel fittizi.
La raccolta fields definisce la struttura dei documenti nell'indice di ricerca. Ogni campo include un tipo di dati e diversi attributi aggiuntivi che ne determinano i possibili utilizzi.
{
"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": "Description_fr",
"type": "Edm.String",
"searchable": true,
"filterable": false,
"sortable": false,
"facetable": false,
"analyzer": "fr.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
}
]
}
],
"suggesters": [
{
"name": "sg",
"searchMode": "analyzingInfixMatching",
"sourceFields": [
"HotelName"
]
}
]
}
Per creare un nuovo indice, fare clic con il pulsante destro del mouse su Indici e quindi scegliere Crea nuovo indice. Verrà visualizzato un editor con un nome simile a indexes-new-28c972f661.azsindex.
Incollare la definizione di indice precedente nella finestra. Quando viene chiesto se aggiornare l'indice, salvare il file e selezionare Carica. Questo passaggio crea l'indice e lo aggiunge alla visualizzazione albero a sinistra.
Se si verifica un problema con la definizione di indice, verrà visualizzato un messaggio di errore simile a quello riportato di seguito.
Se si verifica un errore, correggere il problema e rimettere il file.
2 - Caricare i documenti
Nell'API REST creare l'indice e popolare l'indice sono passaggi separati. In Ricerca cognitiva di Azure l'indice contiene tutti dati ricercabili. In questa guida introduttiva i dati vengono forniti come documenti JSON. Per questa attività viene usata l'API REST di aggiunta, aggiornamento o eliminazione di documenti.
Per aggiungere nuovi documenti all'indice:
Espandere l'indice
hotels-quickstartcreato. Fare clic con il pulsante destro del mouse su Documenti e scegliere Crea nuovo documento.
Verrà visualizzato un editor JSON che ha dedotto lo schema dell'indice.
Incollare il codice JSON seguente e quindi salvare il file. Viene chiesto di confermare le modifiche. Selezionare Carica per salvare le modifiche.
{ "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" } }Ripetere questo processo per i tre documenti rimanenti:
Documento 2:
{ "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" } }Documento 3:
{ "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" } }Documento 4:
{ "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" } }
A questo punto, tutti e quattro i documenti saranno disponibili nella sezione Documenti.
3 - Eseguire la ricerca in un indice
Ora che l'indice contiene contenuto, è possibile eseguire query usando l'API REST documenti di ricerca:
Fare clic con il pulsante destro del mouse sull'indice da cercare e selezionare Cerca. Questo passaggio apre un editor con un nome simile a
sandbox-b946dcda48.azs.
Viene automaticamente popolata una semplice query. Premere CTRL+ALT+R o CMD+ALT+R per inviare la query. In una finestra a sinistra verrà visualizzato il popup dei risultati.
Query di esempio
Provare altri esempi di query per fare pratica con la sintassi. Di seguito sono riportate altre quattro query da provare. È possibile aggiungere più query nello stesso editor. Quando si preme CTRL+ALT+R o CMD+ALT+R, la linea del cursore determina quale query verrà inviata.
Nella prima query viene eseguita la ricerca di boutique e si imposta select per selezionare solo specifici campi. È consigliabile select solo i campi necessari, in quanto il pull di dati non necessari può aggiungere latenza alle query. La query imposta anche $count=true per restituire il numero totale di risultati della ricerca.
// Query example 1 - Search `boutique` with select and return count
search=boutique&$count=true&$select=HotelId,HotelName,Rating,Category
Nella query successiva viene specificato il termine di ricerca wifi e viene incluso anche un filtro per restituire solo i risultati in cui lo stato è uguale a 'FL'. I risultati sono inoltre ordinati in base al Rating dell'hotel.
// Query example 2 - Search with filter, orderBy, select, and count
search=wifi&$filter=Address/StateProvince eq 'FL'&$select=HotelId,HotelName,Rating,Address/StateProvince&$orderby=Rating desc
La ricerca viene quindi limitata a un singolo campo ricercabile con il parametro searchFields. È un'ottima opzione per rendere la query più efficiente, se si è interessati solo alle corrispondenze in determinati campi.
// Query example 3 - Limit searchFields
search=sublime cliff&$select=HotelId,HotelName,Rating&searchFields=HotelName
Un'altra opzione comune da includere in una query è facets. I facet consentono di compilare filtri nell'app per semplificare l'applicazione per consentire agli utenti di conoscere i valori che possono filtrare verso il basso.
// Query example 4 - Take the top two results, and show only HotelName and Category in the results
search=*&$select=HotelId,HotelName,Rating&searchFields=HotelName&facet=Category
Aprire l'indice nel portale
Per visualizzare l'indice di ricerca nel portale, fare clic con il pulsante destro del mouse sul nome del servizio di ricerca, quindi scegliere Apri nel portale.
Pulire le risorse
Quando si lavora nella propria sottoscrizione, alla fine di un progetto è opportuno verificare se le risorse create sono ancora necessarie. Le risorse che rimangono in esecuzione hanno un costo. È possibile eliminare le singole risorse oppure il gruppo di risorse per eliminare l'intero set di risorse.
Per trovare e gestire le risorse nel portale, usare il collegamento Tutte le risorse o Gruppi di risorse nel riquadro di spostamento a sinistra.
Se si usa un servizio gratuito, tenere presente che il numero di indicizzatori e origini dati è limitato a tre. Per non superare il limite, è possibile eliminare i singoli elementi nel portale.
Passaggi successivi
Ora che si sa come eseguire attività di base, è possibile procedere con altre chiamate API REST per funzionalità più avanzate, ad esempio indicizzatori o configurare una pipeline di arricchimento che aggiunge trasformazioni di contenuto all'indicizzazione. Per il passaggio successivo, vedere il collegamento seguente: