Esercitazione: Eseguire query su un indice di Azure AI Search da Power Apps

2025-04-23

Usare l'ambiente di sviluppo rapido di applicazioni di Power Apps per creare un'app personalizzata per il contenuto ricercabile in Azure AI Search.

In questa esercitazione apprenderai a:

Connettersi ad Azure AI Search
Configurare una richiesta di query
Visualizzare i risultati in un'app canvas

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

Prerequisiti

Account Power Apps con una licenza Premium, ad esempio un piano di Power Apps per app o un piano di Power Apps per utente.
Indice Hotels-sample ospitato nel servizio di ricerca.
Chiave API di query.

1 - Creare un connettore personalizzato

Un connettore di Power Apps è una connessione a una fonte di dati. In questo passaggio creare un connettore personalizzato per connettersi a un indice di ricerca nel cloud.

Accedere a Power Apps.
A sinistra selezionare Connettori personalizzati.
Selezionare + Nuovo connettore personalizzato e quindi selezionare Creare da zero.
Assegnare un nome al connettore personalizzato, ad esempio AzureSearchQuery, quindi fare clic su Continua.
Immettere le informazioni nella pagina Generale:
- Colore di sfondo dell'icona (ad esempio #007ee5)
- Descrizione (ad esempio "Connettore a Azure AI Search")
- Nell'host immettere l'URL del servizio di ricerca (ad esempio <yourservicename>.search.windows.net)
- Per l’URL di base immettere "/"
Nella pagina Sicurezza impostare Chiave API per Tipo di autenticazione, quindi impostare sia l'etichetta che il nome del parametro su api-key. Per Percorso parametro selezionare Intestazione come illustrato nello screenshot seguente.
Nella pagina Definizioni selezionare + Nuova azione per creare un'azione che eseguirà una query sull'indice. Immettere il valore "Query" per il riepilogo e per il nome dell'ID operazione. Immettere una descrizione, ad esempio "query sull'indice di ricerca".
Scorrere verso il basso. In Richieste selezionare il pulsante + Importa da esempio per configurare una richiesta di query per il servizio di ricerca:
- Selezionare il verbo GET
- Per l’URL, immettere una query di esempio per l'indice di ricerca (search=* restituisce tutti i documenti, $select= consente di scegliere i campi). Il campo Versione API è obbligatorio. Specificato completamente, un URL potrebbe essere simile all'esempio seguente. Si noti che il https:// prefisso viene omesso.
```
mydemo.search.windows.net/indexes/hotels-sample-index/docs?search=*&$select=HotelName,Description,Address/City&api-version=2024-07-01
```
- Per Intestazioni, digitare Content-Type application/json.
  
  Power Apps usa la sintassi dell'URL per estrarre parametri dalla query: i parametri search, select e api-version diventano configurabili durante l'esecuzione della procedura guidata.
Selezionare Importa per riempire automaticamente la richiesta. Completare l'impostazione dei metadati dei parametri facendo clic sul simbolo ... accanto a ognuno dei parametri. Selezionare Indietro per tornare nella pagina Richiesta dopo l'aggiornamento di ogni parametro.
Per la ricerca: impostare * come valore predefinito, impostare Obbligatorio come Falso e impostare la visibilità su nessuna.
Per la selezione: impostare HotelName,Description,Address/City come valore predefinito, impostare Obbligatorio su Falso e impostare la visibilità su nessuna.
Per la versione api: impostare 2024-07-01 come valore predefinito, impostare Obbligatorio su Vero e impostare la visibilità su interno.
Per tipo di contenuto: impostare su application/json.

Dopo aver apportato queste modifiche, passare alla visualizzazione Editor Swagger. Nella sezione parameters dovrebbe essere visualizzata la configurazione seguente:

parameters:
  - {name: search, in: query, required: false, type: string, default: '*'}
  - {name: $select, in: query, required: false, type: string, default: 'HotelName,Description,Address/City'}
  - {name: api-version, in: query, required: true, type: string, default: '2024-07-01',
    x-ms-visibility: internal}
  - {name: Content-Type, in: header, required: false, type: string}

Tornare alla procedura guidata e in particolare al passaggio 3. Definizione. Scorrere in basso fino alla sezione Risposta. Selezionare "Aggiungi risposta predefinita". Questo passaggio è fondamentale perché consente a Power Apps di comprendere lo schema della risposta.

Incollare una risposta di esempio. Per acquisire facilmente una risposta di esempio, è possibile usare Esplora ricerche nel portale di Azure. In Esplora ricerche è necessario immettere la stessa query specificata per la richiesta, ma aggiungendo $top = 2 per vincolare i risultati a due soli documenti: search=*&$select=HotelName,Description,Address/City&$top=2.

Power Apps richiede solo pochi risultati per rilevare lo schema. È ora possibile copiare la risposta seguente nella procedura guidata, presupponendo che si usi hotels-sample-index.

{
    "@odata.context": "https://mydemo.search.windows.net/indexes('hotels-sample-index')/$metadata#docs(*)",
    "value": [
        {
            "@search.score": 1,
            "HotelName": "Happy Lake Resort & Restaurant",
            "Description": "The largest year-round resort in the area offering more of everything for your vacation – at the best value!  What can you enjoy while at the resort, aside from the mile-long sandy beaches of the lake? Check out our activities sure to excite both young and young-at-heart guests. We have it all, including being named “Property of the Year” and a “Top Ten Resort” by top publications.",
            "Address": {
                "City": "Seattle"
            }
        },
        {
            "@search.score": 1,
            "HotelName": "Grand Gaming Resort",
            "Description": "The Best Gaming Resort in the area.  With elegant rooms & suites, pool, cabanas, spa, brewery & world-class gaming.  This is the best place to play, stay & dine.",
            "Address": {
                "City": "Albuquerque"
            }
        }
    ]
}

Suggerimento

Esiste un limite di caratteri per la risposta JSON che è possibile immettere, quindi è consigliabile semplificare il codice JSON prima di incollarlo. Lo schema e il formato della risposta sono più importanti dei valori stessi. Il campo Descrizione, ad esempio, può essere semplificato lasciando solo la prima frase.

Selezionare Importa per aggiungere la risposta predefinita.
Fare clic su Crea connettore in alto a destra per salvare la definizione.
Fare clic su Chiudi per chiudere il connettore.

2 - Testare la connessione

La prima volta che viene creato il connettore, è necessario riaprirlo dall'elenco di connettori personalizzati per poterlo testare. In seguito, se si apportano altri aggiornamenti, è possibile eseguire il test dall'interno della procedura guidata.

Specificare una chiave API di query per questa attività. Ogni volta che viene creata una connessione, sia per un'esecuzione di test o per l'inclusione in un'app, il connettore richiede la chiave API di query usata per la connessione ad Azure AI Search.

Sull'estrema sinistra selezionare Connettori personalizzati.
Individuare il connettore nell'elenco, che in questa esercitazione è "AzureSearchQuery".
Selezionare il connettore, espandere l'elenco di azioni e selezionare Visualizza proprietà.
Nell'elenco a discesa delle operazioni selezionare 6. Test.
In Verifica operazione selezionare + Nuova connessione.
Immettere una chiave API di query. Si tratta di una query Azure AI Search per l'accesso in sola lettura a un indice. La chiave è reperibile nel portale di Azure.
In Operazioni selezionare il pulsante Verifica operazione. Se l'operazione riesce, verrà visualizzato lo stato 200 e nel corpo della risposta verrà visualizzato il codice JSON che descrive i risultati della ricerca.

Se il test non riesce, controllare nuovamente gli input. In particolare, rivedere la risposta di esempio e assicurarsi che sia stata creata correttamente. La definizione del connettore dovrebbe mostrare gli elementi previsti per la risposta.

Se si è bloccati da un errore dei criteri di prevenzione della perdita dei dati (DLP), esaminare il messaggio di errore per indicazioni. Potrebbe essere possibile modificare i criteri o rendere il connettore non bloccabile.

3 - Visualizzare i risultati

In questo passaggio creare un'app Power Apps con una casella di ricerca, un pulsante di ricerca e un'area per la visualizzazione dei risultati. Power Apps si connetterà al connettore personalizzato creato di recente per ottenere i dati da Ricerca di Azure.

A sinistra, espandere >>Iniziare con una progettazione di pagina.
Selezionare un'area di disegno vuota con Layout telefono. Assegnare all'app un nome, ad esempio "Ricerca hotel". Seleziona Crea. Viene visualizzato Power Apps Studio.
In studio, selezionare la scheda Dati, selezionare Aggiungi dati e quindi trovare il nuovo connettore appena creato. In questa esercitazione è denominata AzureSearchQuery. Seleziona Aggiungi una connessione.

Immettere la chiave API di query.

A questo punto AzureSearchQuery è un'origine dati disponibile per la tua applicazione.
Nella scheda Inserisci aggiungere alcuni controlli al canvas.
Inserire gli elementi seguenti:
- Un'etichetta di testo con il valore "Query":
- Un elemento input di testo (assegnare il nome txtQuery, valore predefinito: "*")
- Un pulsante con il testo "Search"
- Una raccolta verticale chiamata (chiamatela galleryResults)
La tela dovrebbe apparire simile a questo:

Layout dei controlli
Per fare in modo che il pulsante di ricerca esegua una query, incollare l'azione seguente in OnSelect:
```
If(!IsBlank(txtQuery.Text),
    ClearCollect(azResult, AzureSearchQuery.Query({search: txtQuery.Text}).value))
```
Lo screenshot seguente mostra la barra della formula per l'azione OnSelect.

Con questa azione, il pulsante aggiornerà una nuova raccolta denominata azResult con il risultato della query di ricerca, usando il testo della casella di testo txtQuery come termine della query.
Nota

Prova questo se si riceve un errore di sintassi della formula: "La funzione 'ClearCollect' ha alcune funzioni non valide".
- Assicurarsi prima di tutto che il riferimento al connettore sia corretto. Cancellare il nome del connettore e iniziare a digitarne il nome. IntelliSense dovrebbe suggerire il connettore e il verbo corretti.
- Se l'errore persiste, eliminare il connettore e ricrearlo. Se sono presenti più istanze di un connettore, è possibile che l'app usi quella sbagliata.
Collega il controllo della raccolta verticale alla raccolta azResult creata nel passaggio precedente.

Seleziona il controllo galleria ed esegui le seguenti azioni nel riquadro delle proprietà.
- Impostare DataSource su azResult.
- Selezionare un Layout appropriato in base al tipo di dati dell'indice. In questo caso, è stato usato il layout Titolo, sottotitolo e corpo.
- Scegliere Modifica campi e selezionare i campi da visualizzare.
Poiché quando è stato definito il connettore è stato fornito un risultato di esempio, l'app è in grado di riconoscere i campi disponibili nell'indice.
Premere F5 per visualizzare l'anteprima dell'app.

Pulire le risorse

Quando si lavora nella propria sottoscrizione, alla fine di un progetto è opportuno verificare se le risorse create sono ancora necessarie. L'esecuzione continua delle risorse può avere 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 di spostamento a sinistra.

Tenere presente che un servizio di ricerca gratuito è limitato a tre indici, indicizzatori e origini dati. È possibile eliminare singoli elementi nel portale di Azure per rimanere al di sotto del limite.

Passaggi successivi

Power Apps consente lo sviluppo rapido di app personalizzate. Ora che sai come connetterti a un indice di ricerca, scopri di più su come creare un'esperienza di visualizzazione arricchita in un'app personalizzata di Power App.

Catalogo di risorse di apprendimento per Power Apps