Utilizar um webhook como acionador para o Azure Logic Apps e o Power Automate

Webhooks são callbacks HTTP simples que fornecem notificações de eventos quando algo acontece num serviço web. No Azure Logic Apps e no Power Automate, pode utilizar webhooks como accionadores. Uma aplicação lógica ou fluxo reconhece este acionador e efetua uma ação sempre que ele é acionado. Este tutorial demonstra como usar um webhook como gatilho através de um conector personalizado definido com uma especificação OpenAPI.

Nota

Este artigo usa o GitHub como exemplo de um serviço que pode enviar notificações através de webhooks, mas pode estender as técnicas aqui demonstradas a qualquer serviço que permita webhooks.

Pré-requisitos

• Uma das seguintes subscrições:
  • Azure, se estiver a utilizar Logic Apps
  • Power Automate
• Experiência básica a construir aplicações lógicas ou fluxos na cloud, e a criar conectores personalizados a partir das definições da OpenAPI.
• Se você estiver a usar Aplicativos Lógicos, primeiro crie um conector personalizado de Aplicativos Lógicos do Azure.
• Compreensão básica dos webhooks.
• Compreensão básica da OpenAPI especificação (anteriormente conhecida como Swagger).
• Uma conta do GitHub .
• A definição OpenAPI de exemplo para este tutorial. Se ainda não o tens, descarrega-o para usar nos passos seguintes. Caso contrário, precisa de criar uma definição OpenAPI personalizada para o seu webhook.

Ative a autenticação no GitHub

Uma API de serviço web que envia um pedido de webhook para Logic Apps ou Power Automate normalmente utiliza algum tipo de autenticação, e o GitHub não é exceção. O GitHub suporta vários tipos de autenticação. Este tutorial utiliza tokens de acesso pessoal detalhados do GitHub.

1. Vai ao GitHub e inicia sessão se ainda não o fizeste.

2. No canto superior direito, selecione a sua foto de perfil e, no menu, selecione Definições.

3. No menu à esquerda, selecione Definições de Desenvolvedor.

4. Em Tokens de acesso pessoal, selecione Tokens detalhados.

5. Selecione o botão Gerar novo token e depois confirme a sua palavra-passe se solicitado.

6. Introduza um nome do token e uma descrição para o token.

7. Em Expiração, selecione uma data de expiração para o token.

8. Em Acesso ao Repositório, selecione Apenas selecionar repositórios e selecione o repositório ao qual quer dar acesso.

9. Em Permissões, selecione Adicionar permissões>Webhooks>Ler e escrever.

10. Selecione o botão Gerar token .

11. Tome nota do novo token. Precisas de usar este token mais tarde quando adicionares o conector do teu webhook como gatilho.

    Importante

    Não podes aceder a este token outra vez. Copia e cola em algum sítio para usar mais tarde no tutorial.

Defina o webhook na definição do OpenAPI

Implementas webhooks no Logic Apps e no Power Automate como parte de um conector personalizado. Para criar o conector, é necessário fornecer uma definição OpenAPI que defina a forma do webhook. Este tutorial utiliza uma definição OpenAPI de exemplo descarregada para webhooks do GitHub.

Se quiseres criar um acionador mas não tens uma definição OpenAPI com que trabalhar, usa a interface de utilizador de acionadores no assistente de conectores personalizados para definir acionadores de webhook.

A definição de exemplo do OpenAPI contém três partes que são críticas para fazer o webhook funcionar:

• Criação do webhook
• Definir o pedido de hook recebido da API do serviço web (neste exemplo tutorial, GitHub)
• Eliminar o webhook

O conector utiliza esta definição OpenAPI para compreender como criar, receber e eliminar webhooks para o repositório GitHub.

Criar o webhook

O conector utiliza a API do serviço web (no nosso exemplo, a API REST do GitHub) para criar o webhook do lado do serviço web, enviando um pedido HTTP POST para o endpoint de criação do webhook apropriado para o serviço web (/repos/{owner}/{repo}/hooksno caso do GitHub).

Quando cria uma nova aplicação lógica ou um novo fluxo utilizando o conector, o conector envia um pedido HTTP POST para o ponto final de criação do webhook do serviço Web, conforme definido na definição OpenAPI do conector. Também envia um pedido HTTP POST para este URL se modificar a aplicação lógica ou o acionador do fluxo. No exemplo seguinte de configuração do caminho OpenAPI, a post propriedade contém o esquema do pedido de criação de webhook para enviar para a API REST do 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

A propriedade "x-ms-trigger": "single" é uma extensão de esquema que indica ao Logic Apps e ao Power Automate para apresentarem este webhook na lista de acionadores disponíveis no estruturador. Não te esqueças de o incluir.

Definir o pedido de hook recebido a partir da API

Defina a forma do pedido de hook recebido (a notificação do GitHub para Logic Apps ou Power Automate) na propriedade personalizadax-ms-notification-content, como mostrado no exemplo anterior. O pedido não precisa de conter todo o conteúdo do pedido, apenas as partes que quer usar na sua aplicação de lógica ou fluxo.

Eliminar o webhook

Inclua uma definição de como eliminar o webhook na definição da OpenAPI. As Logic Apps e o Power Automate tentam eliminar o webhook existente se atualizares o trigger, ou se apagares a aplicação lógica ou o fluxo.

"/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"
            }
        ]
    }
},

Não há cabeçalho incluído para a chamada de apagar o webhook. A chamada para eliminar o webhook usa a mesma conexão que o conector.

Importante

Para permitir que o Logic Apps ou o Power Automate eliminem um webhook, a API do serviço web deve incluir um Location cabeçalho HTTP na resposta 201 quando o webhook é criado. O Location cabeçalho deve conter o caminho para o webhook usado com o método HTTP DELETE. Por exemplo, o Location cabeçalho incluído na resposta do GitHub segue este formato: https://api.github.com/repos/<user name>/<repo name>/hooks/<hook ID>.

Importar a definição de OpenAPI

Comece importando a OpenAPI definição para Aplicativos Lógicos ou para Power Automate.

Importar a definição de OpenAPI para Logic Apps

1. Vá para o portal do Azure e abra o conector de Aplicativos Lógicos que você criou anteriormente em Criar um conector personalizado de Aplicativos Lógicos do Azure.

2. No menu do conector, selecione Conector de aplicativos lógicos e, em seguida, selecione Editar.

   

3. Em Geral, selecione Carregar um ficheiro OpenAPI e depois vá ao ficheiro OpenAPI de exemplo que descarregou.

   

Importar a definição de OpenAPI para o Power Automate

1. Aceda a https://make.powerautomate.com/.

2. No canto superior direito, selecione o ícone de engrenagem e depois selecione Conectores personalizados.

   

3. Selecione Criar conector personalizado e depois selecione Importar uma coleção do Postman.

   

4. Introduza um nome para o conector personalizado, vá ao ficheiro OpenAPI de exemplo que descarregou e selecione Conectar.

   

   Parâmetro	valor
   Título do conector personalizado	"GitHubDemo"

Concluir a criação do conector personalizado

1. Na página Geral , selecione Continuar.

2. Na página Segurança , em Tipo de autenticação, selecioneAutenticação básica.

3. Na secção Autenticação básica, para os campos de rótulo, digite o texto Nome de utilizador e Senha. Estes rótulos aparecem quando usas o gatilho numa aplicação lógica ou fluxo.

   

4. No topo do assistente, certifica-te de que o nome está definido como "GitHubDemo" e depois escolhe Criar conector.

Agora você está pronto para usar o gatilho em um aplicativo lógico ou fluxo, ou pode ler sobre como criar gatilhos a partir da interface do utilizador.

Criar acionadores de webhook a partir da UI

Nesta secção, aprende como criar um trigger na interface sem ter definições de trigger na definição da OpenAPI. Comece com uma definição de OpenAPI de linha base ou comece do zero no assistente de conector personalizado.

1. Na página Geral , certifique-se de especificar uma descrição e uma URL.

   Parâmetro	valor
   Descrição	"O GitHub é um repositório de código de origem social."
   URL	"api.github.com"

2. Na página Segurança, configure a autenticação básica tal como fez na secção anterior.

3. Na página de Definição , escolha Novo gatilho e preencha a descrição do seu gatilho. Neste exemplo, vai criar um gatilho que é acionado quando é criado um pull request num repositório.

   

   Parâmetro	valor
   Resumo	É acionado quando é criado um pull request num repositório selecionado
   Descrição	É acionado quando é criado um pull request no repositório selecionado
   ID da operação	"webhook-PR-trigger"
   Visibilidade	"nenhum" (para mais informações, ver abaixo)
   Tipo de acionamento	"Webhook"

   A propriedade Visibility das operações e dos parâmetros numa aplicação lógica ou fluxo tem as seguintes opções:

   • nenhum: apresentado normalmente na aplicação lógica ou no fluxo
   • Avançado: oculto sob um menu adicional
   • interna: oculta do utilizador
   • Importante: Sempre mostrado ao utilizador primeiro

4. A área Solicitação exibe informações com base na solicitação HTTP para a ação. Escolha Importar da amostra.

   

5. Defina o pedido para o gatilho do webhook e depois selecione Importar. Fornecemos um exemplo para importar (na secção seguinte). Para obter mais informações, consulte a referência da API doGitHub. Os Aplicativos Lógicos e o Power Automate adicionam automaticamente cabeçalhos padrão content-type e de segurança, para que você não precise defini-los ao importar de uma amostra.

   

   Parâmetro	valor
   Verbo	"POST"
   URL	"https://api.github.com/repos/{owner}/{repo}/hooks"
   Corpo	Ver abaixo

   {
     "name": "web",
     "active": true,
     "events": [
       "pull_request"
     ],
     "config": {
       "url": "http://example.com/webhook"
     }
   }
   

6. A área Resposta exibe informações com base na resposta HTTP para a ação. Selecione Adicionar resposta padrão.

   

7. Defina a resposta para o gatilho do webhook e depois selecione Importar. Mais uma vez, fornecemos um exemplo para importar. Para obter mais informações, consulte a referência da API doGitHub.

   

   {
     "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. Na área configuração do acionador, selecione o parâmetro que deve receber o valor da URL de callback do GitHub. Este parâmetro é a url propriedade no config objeto.

   

9. No topo do assistente, introduza um nome e depois escolha Criar conector.

Utilizar o webhook como acionador

Depois de configurar tudo, utilize o webhook através do conector personalizado numa aplicação lógica ou num fluxo. De seguida, cria um fluxo que envie um email sempre que o teu repositório do GitHub recebe um push do git.

1. Em https://make.powerautomate.com/, no topo da página, selecione os meus fluxos.

2. Selecione Criar a partir do zero.

   

3. No estruturador do Power Automate, procure o conector personalizado que registou anteriormente.

   

4. Selecione o item da lista para o usar como gatilho.

5. Como é a primeira vez que usas este conector personalizado, liga-o a ele. Insira a informação da ligação e depois selecione Criar.

   

   Parâmetro	valor
   Nome da conexão	Um nome descritivo
   Nome de utilizador	O seu nome de utilizador no GitHub
   Palavra-passe	O token de acesso pessoal que criou anteriormente

6. Introduza os detalhes do repositório que quer monitorizar. Poderá reconhecer os campos do objeto WebhookRequestBody no ficheiro OpenAPI.

   

   Parâmetro	valor
   proprietário	O proprietário do repositório a monitorizar
   Repositório	O repositório a monitorizar

   Importante

   Usa um repositório sobre o qual a tua conta tem direitos. A forma mais fácil de fazer isto é usar o teu próprio repositório.

7. Selecione Nova etapa>Adicionar uma ação.

8. Procure e selecione a ação Enviar um email (V2 ).

9. Introduza texto no campo Corpo e nos outros campos, usando valores da caixa de diálogo de conteúdo dinâmico. Os valores vêm do objeto WebhookPushResponse no ficheiro OpenAPI.

10. Na parte superior da página, dê um nome ao fluxo e escolha Criar fluxo.

    

Verificação e resolução de problemas

Para verificar se está tudo configurado corretamente, selecione os meus fluxos e depois selecione o ícone de informação ao lado do novo fluxo para ver o histórico de execuções:

• Já deverá ver pelo menos uma execução Com êxito a partir da criação do webhook. Esta execução indica que o webhook foi criado com sucesso do lado do GitHub.
• Se a corrida falhou, reveja os detalhes da corrida para perceber porquê. Se a falha foi devido a uma 404 Not Found resposta, provavelmente a tua conta no GitHub não tem as permissões corretas para criar um webhook no repositório que usaste.

Resumo

Se configurou tudo corretamente, recebe notificações push na aplicação móvel Power Automate sempre que ocorre um push git no repositório GitHub que selecionou. Ao utilizar o processo anterior, pode usar qualquer serviço com capacidade de webhook como um gatilho nos seus fluxos.

Passos seguintes

• Criar um conector personalizado para uma API da Web
• Autentique sua API e conector com Microsoft Entra ID

Enviar comentários

Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para fornecer comentários, vá para Enviar problemas ou obter ajuda com conectores e selecione seu tipo de feedback.