Usa un webhook come attivatore per App per la logica di Azure e Power Automate

I webhook sono semplici callback HTTP che forniscono notifiche degli eventi quando si verifica qualcosa in un servizio Web. In App per la logica di Azure e Power Automate è possibile usare 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 illustra come usare un webhook come trigger tramite un connettore personalizzato definito con una specifica OpenAPI.

Nota

Questo articolo usa GitHub come esempio di un servizio che può inviare notifiche tramite webhook, ma è possibile estendere le tecniche illustrate qui a qualsiasi servizio che consenta webhook.

Prerequisiti

Abilitare l'autenticazione in GitHub

Un'API di un servizio Web che invia una richiesta webhook a Logic Apps o Power Automate in genere usa una forma di autenticazione, e GitHub non fa eccezione. GitHub supporta diversi tipi di autenticazione. Questa esercitazione usa i token di accesso personali a granularità fine di GitHub.

  1. Passare a GitHub e accedere se non è già stato fatto.

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

  3. Nel menu a sinistra selezionare Impostazioni sviluppatore.

  4. In Token di accesso personali selezionare Token dettagliato.

  5. Selezionare il pulsante Genera nuovo token , quindi confermare la password, se richiesto.

  6. Immettere un nome token e una descrizione per il token.

  7. In Scadenza selezionare una data di scadenza per il token.

  8. In Accesso al repository selezionare Solo repository e selezionare il repository a cui si vuole concedere l'accesso.

  9. In Autorizzazioni selezionare Aggiungi autorizzazioni>Webhook>Lettura e scrittura.

  10. Selezionare il pulsante Genera token .

  11. Prendere nota del nuovo token. È necessario usare questo token in un secondo momento quando si aggiunge il connettore webhook come trigger.

    Importante

    Non è possibile accedere di nuovo a questo token. Copiarlo e incollarlo da qualche parte da usare più avanti nell'esercitazione.

Definire il webhook nella definizione OpenAPI

Si implementano webhook in Logic Apps e Power Automate come parte di un connettore personalizzato. Per creare il connettore, è necessario fornire una definizione OpenAPI che definisce la forma del webhook. Questa esercitazione usa una definizione OpenAPI di esempio scaricata per GitHub webhook.

Se si vuole creare un trigger ma non si dispone di una definizione OpenAPI da cui lavorare, usare l'interfaccia utente dei trigger nella procedura guidata del connettore personalizzato per definire i trigger webhook.

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

  • Creazione del webhook
  • Definizione della richiesta hook in ingresso dall'API del servizio Web (in questo esempio di esercitazione GitHub)
  • Eliminazione del webhook

Il connettore usa questa definizione OpenAPI per comprendere come creare, ricevere ed eliminare webhook per il repository GitHub.

Creare il webhook

Il connettore usa l'API del servizio Web (in questo esempio, l'API REST GitHub) per creare il webhook sul lato servizio Web inviando una richiesta HTTP POST all'endpoint di creazione webhook appropriato per il servizio Web (/repos/{owner}/{repo}/hooks nel caso di GitHub).

Quando si crea una nuova app per la logica o un flusso usando il connettore, il connettore invia una richiesta POST all'endpoint di creazione webhook del servizio Web come definito nella definizione OpenAPI del connettore. Invia anche una richiesta POST a questo URL se si modifica l'app per la logica o il trigger di flusso. Nella configurazione del percorso OpenAPI di esempio seguente la post proprietà contiene lo schema della richiesta di creazione del webhook da inviare all'API REST 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 a Logic Apps e Power Automate di mostrare questo webhook nell'elenco dei trigger disponibili nel designer. Assicurarsi di includerlo.

Definire la richiesta di hook in ingresso dall'API

Definisci la struttura della richiesta hook in ingresso (la notifica da GitHub a Logic Apps o Power Automate) nella proprietà personalizzata x-ms-notification-content, come mostrato nell'esempio precedente. La richiesta non deve contenere l'intero contenuto della richiesta, ma solo le parti da usare nell'app per la logica o nel flusso.

Eliminare il webhook

Includere una definizione per eliminare il webhook nella definizione OpenAPI. App per la logica e Power Automate tentano di eliminare il webhook esistente se si aggiorna il trigger o 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 webhook being deleted",
                "required": true,
                "type": "string"
            }
        ]
    }
},

Non è incluso alcun header per la chiamata DELETE del webhook. La chiamata di eliminazione del webhook usa la stessa connessione del connettore.

Importante

Per consentire a Logic Apps o Power Automate di eliminare un webhook, l'API del servizio web deve includere un'intestazione HTTP Location nella risposta 201 quando viene creato il webhook. L'intestazione Location deve contenere il percorso del webhook usato con il metodo HTTP DELETE. Ad esempio, l'Locationintestazione inclusa nella risposta di GitHub segue questo formato: https://api.github.com/repos/<user name>/<repo name>/hooks/<hook ID>.

Importare la definizione OpenAPI

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

Importare la definizione OpenAPI per Logic Apps

  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 seleziona Modifica.

    Screenshot dell'opzione Modifica per il connettore Logic Apps.

  3. In Generale selezionare Carica un file OpenAPI e quindi passare al file OpenAPI di esempio scaricato.

    Screenshot dell'opzione Carica un file OpenAPI.

Importare la definizione OpenAPI per Power Automate

  1. Andare alla pagina https://make.powerautomate.com/.

  2. Nell'angolo in alto a destra selezionare l'icona a forma di ingranaggio e quindi selezionare Connettori personalizzati.

    Screenshot del menu dell'icona a forma di ingranaggio con l'opzione Connettori personalizzati.

  3. Selezionare Crea connettore personalizzato, quindi selezionare Importa una raccolta di Postman.

    Screenshot del menu Crea connettore personalizzato con le opzioni di importazione.

  4. Immettere un nome per il connettore personalizzato, passare al file OpenAPI di esempio scaricato e selezionare Connetti.

    Schermata del campo per immettere un nome personalizzato del connettore.

    Parametro Valore
    Titolo del connettore personalizzato "GitHubDemo"

Terminare la creazione del connettore personalizzato

  1. Nella pagina Generale selezionare 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 etichette vengono visualizzate quando si utilizza il trigger in un'app per la logica o in un flusso.

    Schermata dei campi dell'etichetta di autenticazione di base.

  4. Nella parte superiore della procedura guidata verificare che il nome sia impostato su "GitHubDemo" e quindi scegliere 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 si apprenderà come creare un trigger nell'interfaccia utente senza avere 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 assicurarsi di specificare una descrizione e un URL.

    Parametro Valore
    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 scegliere Nuovo trigger e compilare la descrizione per il trigger. In questo esempio, si crea un trigger che si attiva quando viene creata una pull request in un repository.

    Schermata dei nuovi campi delle informazioni generali del trigger.

    Parametro Valore
    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 attivazione "Webhook"

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

    • nessuno: visualizzato 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.

    Schermata della pagina Definizione con l'opzione Importa da un esempio.

  5. Definire la richiesta per il trigger webhook e quindi selezionare Importa. Viene fornito un esempio da importare (nella sezione seguente). Per ulteriori informazioni, vedi le informazioni di riferimento sull'API GitHub. Logic Apps e Power Automate aggiungono automaticamente intestazioni standard e di sicurezza content-type, quindi non è necessario definirle durante l'importazione da un esempio.

    Schermata della finestra di dialogo per l'importazione della richiesta del trigger webhook.

    Parametro Valore
    Verbo "POST"
    URL "https://api.github.com/repos/{owner}/{repo}/hooks"
    Corpo 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. Selezionare Aggiungi risposta predefinita.

    Schermata dell'area Risposta della pagina Definizione con l'opzione Aggiungi risposta predefinita.

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

    Schermata della finestra di dialogo per l'importazione della risposta per il trigger del webhook. 

    {
  "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. Questo parametro è la url proprietà nell'oggetto config .

    Screenshot dell'area di configurazione Trigger con il parametro URL di callback selezionato.

  9. Nella parte superiore della procedura guidata, immettere un nome e quindi scegliere Crea connettore.

Usa il webhook come trigger

Dopo aver configurato tutti gli elementi, usa il webhook tramite il connettore personalizzato in un'app per la logica o in un flusso. Creare quindi un flusso che invia un messaggio di posta elettronica ogni volta che il repository GitHub riceve un push Git.

  1. In https://make.powerautomate.com/, nella parte superiore della pagina selezionare Flussi personali.

  2. Seleziona Crea da zero.

    Schermata dell'opzione Cerca centinaia di connettori e trigger.

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

    Schermata della ricerca del trigger del connettore personalizzato nella progettazione di Power Automate.

  4. Selezionare l'elemento nell'elenco per usarlo come trigger.

  5. Poiché è la prima volta che hai usato questo connettore personalizzato, connettiti ad esso. Immettere le informazioni di connessione e quindi selezionare Crea.

    Schermata dei nuovi campi delle informazioni sulla connessione.

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

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

    Schermata dei campi del proprietario e del nome del repository per il trigger.

    Parametro Valore
    proprietario Il proprietario del repository da monitorare
    repo Il repository da monitorare

    Importante

    Usa un repo per cui il tuo account dispone delle autorizzazioni necessarie. Il modo più semplice per eseguire questa operazione consiste nell'usare il proprio repository.

  7. Selezionare Nuovo passaggio>Aggiungi un'azione.

  8. Cercare e selezionare l'azione Invia un messaggio di posta elettronica (V2).

  9. Immettere testo nel campo Corpo e negli altri campi, usando i valori della finestra di dialogo contenuto dinamico. I valori provengono dall'oggetto WebhookPushResponse nel file OpenAPI.

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

    Schermata del campo Nome flusso e del pulsante Crea flusso.

Verifica e risoluzione dei problemi

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

  • Dovresti già vedere almeno un'esecuzione completata in seguito alla creazione del webhook. Questa esecuzione indica che il webhook è stato creato correttamente sul lato GitHub.
  • Se l'esecuzione non è riuscita, esaminare i dettagli dell'esecuzione per verificare il motivo per cui non è riuscito. Se l'errore è dovuto a una 404 Not Found risposta, è probabile che l'account GitHub non disponga delle autorizzazioni corrette per creare un webhook nel repository usato.

Riepilogo

Se tutto è stato configurato correttamente, si ricevono notifiche push nell'app per dispositivi mobili Power Automate ogni volta che si verifica un push Git nel repository GitHub selezionato. Usando il processo precedente, è possibile usare qualsiasi servizio che supporta webhook come trigger nei flussi.

Passaggi successivi

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

  • Ultimo aggiornamento: