Executar fluxos de trabalho ou ações com base em eventos de ponto de extremidade de serviço usando webhooks HTTP no Aplicativos Lógicos do Azure

Aplica-se a: Aplicativos Lógicos do Azure (Consumo + Standard)

Quando você quiser que um gatilho ou ação de fluxo de trabalho aguarde a chegada de eventos ou dados a um ponto de extremidade de serviço de destino antes de serem executados, use o gatilho ou ação do Webhook HTTP , em vez de verificar proativamente o ponto de extremidade em um agendamento. O gatilho ou a ação do Webhook HTTP se inscreve no endpoint do serviço e aguarda novos eventos ou dados antes de ser executado. Você pode usar o padrão de webhook para tarefas de execução longa e processamento assíncrono.

A lista a seguir descreve exemplos de fluxos de trabalho baseados em webhook:

• Um gatilho HTTP Webhook aguarda que um evento chegue de Hubs de Eventos do Azure antes de executar o fluxo de trabalho.
• Uma ação HTTP Webhook aguarda uma aprovação no Office 365 Outlook antes de continuar a próxima ação no fluxo de trabalho.

Este guia mostra como configurar o gatilho de Webhook HTTP e a ação de Webhook HTTP para que seu fluxo de trabalho possa receber e responder a novos eventos ou dados em um ponto de extremidade de serviço.

Como os webhooks funcionam?

Um gatilho ou ação de webhook não sonda ou faz uma checagem proativa de novos eventos ou dados no endpoint do serviço de destino. Em vez disso, o gatilho ou a ação aguarda até que novos eventos ou dados cheguem ao ponto de extremidade de serviço antes de serem executados. Depois de adicionar um gatilho ou ação de webhook ao fluxo de trabalho e em seguida salvá-lo, ou depois de habilitar novamente um recurso de aplicativo lógico desabilitado, o gatilho ou ação do webhook inscreve-se no endpoint de serviço gerando e registrando uma URL de retorno de chamada com o endpoint. O gatilho ou a ação aguarda o endpoint do serviço chamar a URL, que executa o gatilho ou a ação. Assim como o gatilho Request, um gatilho Webhook HTTP é acionado imediatamente.

Por exemplo, a ação do conector Office 365 Outlook chamada Send approval email segue o padrão de webhook, mas funciona apenas com Office 365 Outlook. É possível estender o padrão webhook para qualquer serviço utilizando o gatilho ou ação Webhook HTTP com o ponto de extremidade do serviço desejado.

Um gatilho de webhook permanece registrado em um endpoint de serviço até que você execute manualmente uma das seguintes ações:

• Altere os valores de parâmetro do gatilho.
• Exclua o gatilho e salve o fluxo de trabalho.
• Desabilite o recurso de aplicativo lógico.

Uma ação de webhook permanece subscrita a um ponto de extremidade de serviço, a menos que uma das seguintes condições aconteça:

• A ação de webhook é concluída sucesso.
• Você cancela a execução do fluxo de trabalho enquanto aguarda uma resposta.
• O fluxo de trabalho atinge o tempo limite.
• Você altera os valores dos parâmetros de ação do webhook que um gatilho de webhook usa como entradas.

Para obter mais informações, consulte:

• Webhooks e assinaturas
• Criar APIs personalizadas que suportam um webhook
• Acesso para chamadas de saída para outros serviços e sistemas

Pré-requisitos

• Uma conta Azure e uma assinatura. Get uma conta de Azure gratuita.

• A URL de um ponto de extremidade do serviço ou da API implantado.

  Este item deve dar suporte ao padrão "inscrição e cancelamento de inscrição" para gatilhos de webhook em fluxos de trabalho ou ações de webhook em fluxos de trabalho.

• O fluxo de trabalho do aplicativo lógico Standard ou Consumption, onde você deseja usar o disparador ou ação do Webhook HTTP.

  • Para usar o gatilho Webhook HTTP, crie um recurso de aplicativo lógico com um fluxo de trabalho em branco.
  • Para usar a ação de Webhook HTTP , inicie seu fluxo de trabalho com qualquer gatilho que funcione melhor para seu cenário. Os exemplos usam o gatilho Webhook HTTP.

Incluir um gatilho de webhook HTTP

Esse gatilho integrado chama o ponto de extremidade de assinatura no serviço de destino e registra uma URL de retorno de chamada nesse serviço. Em seguida, o fluxo de trabalho aguardará até que o serviço de destino envie uma solicitação HTTP POST à URL de retorno de chamada. Quando esse evento ocorre, o gatilho é acionado e passa todos os dados da solicitação para o fluxo de trabalho.

1. No portal Azure, abra o recurso de aplicativo lógico. No designer, abra o fluxo de trabalho em branco.

2. Siga as etapas gerais para adicionar o gatilho chamado Webhook HTTP ao fluxo de trabalho.

   Este exemplo renomeia o gatilho Run HTTP Webhook trigger como um nome mais descritivo. O exemplo também adiciona mais tarde uma ação de Webhook HTTP . Ambos os nomes devem ser exclusivos.

3. Para os parâmetros de gatilho do Webhook HTTP, forneça os valores para as chamadas de assinatura e cancelamento de assinatura:

   Parâmetro	Obrigatório	Descrição
   Método de assinatura	Sim	O método a ser usado para assinar o ponto de extremidade de destino.
   URI de assinatura	Sim	A URL a ser usada para a assinatura do endpoint de destino.
   Corpo da assinatura	Não	Qualquer corpo da mensagem a ser incluído na solicitação de assinatura. Este exemplo inclui a URL de retorno de chamada que identifica exclusivamente o assinante, que é o fluxo de trabalho, usando a listCallbackUrl() função de expressão para recuperar a URL de retorno de chamada do gatilho.
   Conteúdo para cancelar assinatura	Não	Qualquer corpo de mensagem a ser incluído na solicitação de cancelamento de assinatura. Você pode usar a listCallbackUrl() função de expressões para obter a URL de callback da sua ação. No entanto, o gatilho também inclui e envia automaticamente os cabeçalhos x-ms-client-tracking-id e x-ms-workflow-operation-name, que o serviço de destino pode usar para identificar exclusivamente o assinante.

4. Para adicionar outros parâmetros de gatilho, abra a lista de parâmetros Avançados .

   Por exemplo, para usar os parâmetros Desinscrever Método e Cancelar assinatura de URI , adicione-os na lista de parâmetros Avançados .

   O exemplo a seguir mostra um gatilho que inclui os métodos, URIs e corpos de mensagem a serem usados para os métodos de assinatura e cancelamento de assinatura:

   

5. Se você precisar usar autenticação, adicione os parâmetros Assinar autenticação e Cancelar autenticação da lista de Parâmetros Avançados.

   Para obter mais informações sobre os tipos de autenticação disponíveis para o Webhook HTTP, consulte Adicionar autenticação a chamadas de saída.

6. Adicione outras ações de que seu cenário precise.

7. Quando terminar, salve o fluxo de trabalho. Selecione Salvar na barra de ferramentas do designer.

Salvar o fluxo de trabalho chama o ponto de extremidade de assinatura no serviço de destino e registra a URL de retorno de chamada. Seu fluxo de trabalho aguarda o serviço de destino enviar uma solicitação HTTP POST para a URL de callback. Quando esse evento acontece, o gatilho é acionado e passa todos os dados na solicitação para o fluxo de trabalho. Se essa operação for concluída com êxito, o gatilho cancelará a assinatura do ponto de extremidade e seu fluxo de trabalho continuará para a próxima ação.

Incluir uma ação de webhook HTTP

Esta ação integrada chama o ponto de extremidade de assinatura no serviço de destino e registra uma URL de retorno de chamada nele. Em seguida, o fluxo de trabalho pausa e aguarda o serviço de destino enviar uma solicitação HTTP POST para a URL de retorno de chamada. Quando esse evento acontece, a ação passa todos os dados na solicitação para o fluxo de trabalho. Se a operação for concluída com êxito, a ação cancelará a inscrição do endpoint, e seu fluxo de trabalho continuará para a próxima ação.

1. No portal Azure, abra o recurso de aplicativo lógico. Na ferramenta designer, abra o fluxo de trabalho.

2. Siga as etapas gerais para adicionar a ação chamada Webhook HTTP ao fluxo de trabalho.

   Este exemplo renomeia a ação Run HTTP Webhook action como um nome mais descritivo. Se o seu fluxo de trabalho também usar o gatilho Webhook HTTP, os dois nomes devem ser únicos.

3. Para os parâmetros de ação do Webhook HTTP, forneça os valores a serem usados para as chamadas de assinatura e cancelamento de assinatura:

   Parâmetro	Obrigatório	Descrição
   Método de assinatura	Sim	O método a ser usado para se inscrever no endpoint de destino.
   URI de assinatura	Sim	A URL a ser usada para subscrever o endpoint de destino.
   Corpo da assinatura	Não	Qualquer corpo da mensagem a ser incluído na solicitação de assinatura. Este exemplo inclui a URL de retorno de chamada que identifica exclusivamente o assinante, que é seu fluxo de trabalho, usando a listCallbackUrl() função de expressão para recuperar a URL de retorno de chamada da ação.
   Conteúdo para cancelar assinatura	Não	Qualquer corpo de mensagem a ser incluído na solicitação de cancelamento de assinatura. Você pode usar a listCallbackUrl() função de expressão para recuperar a URL de retorno de chamada da ação. No entanto, a ação também inclui e envia automaticamente os cabeçalhos x-ms-client-tracking-id e x-ms-workflow-operation-name, que o serviço de destino pode usar para identificar exclusivamente o assinante.

4. Para adicionar outros parâmetros de ação, abra a lista de parâmetros Avançados .

   Por exemplo, para usar os parâmetros Desinscrever Método e Cancelar assinatura de URI , adicione-os na lista de parâmetros Avançados .

   O exemplo a seguir mostra uma ação que inclui os métodos, URIs e corpos de mensagem a serem usados para os métodos de assinatura e cancelamento de assinatura:

   

5. Se você precisar usar autenticação, adicione os parâmetros Autenticação de Inscrição e Autenticação de Desinscrição da lista de Parâmetros Avançados.

   Para obter mais informações sobre os tipos de autenticação disponíveis para o Webhook HTTP, consulte Adicionar autenticação a chamadas de saída.

6. Adicione outras ações de que seu cenário precise.

7. Quando terminar, salve o fluxo de trabalho. Selecione Salvar na barra de ferramentas do designer.

Após a execução dessa ação, o fluxo de trabalho chama o ponto de extremidade de assinatura no serviço de destino e registra a URL de retorno de chamada. Seu fluxo de trabalho pausa e aguarda o serviço de destino enviar uma solicitação HTTP POST para a URL de retorno de chamada. Quando esse evento acontece, a ação passa todos os dados na solicitação para o fluxo de trabalho. Se a operação for concluída com êxito, a ação cancelará a assinatura do endpoint e seu fluxo de trabalho passará para a próxima ação.

Referência técnica do conector

Para obter mais informações sobre os parâmetros de gatilho e ação de webhook HTTP, consulte os parâmetros de webhook HTTP. O gatilho e a ação têm os mesmos parâmetros.

Expiração do token SAS (Assinatura de Acesso Compartilhado)

A URL de callback para o gatilho ou a ação Webhook HTTP é gerada automaticamente pelo método List Callback Url - REST API. Por padrão, o token SAS na URL de retorno de chamada não tem uma expiração baseada em tempo. A URL de callback permanece válida durante a execução do fluxo de trabalho.

Limites de tempo de espera

A tabela a seguir descreve os limites de tempo para a ação de Webhook HTTP, com base na opção de hospedagem da aplicação lógica.

A URL de retorno de chamada da ação de Webhook HTTP torna-se inválida quando os seguintes eventos ocorrem:

• Você cancela o fluxo de trabalho.
• Exclua ou desabilite o fluxo de trabalho ou o recurso de aplicativo lógico.
• Você gira as chaves de acesso do fluxo de trabalho.
• O fluxo de trabalho expira.

Para obter outros limites HTTP, consulte Limites deHTTP em Aplicativos Lógicos do Azure.

Alterar o limite de tempo de espera

Para alterar esse limite para a ação HTTP Webhook em fluxos de trabalho com estado usando o portal Azure, consulte a tabela de duração Timeout para solicitações HTTP de saída. Ou, na definição JSON da ação, adicione o limit.timeout objeto e defina o valor para a duração desejada, por exemplo:

{
   "actions": {
      "Run_HTTP_Webhook_action": {
         "type": "HttpWebhook",
         "inputs": {
            "subscribe": {
               "method": "POST",
               "uri": "https://<external-service>.com/subscribe",
               "body": {
                  "callbackUrl": "@{listCallBackUrl()}"
               }
            },
            "unsubscribe": {}
         },
         "limit": {
            "timeout": "PT1H"
         }
      }
   }
}

Saídas de gatilho e ação

As tabelas a seguir fornecem mais informações sobre as saídas retornadas por um gatilho ou ação do Webhook HTTP :

Gerar URL de retorno de chamada com chave de acesso secundária

Um fluxo de trabalho de aplicativo lógico tem duas chaves de acesso: primária e secundária. Por padrão, Aplicativos Lógicos do Azure usa a chave primária para gerar a URL de retorno de chamada para o gatilho de webhook HTTP.

Para usar a chave secundária na geração da URL de retorno de chamada, siga estas etapas:

1. Se você estiver no designer de fluxo de trabalho, alterne para o modo de exibição de código.

2. Na definição do HttpWebhook gatilho, localize o accessKeyType parâmetro.

3. Insira a palavra Secondary como o valor do parâmetro.

4. Salve suas alterações.

O exemplo a seguir mostra a definição do gatilho de webhook com o accessKeyType parâmetro definido como Secondary:

{
  "type": "HttpWebhook",
  "inputs": {
    "subscribe": {
      "method": "POST",
      "uri": "<subscription-URL>",
      "body": "@listCallbackUrl()"
    },
    "accessKeyType": "Secondary"
  },
  "runAfter": {}
}

Conteúdo relacionado

• Acesso para chamadas de entrada para gatilhos baseados em solicitação
• Lista de todos os conectores de Aplicativos Lógicos
• Conectores integrados no Aplicativos Lógicos do Azure