Partilhar via

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

  • Artigo

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.

Nota

Utilizaremos o GitHub como exemplo de um serviço que pode enviar notificações através de webhooks, embora as técnicas aqui demonstradas possam ser expandidas para qualquer serviço que utilize webhooks.

Pré-requisitos

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

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, por isso deve certificar-se de que a inclui.

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.

Importante

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

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.

    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.

    Gerar novo token

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

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

    admin:repo_hook

  7. Selecione o botão Gerar token.

  8. Tome nota do novo token.

    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.

    Editar Conector do Logic Apps

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

    Captura de ecrã que mostra a opção Carregar um ficheiro OpenAPI.

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.

    Conectores personalizados

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

    Criar conector personalizado

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

    Captura de ecrã que mostra o campo para introduzir um nome.

    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.

    Autenticação básica

  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.

    Criar Acionador-1

    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.

    Página de definição - importar da amostra

  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.

    Criar Acionador-2

    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.

    Página de definição - resposta

  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.

    Criar Acionador-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. 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.

    Criar Acionador-4

  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.

    Procurar conectores

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

    Novo acionador

    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.

    Nova ligação

    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.

    Informações de repositório

    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.

    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.

    Detalhes das notificações push

    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.

    Nome do 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

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.