Utilizar um weebhook como acionador no Azure Logic Apps e no Power Automate

Webhooks são chamadas de retorno HTTP simples utilizadas para fornecer notificações de eventos. O Azure Logic Apps e o Power Automate permitem-lhe utilizar webhooks como acionadores. Uma aplicação lógica ou fluxo reconhece este acionador e efetua uma ação sempre que ele é acionado. Este tutorial demonstra como utilizar um webhook como acionador.

Pré-requisitos

• Uma das seguintes subscrições:
  • Azure, se estiver a utilizar o Logic Apps
  • Power Automate
• Experiência básica na construção de aplicações lógicas ou fluxos e conectores personalizados.
• Se estiver a utilizar o Logic Apps, comece por criar um conector personalizado do Azure Logic Apps.
• Um compreensão básica de webhooks.
• Noções básicas sobre a Especificação de OpenAPI (anteriormente conhecida como Swagger).
• Uma conta GitHub.
• A definição de OpenAPI de amostra para este tutorial.

A definição de OpenAPI

Os webhooks são implementados em Logic Apps e no Power Automate como parte de um conetor personalizado, pelo que tem de indicar uma definição de OpenAPI que define a forma do webhook. Se pretende criar um acionador, mas não tem uma definição de OpenAPI, pode utilizar acionadores de IU no assistente de conector personalizado para definir acionadores de webhook.

A definição de OpenAPI contém três partes essenciais para fazer com que o webhook funcione:

• Criar o webhook
• Definir o pedido de hook recebido a partir da API (neste caso, o GitHub)
• Eliminar o webhook

Criar o webhook

O webhook é criado no lado do GitHub por um HTTP POST para /repos/{owner}/{repo}/hooks. Quando é criada uma nova aplicação lógica ou fluxo, publica para este URL utilizando o acionador definido na definição de OpenAPI. Também é postado no URL, se o acionador for modificado. No exemplo seguinte, a propriedade post contém o esquema do pedido que é publicado no 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"
        }
        }
    }
    }
},

Definir o pedido de hook recebido a partir da API

A forma do pedido de hook de entrada (a notificação do GitHub para o Logic Apps ou o Power Automate) é definida na propriedade x-ms-notification-content personalizada, conforme mostrado na amostra anterior. Não é necessário ter todo o conteúdo do pedido, apenas as partes que pretende utilizar no aplicação lógica ou fluxo.

Eliminar o webhook

A definição de OpenAPI tem de incluir uma definição de como eliminar o webhook. Se atualizar o acionador e se eliminar a aplicação lógica ou o fluxo, o Logic Apps e o Power Automate tentam eliminar o webhook.

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

Não está incluído nenhum cabeçalho com instruções para a chamada de eliminar o webhook. A mesma ligação utilizada no conector também é utilizada para a chamada de excluir webhook.

Ative a autenticação no GitHub

Geralmente, a API que envia o pedido do webhook para o Logic Apps ou o Power Automate utiliza algum tipo de autenticação e o GitHub não é exceção. O GitHub suporta vários tipos de autenticação; usamos os tokens de acesso pessoal do GitHub para este tutorial.

1. Navegue para GitHub e inicie sessão, caso ainda não o tenha feito.

2. No canto superior direito, selecione a imagem do perfil e, em seguida, no menu, selecione Definições.

   

3. No menu à esquerda, selecione Definições de programador, depois selecione Tokens de acesso pessoal.

4. Escolha o botão gerar novo token e confirme a palavra-passe, se lhe for solicitado.

   

5. Na caixa Descrição do token, introduza uma descrição.

6. Selecione a caixa de verificação admin:repo_hook.

   

7. Selecione o botão Gerar token.

8. Tome nota do novo token.

   

   Importante

   Não poderá aceder a este token novamente. Deve copiá-lo e colá-lo num lugar para utilizar mais tarde no tutorial.

Importar a definição de OpenAPI

Comece por importar a definição de OpenAPI para Logic Apps ou para Power Automate.

Importar a definição de OpenAPI para Logic Apps

1. Aceda ao portal do Azure e abra o conector do Logic Apps que criou anteriormente em Criar um conector personalizado do Azure Logic Apps.

2. No menu do conector, escolha Conector do Logic Apps e depois escolha Editar.

   

3. Em Geral, escolha Carregar um ficheiro OpenAPI e navegue para o ficheiro OpenAPI que transferiu.

   

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

1. Ir para flow.microsoft.com.

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

   

3. Escolha Criar conector personalizado e, em seguida, selecione Importar uma coleção do Postman.

   

4. Introduza um nome para o conector personalizado e, em seguida, navegue para o ficheiro OpenAPI que transferiu e escolha Ligar.

   

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

Concluir a criação do conector personalizado

1. Na página Geral, escolha Continuar.

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

3. Na secção Autenticação básica, nos campos de etiqueta, introduza o texto Nome de utilizador e Palavra-passe. Estas são apenas etiquetas que serão apresentadas quando o acionador for utilizado numa aplicação lógica ou num fluxo.

   

4. Na parte superior do assistente, certifique-se de que o nome está definido como "GitHubDemo" e, em seguida, selecione Criar conector.

Agora está pronto para utilizar o acionador numa aplicação lógica ou fluxo, ou pode pesquisar como criar acionadores a partir da UI.

Criar acionadores de webhook a partir da UI

Nesta secção, mostramos-lhe como criar um acionador na IU sem ter quaisquer definições de acionador na sua definição de 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 que especifica uma descrição e um URL.

   Parâmetro	Value
   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 como fez na secção anterior.

3. Na página definição, escolha + novo acionador e preencha a descrição do acionador. Neste exemplo, vai criar um acionador que é acionado quando é efetuado um pedido de solicitação a um repositório.

   

   Parâmetro	Value
   Resumo	"É acionado quando um pedido de receção é efetuado para um repositório selecionado"
   Descrição	"É acionado quando um pedido de receção é efetuado para um repositório selecionado"
   ID da operação	"webhook-PR-trigger"
   Visibilidade	"nenhum" (para mais informações, ver abaixo)
   Tipo de acionador	"Webhook"

   A propriedade Visibilidade para operações e parâmetros num fluxo ou aplicação lógica tem as seguintes opções:

   • nenhum: apresentado normalmente na aplicação lógica ou no fluxo
   • avançada: ocultada num menu adicional
   • interna: ocultada do utilizador
   • importante: sempre mostrada primeiro ao utilizador

4. A área de Pedido apresenta informações com base no pedido HTTP para a ação. Selecione Importar a partir de exemplo.

   

5. Defina o pedido para o acionador de webhook e escolha Importar. Fornecemos um exemplo que deve ser importado (abaixo da imagem). Para obter mais informações, consulte a referência da API GitHub. O Logic Apps e o Power Automate adicionam automaticamente cabeçalhos content-type e de segurança standard, pelo que não tem de os definir quando importar do exemplo.

   

   Parâmetro	Value
   Verbo	"PUBLICAR"
   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 de Resposta apresenta informações com base na resposta HTTP para a ação. Escolha Adicionar resposta predefinida.

   

7. Defina a resposta para o acionador de webhook e escolha Importar. Fornecemos um exemplo que deve ser importado. Para obter mais informações, consulte a referência da API GitHub.

   

   {
     "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 deverá receber o valor URL da chamada de retorno do GitHub. Esta é a propriedade url no objeto de config.

   

9. Na parte superior do assistente, introduza um nome e, em seguida, escolha criar conector.

Utilizar o webhook como acionador

Agora que já tem tudo configurado, pode utilizar o webhook numa aplicação lógica ou num fluxo. Em seguida, crie um fluxo que envie uma notificação push para a aplicação móvel do Power Automate sempre que o repositório do GitHub receber um git push.

1. No flow.microsoft.com, na parte superior da página, selecione Os meus fluxos.

2. Escolha Criar a partir do início e, na página seguinte, escolha Procurar centenas de conectores e acionador.

   

3. No designer do Power Automate, procure o conector personalizado registado anteriormente.

   

   Selecione o item na lista para o utilizar como acionador.

4. Como é a primeira vez que utiliza este conector personalizado, tem de ligar ao mesmo. Introduza as informações de ligação e, em seguida, escolha Criar.

   

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

5. 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
   repo	O repositório a monitorizar

   Importante

   Deve utilizar um repositório para o qual a sua conta tenha direitos. A forma mais fácil de fazê-lo será se utilizar o seu próprio repositório.

6. Selecione + Novo passo e, em seguida, selecione Adicionar uma ação.

7. Procure e selecione a ação Notificação push.

   

8. Introduza algum texto no campo de texto e nos outros campos, utilizando valores da caixa de diálogo de conteúdo dinâmico. Note que estes valores são provenientes do objeto WebhookPushResponse no ficheiro OpenAPI.

   

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

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

   

Verificação e resolução de problemas

Para verificar se está tudo configurado corretamente, selecione Os meus fluxos e, em seguida, selecione o ícone de informações junto ao novo fluxo para ver o histórico de execuções:

• Já deverá ver, pelo menos, uma execução "Com êxito" desde a criação do webhook. Isto indica que o webhook foi criado com êxito no lado do GitHub.

• Se a execução falhar, pode explorar os detalhes de execução para ver o motivo da falha. Se a falha se deveu a uma resposta "404 Não Encontrado", é provável que a sua conta do GitHub não tenha as permissões corretas para criar um webhook no repositório que utilizou.

Resumo

Se estiver tudo configurado corretamente, irá agora receber notificações push na aplicação para dispositivos móveis do Power Automate sempre que ocorrer um git push no repositório do GitHub que selecionou. Através do processo acima, pode utilizar qualquer serviço com capacidade de webhook como acionador nos seus fluxos.

Passos seguintes

• Criar um conector personalizado para uma API web
• Autenticar a API e o conector com o Microsoft Entra ID

Enviar comentários

Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para enviar comentários, aceda a Submeter problemas ou obter ajuda com conectores e selecione o tipo de comentários.