Effettuare richieste HTTP

In Copilot Studio puoi estendere le funzionalità dell'agente chiamando API REST esterne utilizzando il nodo di richiesta HTTP. Questa chiamata 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. Selezionare l'icona Aggiungi nodo sotto il nodo dopo il quale si vuole chiamare un'API esterna, scegliere Avanzate e selezionare 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. In Intestazioni e corpo del nodo seleziona il pulsante Modifica, che apre il pannello Proprietà della richiesta HTTP.

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

   

   È possibile usare la sezione intestazioni per passare token di autenticazione, tipo di contenuto o qualsiasi altra intestazione obbligatoria per l'API che si sta chiamando. Ad esempio, è possibile aggiungere un'intestazione come Authorization: Bearer <your_token> per autenticare la richiesta.

6. Per impostazione predefinita, nel corpo della richiesta HTTP non viene inviato alcun contenuto, ma è possibile specificare il contenuto nel corpo.

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

   Puoi fornire un esempio di risposta JSON, che solitamente puoi trovare nella documentazione dell'API che stai chiamando. Genera una variabile Power Fx, che ti consente di utilizzarla altrove nel tuo ambiente di creazione, con supporto per IntelliSense nell'editor di Power Fx. Seleziona Dai dati di esempio, quindi seleziona Ottieni lo schema da JSON di esempio. Incolla la tua risposta di esempio nell'editor e seleziona Conferma.

8. In Salva risposta utente con nome sceglie dove archiviare la risposta alla richiesta HTTP, creando una nuova variabile o selezionandone una esistente.

Invia il contenuto nel corpo della richiesta HTTP

1. In Intestazioni e corpo del nodo seleziona il pulsante Modifica, che apre il pannello Proprietà della richiesta HTTP.

2. In Corpo, seleziona il tipo di contenuto appropriato. Per impostazione predefinita, Corpo è impostato su Nessun contenuto, in base al quale non deve essere presente alcun contenuto all'interno di corpo della richiesta, che viene utilizzato più comunemente 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. Questo oggetto viene spesso utilizzato quando si effettuano richieste POST o PUT. Selezionando questa opzione, un editor ti consentirà di inserire il contenuto JSON.

     Puoi anche specificare il contenuto JSON utilizzando Power Fx, in modo da includere valori dinamici e variabili di riferimento. Seleziona il pulsante Modifica JSON, scegli Formula, quindi inserisci un oggetto Power Fx (qualsiasi JSON esistente inserito viene convertito in un oggetto Power Fx), che viene convertito in JSON quando viene 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 immesso utilizzando una formula Power Fx, come il contenuto stringa mostrato nell'esempio seguente.

     

Timeout e gestione degli errori

Il nodo richiesta HTTP ha diverse opzioni per gestire le situazioni in cui la richiesta HTTP potrebbe fallire o restituire un errore.

Per impostazione predefinita, la funzionalità genera un errore. Ciò significa che quando una richiesta HTTP restituisce un errore o non viene eseguita, l'agente interrompe l'operazione e attiva l'argomento del sistema On Error, visualizzando un messaggio di errore.

Tuttavia, puoi configurare la gestione degli errori in modo che non attivi l'argomento di sistema On Error. È invece possibile fare in modo che archivi il codice di stato HTTP e qualsiasi corpo della risposta di errore in variabili specificate. Puoi interrogare queste variabili in base alle esigenze e l'argomento può continuare a essere eseguito. Questa configurazione è utile negli scenari in cui si desidera che l'agente continui a funzionare, anche se una particolare richiesta HTTP non riesce.

Per configurare il comportamento di gestione degli errori di un nodo Richiesta HTTP:

1. In Intestazioni e corpo seleziona Modifica. Viene visualizzato il pannello Proprietà delle richieste HTTP.

2. In Gestione errori seleziona il comportamento desiderato: Genera un errore o Continua in caso di errore.

3. Se selezioni Continua in caso di errore, configura le variabili per il codice di stato e il corpo della risposta di errore.

   

In questo esempio, se la richiesta HTTP ha esito negativo, l'agente archivia il codice di stato HTTP nella variabile Topic.StatusCode e il corpo della risposta nella variabile Topic.ErrorResponse. L'agente continua con i passaggi successivi nell'argomento.

Il tipo di variabile Risposta con errore è Qualsiasi. Puoi usare un nodo Analizza valore per convertire questa variabile in un record di Power Fx.

Nel pannello Proprietà delle richieste HTTP è anche possibile impostare una proprietà Timeout della richiesta, in millisecondi. Il valore predefinito è 30 secondi.