Condividi tramite

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

  • Articolo

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

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.

  1. Passare a GitHub ed eseguire l'accesso se non è già stato fatto.

  2. In alto a destra seleziona l'immagine del profilo e quindi scegli Impostazioni nel menu.

    Impostazioni

  3. Nel menu a sinistra, in Impostazioni per sviluppatori, scegli Token di accesso personali.

  4. Scegli il pulsante Genera nuovo token, quindi conferma la password se richiesto.

    Generare un nuovo token

  5. Immettere una descrizione nella casella Descrizione token.

  6. Selezionare la casella di controllo admin:repo_hook.

    admin:repo_hook

  7. Scegli il pulsante Genera token.

  8. Prendere nota del nuovo token.

    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

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

  2. Nel menu del connettore, seleziona Connettore per app per la logica, quindi scegli Modifica.

    Modificare il connettore per app per la logica

  3. In Generale, scegli Carica un file OpenAPI, e quindi passa al file OpenAPI scaricato.

    Screenshot che mostra l'opzione Carica un file OpenAPI.

Importare la definizione OpenAPI per Power Automate

  1. Vai a flow.microsoft.com.

  2. Nell'angolo superiore destro scegli l'icona a forma di ingranaggio e quindi seleziona Connettori personalizzati.

    Connettori personalizzati

  3. Scegli Crea connettore personalizzato e quindi seleziona Importa un file Postman Collection.

    Creare connettore personalizzato

  4. Immetti un nome per il connettore personalizzato, quindi passa al file OpenAPI scaricato e scegli Connetti.

    Screenshot che mostra il campo per l'immissione di un nome.

    Parametro Valore
    Titolo connettore personalizzato "GitHubDemo"

Terminare la creazione del connettore personalizzato

  1. Nella pagina Generale scegli Continua.

  2. Nella pagina Sicurezza sotto Tipo di autenticazione, seleziona Autenticazione di base.

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

    Autenticazione di base

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

  1. Nella pagina Generale specifica una descrizione e un URL.

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

  2. Nella pagina Sicurezza, configura l'autenticazione di base come hai fatto nella sezione precedente.

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

  4. L'area Richiesta visualizza le informazioni in base alla richiesta HTTP per l'azione. Scegli Importa da esempio.

    Pagina di definizione: importa da esempio

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

    Crea trigger-2

    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"
  }
}

  6. L'area Risposta visualizza le informazioni in base alla risposta HTTP per l'azione. Seleziona Aggiungi risposta predefinita.

    Pagina Definizione - Risposta

  7. 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"
    }
  }
}

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

    Crea trigger-4

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

  1. In flow.microsoft.com, nella parte superiore della pagina, scegli Flussi personali.

  2. Scegli Crea da zero, quindi nella pagina successiva, seleziona Cerca tra centinaia di connettori e trigger.

    Cerca connettori

  3. Nella finestra di progettazione per Power Automate cerca il connettore personalizzato registrato in precedenza.

    Nuovo trigger

    Scegli l'elemento nell'elenco per usarlo come trigger.

  4. Dato che è la prima volta che viene usato questo connettore personalizzato, è necessario connettersi. Immetti le informazioni di connessione, quindi seleziona Crea.

    Nuova connessione

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

  5. Immettere i dettagli sul repository da monitorare. Puoi riconoscere i campi dall'oggetto WebhookRequestBody nel file OpenAPI.

    Informazioni sul repository

    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.

  6. Seleziona + Nuovo passaggio, quindi scegli Aggiungi un'azione.

  7. Cercare e selezionare l'azione Notifica push.

    Notifica push

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

    Dettagli della notifica push

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

  9. Nella parte superiore della pagina assegna un nome al flusso e fai clic su Crea flusso.

    Nome flusso

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.