Effettuare richieste HTTP

Importante

Le capacità e funzionalità di Power Virtual Agents ora fanno parte di Microsoft Copilot Studio a seguito di investimenti significativi nell'intelligenza artificiale generativa e integrazioni migliorate in Microsoft Copilot.

Alcuni articoli e schermate potrebbero fare riferimento a Power Virtual Agents durante l'aggiornamento della documentazione e dei contenuti per il training.

In Copilot Studio, puoi estendere le funzionalità di un copilota chiamando API REST esterne utilizzando il nodo Richiesta HTTP. Ciò può essere utile quando è necessario recuperare dati da un sistema esterno o manipolare dati su quel sistema.

Prerequisiti

• Creare e modificare argomenti

Usa il nodo di richiesta HTTP

1. Seleziona Aggiungi nodo (+), apri il menu secondario Avanzate, quindi seleziona Invia richiesta HTTP.

   

2. Nella casella URL, inserisci l'URL dell'endpoint API che desideri chiamare.

3. Seleziona il Metodo della richiesta appropriata dall'elenco a discesa. Sono supportati i metodi GET, POST, PATCH, PUT e DELETE.

   

4. Sotto Intestazioni e corpo sul nodo, fai clic sul pulsante Modifica . Verrà aperto il riquadro proprietà della richiesta HTTP.

5. Facoltativamente puoi aggiungere una o più intestazioni alla richiesta HTTP. Fai clic sul pulsante Aggiungi per aggiungere la chiave e il valore di ciascuna intestazione.

   

6. Per impostazione predefinita, nessun contenuto viene inviato nel corpo della richiesta HTTP, ma specifica il contenuto da inviare nel corpo.

7. Sul nodo, scegli Tipo di dati di risposta tra le opzioni disponibili.

   Puoi fornire una risposta JSON di esempio (che in genere puoi trovare nella documentazione dell'API che stai chiamando), che genererà una variabile Power FX fortemente tipizzata, consentendoti di utilizzarla altrove nella tua area del contenuto con il supporto intellisense nell'editor di Power FX. Per fare ciò, scegli Dai dati di esempio quindi poi fai clic su Ottieni schema dal JSON di esempio, incollando la risposta di esempio nell'editor visualizzato e scegliendo Conferma.

   

8. In Salva risposta con nome scegli dove vuoi che venga archiviata la risposta della richiesta HTTP, creando una nuova variabile o selezionandone una esistente.

Invia il contenuto nel corpo della richiesta HTTP

1. Sotto Intestazioni e corpo sul nodo, fai clic sul pulsante Modifica . Verrà aperto il riquadro proprietà della richiesta HTTP.

2. In Corpo, seleziona il tipo di contenuto appropriato. Per impostazione predefinita è impostato su Nessun contenuto, dove nessun contenuto deve essere presente nel corpo della richiesta, che viene comunemente utilizzato con la richiesta GET. Per aggiungere contenuto al corpo, seleziona una delle opzioni disponibili.

   

   • Contenuto JSON: il contenuto JSON consente di fornire un oggetto JSON nel corpo della richiesta. Viene spesso utilizzato quando si effettuano richieste POST o PUT. Quando questa opzione è selezionata, ti viene presentato un editor in cui puoi inserire il tuo contenuto JSON.

     Puoi anche specificare il contenuto JSON utilizzando Power FX, consentendoti di includere valori dinamici e variabili di riferimento. Per fare ciò, seleziona il pulsante Modifica JSON, scegli Formula e quindi inserisci un oggetto Power FX (qualsiasi oggetto esistente JSON già inserito verrà convertito per te in un oggetto Power FX), che verrà convertito in JSON quando verrà effettuata la richiesta HTTP.

     

   • Contenuto non elaborato: il contenuto non elaborato ti consente di inserire una stringa di dati nel corpo della richiesta e questa stringa può essere qualsiasi tipo di contenuto specificato. Il contenuto non elaborato viene inserito utilizzando una formula Power FX, come il contenuto della stringa mostrato nell'esempio seguente.

     

Timeout e gestione degli errori

Il nodo della richiesta HTTP ha più opzioni per gestire le situazioni in cui la richiesta HTTP potrebbe non riuscire o restituire un errore.

Per impostazione predefinita, la funzione "Genera un errore". Ciò significa che quando una richiesta HTTP restituisce un errore o non viene eseguita, il copilota interromperà la sua operazione e attiverà l'argomento di sistema Errore, visualizzando un messaggio di errore.

Tuttavia, puoi configurare la gestione degli errori per non attivare l'argomento di sistema Errore e inserire invece il codice di stato HTTP e qualsiasi corpo della risposta all'errore nelle variabili specificate, permettendoti di interrogare queste variabili secondo necessità e affinché l'argomento continui a funzionare. Ciò è utile negli scenari in cui si desidera che il copilota continui l'operazione anche se una particolare richiesta HTTP fallisce.

Per configurare il comportamento di gestione degli errori.

1. Sotto Intestazioni e corpo sul nodo, fai clic sul pulsante Modifica . Verrà aperto il riquadro proprietà della richiesta HTTP.

2. Scegli il comportamento desiderato dal menu a discesa Gestione degli errori.

3. Se scegli Continua in caso di errore, configura le variabili Codice di stato e Corpo della risposta dell'errore, creando nuove variabili o selezionando variabili esistenti dal selettore.

   

In questo esempio di codice, se la richiesta HTTP fallisce, il copilota memorizzerà il codice di stato HTTP nella variabile Topic.StatusCode e il corpo della risposta nella variabile Topic.ErrorResponse. Il copilota proseguirà quindi con i passaggi successivi nell'argomento.

Il tipo di variabile Risposta all'errore sarà Qualunque. Puoi usare il Nodo Analizza valore per convertirlo in un record Power Fx.

Il riquadro delle proprietà contiene anche una proprietà Richiedi timeout, che accetta un valore in millisecondi. Il valore predefinito è 30 secondi, ma puoi modificare questo valore se necessario.