Condividi tramite

Effettuare richieste HTTP

  • Articolo

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

Prerequisiti

Usa il nodo di richiesta HTTP

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

    Screenshot dell'opzione richiesta HTTP nel menu Avanzate.

  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.

    Screenshot dell'URL dell'API completato e del menu a discesa del metodo

  4. In Intestazioni e corpo sul nodo, seleziona il pulsante Modifica, che apre il riquadro Proprietà 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.

    Screenshot dell'elenco delle coppie chiave-valore delle intestazioni per il nodo HTTP.

  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.

    Screenshot dell'editor Ottieni schema dal JSON di esempio.

  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. In Intestazioni e corpo sul nodo, seleziona il pulsante Modifica, che apre il riquadro Proprietà 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.

    Screenshot del menu a discesa delle opzioni del contenuto del corpo

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

      Screenshot del contenuto JSON selezionato per il tipo di contenuto del corpo.

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

      Screenshot del contenuto NON ELABORATO selezionato per il tipo di contenuto del corpo.

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, il copilota interrompe la sua operazione e attiva l'argomento di sistema Errore, visualizzando un messaggio di errore.

Tuttavia, è possibile configurare la gestione degli errori in modo che non attivi l'argomento di sistema Errore. Popola, invece, il codice di stato HTTP e qualsiasi errore del corpo della risposta nelle variabili specificate, consentendo di interrogare queste variabili secondo necessità e di continuare l'esecuzione di argomento. Questa configurazione è 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. In Intestazioni e corpo sul nodo, seleziona il pulsante Modifica, che apre il riquadro Proprietà 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.

    Screenshot della gestione degli errori configurata per continuare in caso di errore con le variabili specificate per il codice di stato e il corpo della risposta all'errore.

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

Il tipo di variabile Risposta con errore è Qualsiasi. Puoi usare Analizza valore nodo per convertire questa variabile in un record di 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.