Use um webhook como gatilho para os Aplicativos Lógicos do Azure e o Power Automate

Webhooks são retornos de chamada HTTP simples que fornecem notificações de evento quando algo acontece em um serviço Web. Em Aplicativos Lógicos do Azure e Power Automate você pode usar webhooks como gatilhos. Um aplicativo lógico ou fluxo aguarda esse gatilho e executa uma ação sempre que o gatilho é acionado. Este tutorial demonstra como usar um webhook como um gatilho por meio de um conector personalizado definido com uma especificação OpenAPI.

Pré-requisitos

• Uma das seguintes assinaturas:
  • Azure, se você estiver usando Logic Apps
  • Power Automate
• Experiência básica na criação de aplicativos lógicos ou fluxos de nuvem e criação de conectores personalizados a partir de definições do OpenAPI.
• Caso esteja usando Aplicativos Lógicos, primeiro crie um conector personalizado dos Aplicativos Lógicos do Azure.
• Compreensão básica de webhooks.
• Compreensão básica da Especificação OpenAPI (anteriormente conhecido como Swagger).
• Uma conta do GitHub.
• A definição OpenAPI de exemplo para este tutorial. Se você ainda não o tiver, baixe-o para usá-lo nas etapas a seguir. Caso contrário, você precisará criar uma definição de OpenAPI personalizada para o webhook.

Habilitar autenticação no GitHub

Uma API de serviço Web que envia uma solicitação de webhook para Aplicativos Lógicos ou Power Automate normalmente usa alguma forma de autenticação e GitHub não é exceção. GitHub dá suporte a vários tipos de autenticação. Este tutorial usa tokens de acesso pessoal granulares do GitHub.

1. Vá para GitHub e entre se você ainda não fez isso.

2. No canto superior direito, selecione sua imagem de perfil e, no menu, selecione Configurações.

3. No menu à esquerda, selecione Configurações do Desenvolvedor.

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

5. Selecione o botão Gerar novo token e confirme sua senha, se solicitado.

6. Insira um nome de token e uma descrição para o token.

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

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

9. Em Permissões, selecione Adicionar permissões>Webhooks>Leitura e gravação.

10. Selecione o botão Gerar token .

11. Anote o novo token. Você precisará usar esse token posteriormente ao adicionar seu conector de webhook como gatilho.

    Importante

    Você não pode acessar esse token novamente. Copie e cole-o em algum lugar para usar posteriormente no tutorial.

Definir o webhook na definição de OpenAPI

Você implementa webhooks no Logic Apps e no Power Automate como parte de um conector personalizado. Para criar o conector, você precisa fornecer uma definição de OpenAPI que defina a forma do webhook. Este tutorial usa uma definição de exemplo da OpenAPI baixada para os webhooks do GitHub.

Se você quiser criar um gatilho, mas não tiver uma definição de OpenAPI para usar como base, use a IU de gatilhos no assistente de conectores personalizados para definir gatilhos de webhook.

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

• Criando o webhook
• Definindo a solicitação de webhook de entrada vinda da API do serviço web (neste exemplo do tutorial, GitHub)
• Excluir o webhook

O conector usa essa definição de OpenAPI para entender como criar, receber e excluir webhooks para o repositório GitHub.

Criar o webhook

O conector usa a API do serviço Web (em nosso exemplo, a API REST GitHub) para criar o webhook no lado do serviço Web enviando uma solicitação HTTP POST para o ponto de extremidade de criação de webhook apropriado para o serviço Web (/repos/{owner}/{repo}/hooksno caso de GitHub).

Quando você cria um novo aplicativo de lógica ou fluxo usando o conector, o conector envia uma solicitação POST para o endpoint de criação do webhook do serviço web, conforme definido na definição OpenAPI do conector. Ele também enviará uma solicitação POST para essa URL se você modificar o aplicativo lógico ou o gatilho de fluxo. Na configuração de caminho do OpenAPI de exemplo a seguir, a propriedade post contém o esquema da solicitação de criação de webhook a ser enviada à 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"
                }
            }
        }
    }
},

Definir a solicitação de entrada do webhook a partir da API

Defina o formato da solicitação do gancho de entrada (a notificação do GitHub para o Logic Apps ou o Power Automate) na propriedade personalizada x-ms-notification-content, conforme mostrado no exemplo anterior. A solicitação não precisa conter todo o conteúdo da solicitação, apenas as partes que você deseja usar em seu aplicativo lógico ou fluxo.

Excluir o webhook

Inclua uma definição de como excluir o webhook na definição de OpenAPI. O Logic Apps e o Power Automate tentam excluir o webhook existente se você atualizar o gatilho ou excluir o aplicativo lógico 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"
            }
        ]
    }
},

Nenhum cabeçalho é incluído para a chamada de webhook de exclusão. A chamada de exclusão do webhook usa a mesma conexão que o conector.

Importar a definição OpenAPI

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

Importar a definição OpenAPI para Aplicativos Lógicos

1. Acesse o portal do Azure e abra o conector dos Aplicativos Lógicos que você criou anteriormente em Criar um conector personalizado dos Aplicativos Lógicos do Azure.

2. No menu do conector, selecione Conector de Aplicativos Lógicos e, depois, Editar.

   

3. Em Geral, selecione Carregar um arquivo OpenAPI e vá para o arquivo OpenAPI de exemplo que você baixou.

   

Importar a definição OpenAPI para o Power Automate

1. Ir para https://make.powerautomate.com/.

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

   

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

   

4. Insira um nome para o conector personalizado, vá para o arquivo OpenAPI de exemplo que você baixou 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, selecione Autenticação básica.

3. Na seção Autenticação básica, nos campos de rótulo, insira o texto Nome de usuário e Senha. Esses rótulos aparecem quando você usa o gatilho em um aplicativo lógico ou fluxo.

   

4. Na parte superior do assistente, verifique se o nome está definido como "GitHubDemo" e escolha Criar conector.

Agora você está pronto para usar o gatilho em um aplicativo lógico ou fluxo ou pode continuar a ler sobre como criar gatilhos usando a interface do usuário.

Criar gatilhos de webhook pela interface

Nesta seção, você aprenderá a criar um gatilho na interface do usuário sem ter definições de gatilho em sua definição de OpenAPI. Comece com uma definição OpenAPI de linha de base ou comece do zero no assistente de conector personalizado.

1. Na página Geral , especifique uma descrição e UMA URL.

   Parâmetro	Valor
   Descrição	"GitHub é um repositório de código-fonte social."
   URL	"api.github.com"

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

3. Na página Definição , escolha Novo gatilho e preencha a descrição do gatilho. Neste exemplo, você está criando um gatilho que é acionado quando uma solicitação por pull é feita em um repositório.

   

   Parâmetro	Valor
   Resumo	"Dispara quando uma solicitação pull é feita para um repositório selecionado"
   Descrição	"Dispara quando uma solicitação pull é feita para um repositório selecionado"
   ID da Operação	"webhook-PR-trigger"
   Visibilidade	"nenhum" (veja abaixo para obter mais informações)
   Tipo de acionador	"Webhook"

   A propriedade Visibilidade para operações e parâmetros em um aplicativo lógico ou fluxo possui as seguintes opções:

   • sem: exibido normalmente no aplicativo lógico ou no fluxo
   • avançado: oculto em um menu adicional
   • interno: ocultado do usuário
   • importante: sempre exibido para o usuário 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 a solicitação para o gatilho de webhook e selecione Importar. Fornecemos um exemplo para você importar (na seção a seguir). Para obter mais informações, consulte a referência da API do GitHub. Os Aplicativos Lógicos e o Power Automate adicionam automaticamente cabeçalhos padrão content-type e de segurança, portanto, você não precisa defini-los durante a importação de um exemplo.

   

   Parâmetro	Valor
   Verbo	"POST"
   URL	"https://api.github.com/repos/{owner}/{repo}/hooks"
   Corpo	Consulte 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 de webhook e selecione Importar. Mais uma vez, fornecemos uma amostra para você importar. Para obter mais informações, consulte a referência da API do 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 gatilho, selecione o parâmetro que deve receber o valor da URL de retorno de chamada do GitHub. Esse parâmetro é a url propriedade no config objeto.

   

9. Na parte superior do assistente, insira um nome e, em seguida, escolha Criar conector.

Usar o webhook como um gatilho

Depois de configurar tudo, use o webhook por meio do conector personalizado em um aplicativo lógico ou fluxo. Em seguida, crie um fluxo que envie um email sempre que seu repositório GitHub receber um push do git.

1. Na https://make.powerautomate.com/parte superior da página, selecione Meus fluxos.

2. Selecione Criar do zero.

   

3. No designer do Power Automate, pesquise o conector personalizado que você registrou anteriormente.

   

4. Selecione o item na lista para usá-lo como um gatilho.

5. Como esta é a primeira vez que você usou esse conector personalizado, conecte-se a ele. Insira informações de conexão e selecione Criar.

   

   Parâmetro	Valor
   Nome da conexão	Um nome descritivo
   Nome do Usuário	Seu nome de usuário do GitHub
   Senha	O token de acesso pessoal que você criou anteriormente

6. Insira os detalhes sobre o repositório que deseja monitorar. Você pode reconhecer os campos do objeto WebhookRequestBody no arquivo OpenAPI.

   

   Parâmetro	Valor
   proprietário	O proprietário do repositório a ser monitorado
   repositório	O repositório a ser monitorado

   Importante

   Use um repositório ao qual sua conta tem direitos. A maneira mais fácil de fazer isso é usar seu próprio repositório.

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

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

9. Insira 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 arquivo OpenAPI.

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

    

Verificação e solução de problemas

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

• Você já deve conseguir ver pelo menos uma execução bem-sucedida gerada pela criação do webhook. Essa execução indica que o webhook foi criado com êxito no lado GitHub.
• Se a execução falhar, examine os detalhes da execução para ver por que ela falhou. Se a falha foi devido a uma 404 Not Found resposta, sua conta GitHub provavelmente não tem as permissões corretas para criar um webhook no repositório usado.

Resumo

Se você configurou tudo corretamente, receberá notificações por push no aplicativo móvel Power Automate sempre que ocorrer um push git no repositório GitHub selecionado. Ao usar o processo anterior, você pode usar qualquer serviço com suporte a webhook como gatilho em seus fluxos.

Próximas etapas

• Criar um conector personalizado para uma API Web
• Autentique sua API e o conector usando o Microsoft Entra ID

Faça comentários

Agradecemos muito os comentários sobre problemas com nossa plataforma de conectores ou novas ideias de recursos. Para fornecer comentários, acesseEnviar problemas ou obter ajuda com conectores e selecione o tipo de comentário.