Trigger webhook
I webhook sono implementazioni molto diffuse basate su HTTP di un modello di notifica più generico editore-sottoscrittore. Consentono di inviare notifiche a un servizio esterno (sottoscrittore) ogni volta che si verificano determinati eventi all'interno di un sistema (editore).
Power Automate e App per la logica di Azure consentono ai creatori di usare i webhook come trigger. In questo scenario, i trigger ricoprono il ruolo di un sottoscrittore che registra e annulla la registrazione dei webhook per conto di un creatore. La registrazione si verifica quando viene creato o aggiornato un passaggio in un flusso cloud o in un flusso di lavoro di App per la logica. Quando il passaggio viene rimosso, la piattaforma annulla la registrazione del webhook.
Anche in questo caso, così come nella configurazione del connettore, Copilot può essere di aiuto. È possibile iniziare con semplici richieste e, man mano che si procede, migliorare l'implementazione:
"Come faccio a definire un trigger HTTP per il mio connettore personalizzato?"
"Quali parametri devo includere nel trigger del mio connettore personalizzato?"
"Puoi controllare la mia logica del trigger e vedere se posso migliorarlo?"
Copilot può suggerire il modo ottimale per definire i trigger in base all'API e ai requisiti del flusso.
Lo screenshot seguente mostra un esempio di interazione tra sottoscrittore ed editore.
Le responsabilità delle parti sono descritte nella tabella seguente.
| Editore (connettore personalizzato OpenAPI) | Sottoscrittore (Power Automate/App per la logica) |
|---|---|
| Fornisce l'endpoint di registrazione della sottoscrizione. | Chiama l'endpoint di registrazione della sottoscrizione quando viene creato o aggiornato un trigger in un flusso. |
| Specifica il contratto di notifica, ovvero l'oggetto che verrà passato con ogni notifica. Deve includere l'intestazione HTTP Location nella risposta 201 al momento della creazione di un webhook. | Fornisce l'URL dell'endpoint generato automaticamente che accetterà i messaggi di notifica. |
| Mantiene il registro dei sottoscrittori e i relativi endpoint di notifica. | Riceve e archivia le informazioni sulla posizione che verranno usate per annullare la registrazione del webhook. |
| Emette una richiesta POST a ogni endpoint registrato e passa i dati rilevanti nel corpo del messaggio. | Riceve le notifiche, le convalida rispetto allo schema definito dal connettore personalizzato e quindi attiva l'automazione. |
| Annulla la registrazione/rimuove gli endpoint in risposta al messaggio DELETE. | Invia un messaggio DELETE per annullare la registrazione del webhook quando il passaggio del trigger viene eliminato. |
I webhook forniscono solo il meccanismo di notifica e non supportano la modifica dei dati. Spesso, l'implementazione di un webhook viene completata da una o più azioni progettate per supportare il recupero e la modifica di dati o oggetti.
Requisiti API
Per fornire il supporto per i webhook richiesto dai connettori personalizzati, l'implementazione dell'API deve fornire i seguenti parametri:
Un endpoint che accetta il messaggio di registrazione e restituisce le informazioni sulla posizione
Una definizione del corpo del messaggio inviato con i messaggi di notifica
Un endpoint per accettare il messaggio DELETE e rimuovere la registrazione del webhook
Di solito, l'implementazione dell'API mantiene un elenco interno di sottoscrittori attivi, in cui ogni sottoscrittore viene identificato da un URL univoco. Per restituire questo URL al sottoscrittore, una creazione del webhook corretta deve restituire una risposta HTTP 201 e deve includere un'intestazione HTTP Location. Il valore di questa posizione viene usato in seguito dal sottoscrittore per eliminare la registrazione del webhook.
Creazione di un trigger webhook
I connettori personalizzati usano OpenAPI per descrivere l'implementazione dell'API dell'editore, come richiesto dai webhook. Per definire un trigger webhook in un connettore personalizzato, è necessario includere tre parti essenziali nella definizione OpenAPI:
Un messaggio POST che descrive la registrazione del webhook
La definizione del contenuto per le risposte del webhook
Un messaggio DELETE che descrive il processo di eliminazione del webhook
Messaggio di registrazione
La definizione del trigger deve includere un metodo POST usato per registrare un webhook. La definizione è simile a quella delle azioni.
La versione della specifica OpenAPI usata da Microsoft Power Platform non distingue tra azioni e trigger. La definizione del connettore personalizzato usa l'estensione personalizzata x-ms-trigger per dichiarare un trigger.
paths:
/webhooks:
post:
operationId: OrderCreated
x-ms-trigger: single
La presenza dell'estensione x-ms-trigger indica che il metodo è un trigger e non un'azione. Quando un trigger viene creato con la procedura guidata, questa estensione viene aggiunta automaticamente. Tuttavia, quando un connettore personalizzato viene creato dalle definizioni OpenAPI esterne, il processo di importazione crea sempre delle azioni. In questo scenario, è necessario ricreare i trigger con la procedura guidata, quindi rimuovere le definizioni delle azioni corrispondenti.
I possibili valori per l'estensione x-ms-trigger sono single o batch per distinguere tra le risposte oggetto e le risposte array. Se un webhook genera una notifica per ogni modifica, viene incluso un solo oggetto. Questo è l'approccio più comune con i webhook. Quando più modifiche vengono combinate in una singola notifica, viene inviato un array di oggetti. Questo approccio in genere viene usato nei trigger di poll e verrà affrontato più avanti nel modulo.
Risposta webhook
Le definizioni dei connettori personalizzati possono descrivere il contenuto delle risposte webhook in arrivo dal servizio quando si verifica un evento. Sebbene non siano obbligatorie, queste definizioni identificano i valori dinamici disponibili per il creatore durante la progettazione nell'elenco dei contenuti dinamici.
Nota
Questa risposta non è della richiesta che crea e registra il webhook. Questi dati vengono inviati dal servizio quando si verifica un evento.
La proprietà personalizzata x-ms-notification-content è un'altra estensione usata in OpenAPI per definire lo schema di risposta del webhook.
paths:
/webhooks:
x-ms-notification-content:
description: Order
schema:
type: object
properties:
id: {type: integer, format: int32, description: id}
order_key: {type: string, description: order_key}
status: {type: string, description: status}
currency: {type: string, description: currency}
date_created: {type: string, description: date_created}
total: {type: number, description: total, format: decimal}
Suggerimento
Una definizione della risposta webhook non deve contenere l'intero contenuto della risposta, ma solo le parti da esporre ai creatori del flusso in fase di progettazione nell'elenco dei contenuti dinamici.
I dati inviati con la risposta webhook non devono contenere necessariamente tutte le proprietà richieste dall'oggetto sottostante. In queste situazioni, è opportuno creare altre azioni nel connettore personalizzato per il recupero delle informazioni. Ad esempio, un negozio Web potrebbe inviare solo un nuovo identificatore dell'ordine con la notifica "Quando viene creato un nuovo ordine". Il connettore personalizzato può quindi definire un'azione, ad esempio "Ottieni dettagli ordine", che accetta un identificatore dell'ordine e restituisce informazioni estese sull'ordine.
È valida anche la procedura inversa. Le risposte webhook potrebbero fornire informazioni superflue non richieste o necessarie in circostanze normali. È sufficiente descrivere i dati da mostrare nell'interfaccia del creatore in Power Automate o in App per la logica. Se il creatore ha bisogno di accedere a ulteriori dati inviati nella notifica, può usare le funzioni JSON per estrarre direttamente queste proprietà dal messaggio ricevuto.
Messaggio di eliminazione
Per eliminare un webhook in Power Automate o App per la logica, l'API deve includere un'intestazione HTTP Location nella risposta al momento della creazione del webhook.
Importante
È necessario definire il percorso della richiesta di eliminazione del webhook come azione interna. Questa azione invierà una richiesta DELETE all'URL specificato nell'intestazione della posizione.
Se questa azione non è definita o se l'API non include l'intestazione della posizione, i webhook verranno creati ma non eliminati, causando possibili problemi nell'implementazione dell'API durante il runtime.
L'implementazione dei webhook offre un meccanismo flessibile per fornire supporto per i trigger in un connettore personalizzato. Tuttavia, non tutte le API supportano le integrazioni di webhook. L'implementazione del polling offre un modo alternativo per creare trigger nei connettori personalizzati.