Usare un webhook come trigger per App per la logica di Azure e Power Automate

Articolo
06/23/2023

I webhook sono semplici callback HTTP usati per fornire notifiche di eventi. App per la logica di Azure e Power Automate consentono di usare i webhook come trigger. Un'app per la logica o un flusso ascolta questo trigger ed esegue un'azione ogni volta che il trigger si attiva. Questa esercitazione dimostra come utilizzare un webhook come trigger.

Nota

GitHub viene usato come esempio di un servizio che può inviare notifiche tramite webhook, ma le tecniche illustrate di seguito possono essere estese a qualsiasi servizio che usa webhook.

Prerequisiti

Una delle sottoscrizioni seguenti:
- Azure, se stai usando le App per la logica
- Power Automate
Esperienza di base per la creazione delle app per la logica o dei flussi e dei connettori personalizzati.
Se usi App per la logica, prima di tutto crea un connettore personalizzato in App per la logica di Azure.
Conoscenze di base dei webhook.
Conoscenza di base della specifica OpenAPI (precedentemente nota come Swagger).
Un account GitHub.
La definizione OpenAPI di esempio per questa esercitazione.

Definizione OpenAPI

I webhook vengono implementati in App per la logica e Power Automate come parte di un connettore personalizzato ed è quindi necessario specificare una definizione OpenAPI che definisca la forma del webhook. Se vuoi creare un trigger, ma non hai una definizione OpenAPI, puoi usare l'interfaccia utente dei trigger nella procedura guidata del connettore personalizzato per definire i trigger webhook.

La definizione OpenAPI contiene tre parti fondamentali per il funzionamento del webhook:

Creazione del webhook
Definizione della richiesta di hook in ingresso dall'API (in questo caso, GitHub)
Eliminazione del webhook

Creazione del webhook

Il webhook viene creato sul lato GitHub mediante un POST HTTP a /repos/{owner}/{repo}/hooks. Quando viene creata una nuova app per la logica o flusso, viene inviato a questo URL usando il trigger definito nella definizione OpenAPI. Viene registrato anche nell'URL se il trigger viene modificato. Nell'esempio seguente la proprietà post contiene lo schema della richiesta che viene inviata a GitHub.

"/repos/{owner}/{repo}/hooks": {
    "x-ms-notification-content": {
    "description": "Details for Webhook",
    "schema": {
        "$ref": "#/definitions/WebhookPushResponse"
    }
    },
    "post": {
    "description": "Creates a Github webhook",
    "summary": "Triggers when a PUSH event occurs",
    "operationId": "webhook-trigger",
    "x-ms-trigger": "single",
    "parameters": [
        {
        "name": "owner",
        "in": "path",
        "description": "Name of the owner of targeted repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "repo",
        "in": "path",
        "description": "Name of the repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "Request body of webhook",
        "in": "body",
        "description": "This is the request body of the Webhook",
        "schema": {
            "$ref": "#/definitions/WebhookRequestBody"
        }
        }
    ],
    "responses": {
        "201": {
        "description": "Created",
        "schema": {
            "$ref": "#/definitions/WebhookCreationResponse"
        }
        }
    }
    }
},

Importante

La proprietà "x-ms-trigger": "single" è un'estensione dello schema che indica ad App per la logica e Power Automate di visualizzare il webhook nell'elenco dei trigger disponibili nella finestra di progettazione, quindi assicurarsi di includerla.

Definire la richiesta di hook in ingresso dall'API

La forma della richiesta di hook in ingresso, ossia della notifica inviata da GitHub ad App per la logica o Power Automate, è definita nella proprietà x-ms-notification-content personalizzata, come illustrato nell'esempio precedente. Non è necessario che includa l'intero contenuto della richiesta, ma solo le parti che si vuole usare nell'app per la logica o nel flusso.

Eliminare il webhook

La definizione OpenAPI deve includere una definizione su come eliminare il webhook. App per la logica e Power Automate tentano di eliminare il webhook se si aggiorna il trigger e se si elimina l'app per la logica o il flusso.

"/repos/{owner}/{repo}/hooks/{hook_Id}": {
    "delete": {
    "description": "Deletes a Github webhook",
    "operationId": "DeleteTrigger",
    "parameters": [
        {
        "name": "owner",
        "in": "path",
        "description": "Name of the owner of targeted repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "repo",
        "in": "path",
        "description": "Name of the repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "hook_Id",
        "in": "path",
        "description": "ID of the Hook being deleted",
        "required": true,
        "type": "string"
        }
    ]
    }
},

Nessuna intestazione aggiuntiva è inclusa per la chiamata di eliminazione del webhook. La stessa connessione utilizzata nel connettore viene utilizzata anche per la chiamata di eliminazione del webhook.

Importante

Affinché App per la logica o Power Automate elimini un webhook, l'API deve includere un'intestazione HTTP Location nella risposta 201 al momento della creazione del webhook. L'intestazione Location deve contenere il percorso per il webhook che viene usato con HTTP DELETE. Ad esempio, il percorso Location incluso nella risposta di GitHub segue questo formato: https://api.github.com/repos/<user name>/<repo name>/hooks/<hook ID>.

Abilitare l'autenticazione in GitHub

L'API che invia la richiesta del webhook ad App per la logica o Power Automate usa in genere una qualche forma di autenticazione e GitHub non fa eccezione. GitHub supporta diversi tipi di autenticazione; useremo i token di accesso personale GitHub per questa esercitazione.

Passare a GitHub ed eseguire l'accesso se non è già stato fatto.
In alto a destra seleziona l'immagine del profilo e quindi scegli Impostazioni nel menu.
Nel menu a sinistra, in Impostazioni per sviluppatori, scegli Token di accesso personali.
Scegli il pulsante Genera nuovo token, quindi conferma la password se richiesto.
Immettere una descrizione nella casella Descrizione token.
Selezionare la casella di controllo admin:repo_hook.
Scegli il pulsante Genera token.
Prendere nota del nuovo token.

Importante

Non sarà possibile accedere di nuovo a questo token. È necessario copiarlo e incollarlo da qualche parte per usarlo in seguito nell'esercitazione.

Importare la definizione OpenAPI

Per iniziare, importa la definizione OpenAPI per App per la logica, o per Power Automate.

Importare la definizione OpenAPI per App per la logica

Passa al portale di Azure e apri il connettore per App per la logica creato in precedenza in Creare un connettore personalizzato in App per la logica di Azure.
Nel menu del connettore, seleziona Connettore per app per la logica, quindi scegli Modifica.
In Generale, scegli Carica un file OpenAPI, e quindi passa al file OpenAPI scaricato.

Importare la definizione OpenAPI per Power Automate

Vai a flow.microsoft.com.
Nell'angolo superiore destro scegli l'icona a forma di ingranaggio e quindi seleziona Connettori personalizzati.
Scegli Crea connettore personalizzato e quindi seleziona Importa un file Postman Collection.
Immetti un nome per il connettore personalizzato, quindi passa al file OpenAPI scaricato e scegli Connetti.

Parametro Valore

Titolo connettore personalizzato "GitHubDemo"

Parametro	Valore
Titolo connettore personalizzato	"GitHubDemo"

Terminare la creazione del connettore personalizzato

Nella pagina Generale scegli Continua.
Nella pagina Sicurezza sotto Tipo di autenticazione, seleziona Autenticazione di base.
Nella sezione Autenticazione di base immettere il testo Nome utente e Password per i campi etichetta. Queste saranno le uniche etichette visualizzate quando il trigger viene usato in un'app per la logica o in un flusso.
Nella parte superiore della procedura guidata verifica che il nome sia impostato su "GitHubDemo" e quindi seleziona Crea connettore.

Ora sei pronto per usare il trigger in un'app per la logica o in un flusso oppure puoi leggere come creare i trigger dall'interfaccia utente.

Creare i trigger di webhook dall'interfaccia utente

In questa sezione, ti mostreremo come creare un trigger nell'interfaccia utente senza avere le definizioni di trigger nella definizione OpenAPI. Inizia con una definizione OpenAPI di base o ricomincia da zero con la procedura guidata del connettore personalizzato.

Nella pagina Generale specifica una descrizione e un URL.

Parametro Value

Descrizione "GitHub è un repository social di codice sorgente".

URL "api.github.com"
Nella pagina Sicurezza, configura l'autenticazione di base come hai fatto nella sezione precedente.

Parametro	Value
Descrizione	"GitHub è un repository social di codice sorgente".
URL	"api.github.com"

Nella pagina Definizione, scegli + Nuovo trigger e compila la descrizione del trigger. In questo esempio viene creato un trigger generato quando si effettua una richiesta di pull a un repository.

Crea trigger-1

Parametro	Value
Riepilogo	"Si attiva quando viene effettuata una richiesta pull in un repository selezionato"
Descrizione	"Si attiva quando viene effettuata una richiesta pull in un repository selezionato"
ID operazione	"webhook-PR-trigger"
Visibilità	"nessuno" (vedi di seguito per ulteriori informazioni)
Tipo di trigger	"Webhook"

La proprietà Visibilità per operazioni e parametri in un'app per la logica o in un flusso ha le seguenti opzioni:

nessuna: visualizzati normalmente nell'app per la logica o nel flusso
avanzata: nascosti in un menu aggiuntivo
interna: nascosti all'utente
importante: sempre mostrati all'utente come prima cosa

L'area Richiesta visualizza le informazioni in base alla richiesta HTTP per l'azione. Scegli Importa da esempio.
Definisci la richiesta per il trigger di webhook e quindi scegli Importa. Forniamo un esempio di importazione (sotto l'immagine). Per ulteriori informazioni, vedi le informazioni di riferimento sull'API GitHub. App per la logica e Power Automate aggiungono automaticamente intestazioni di sicurezza e content-type standard e non è quindi necessario definirle durante l'importazione da un esempio.

Parametro Value

Verbo "POST"

URL "https://api.github.com/repos/{owner}/{repo}/hooks"

Testo Vedi di seguito
```
{
  "name": "web",
  "active": true,
  "events": [
    "pull_request"
  ],
  "config": {
    "url": "http://example.com/webhook"
  }
}
```
L'area Risposta visualizza le informazioni in base alla risposta HTTP per l'azione. Seleziona Aggiungi risposta predefinita.

Parametro	Value
Verbo	"POST"
URL	"https://api.github.com/repos/{owner}/{repo}/hooks"
Testo	Vedi di seguito

Definisci la risposta per il trigger di webhook e quindi scegli Importa. Di nuovo, forniamo un esempio di importazione. Per ulteriori informazioni, vedi le informazioni di riferimento sull'API GitHub.

Crea trigger-3

{
  "action": "opened",
  "number": 1,
  "pull_request": {
    "html_url": "https://github.com/baxterthehacker/public-repo/pull/1",
    "state": "open",
    "locked": false,
    "title": "Update the README with new information",
    "user": {
      "login": "baxterthehacker",
      "type": "User"
    }
  }
}

Nell'area Configurazione del trigger, seleziona il parametro che deve ricevere il valore dell'URL di callback da GitHub. Questa è la proprietà url nell'oggetto config.
Nella parte superiore della procedura guidata, inserisci un nome, quindi scegli Crea connettore.

Usare il webhook come trigger

Dopo aver configurato ogni elemento, è possibile usare il webhook in un'app per la logica o in un flusso. Successivamente, crea un flusso per inviare una notifica push all'app per dispositivi mobili Power Automate ogni volta che il repository GitHub riceve un comando git push.

In flow.microsoft.com, nella parte superiore della pagina, scegli Flussi personali.
Scegli Crea da zero, quindi nella pagina successiva, seleziona Cerca tra centinaia di connettori e trigger.
Nella finestra di progettazione per Power Automate cerca il connettore personalizzato registrato in precedenza.

Scegli l'elemento nell'elenco per usarlo come trigger.
Dato che è la prima volta che viene usato questo connettore personalizzato, è necessario connettersi. Immetti le informazioni di connessione, quindi seleziona Crea.

Parametro Value

Nome connessione Un nome descrittivo

Nome utente Il nome utente GitHub

Password Il token di accesso personale creato in precedenza
Immettere i dettagli sul repository da monitorare. Puoi riconoscere i campi dall'oggetto WebhookRequestBody nel file OpenAPI.

Parametro valore

proprietario Il proprietàrio del repository da monitorare

repo Il repository da monitorare

Importante

È necessario usare un repository per il quale l'account usato ha i diritti. Il modo più semplice consiste nell'usare il proprio repository.
Seleziona + Nuovo passaggio, quindi scegli Aggiungi un'azione.
Cercare e selezionare l'azione Notifica push.
Inserisci del testo nel campo Testo e negli altri campi, utilizzando i valori della finestra di dialogo del contenuto dinamico. Questi valori provengono dall'oggetto WebhookPushResponse nel file OpenAPI.

Parametro valore

Nome connessione Un nome descrittivo

Nome utente Il nome utente GitHub

Password Il token di accesso personale creato in precedenza
Nella parte superiore della pagina assegna un nome al flusso e fai clic su Crea flusso.

Parametro	Value
Nome connessione	Un nome descrittivo
Nome utente	Il nome utente GitHub
Password	Il token di accesso personale creato in precedenza

Parametro	valore
proprietario	Il proprietàrio del repository da monitorare
repo	Il repository da monitorare

Parametro	valore
Nome connessione	Un nome descrittivo
Nome utente	Il nome utente GitHub
Password	Il token di accesso personale creato in precedenza

Verifica e risoluzione dei problemi

Per verificare che tutto sia configurato correttamente, scegli Flussi personali e quindi seleziona l'icona delle informazioni accanto al nuovo flusso per visualizzare la cronologia di esecuzione:

Dovrebbe essere già visibile almeno un'esecuzione completata correttamente dalla creazione del webhook. Questo indica che il webhook è stato creato correttamente sul lato di GitHub.
Se l'esecuzione non è riuscita, è possibile analizzare i dettagli di esecuzione per scoprire i motivi dell'errore. Se l'errore è dovuto a una risposta "404 Non trovato", è probabile che l'account GitHub non abbia le autorizzazioni corrette per creare un webhook nel repository usato.

Riepilogo

Se tutto è configurato correttamente, si riceveranno notifiche push nell'app per dispositivi mobili Power Automate ogni volta che si verifica un comando git push nel repository GitHub selezionato. Tramite il processo descritto sopra è possibile usare qualsiasi servizio in grado di supportare webhook come trigger nei flussi.

Passaggi successivi

Inviare commenti

L'invio da parte degli utenti di feedback sui problemi riscontrati con la piattaforma di connettori o di idee su nuove funzionalità è molto apprezzato. Per fornire un feedback, vai a Inviare problemi o ottenere assistenza per i connettori e seleziona il tipo di commenti.