Compartilhar via

Atividade do webhook no Azure Data Factory

  • Artigo

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange desde movimentação de dados até ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma avaliação gratuita!

Uma atividade do webhook pode controlar a execução de pipelines por meio do código personalizado. Com a atividade do webhook, o código pode chamar um ponto de extremidade e passá-lo para uma URL de retorno de chamada. A execução de pipeline aguarda o retorno de chamada antes de prosseguir para a próxima atividade.

Importante

A atividade do WebHook agora permite que você visualize o status de erro e mensagens personalizadas de volta à atividade e ao pipeline. Defina reportStatusOnCallBack como true e inclua StatusCode e Error na carga de retorno de chamada. Para saber mais, confira a seção Observações adicionais.

Criar uma atividade de Webhook com a interface do usuário

Para usar uma atividade Webhook em um pipeline, conclua as seguintes etapas:

  1. Procure Webhook no painel Atividades do pipeline e arraste uma atividade Webhook para a tela do pipeline.

  2. Selecione a nova atividade de webhook na tela, se ela ainda não estiver selecionada, e a guia Configurações para editar seus detalhes.

    Mostra a interface do usuário para uma atividade do webhook.

  3. Especifique um URL para o Webhook, que pode ser uma cadeia de caracteres URL literal ou qualquer outra combinação de expressões dinâmicas, variáveis do sistema ou saídas de outras atividades. Forneça outros detalhes a serem enviados com a solicitação.

  4. Use a saída da atividade como a entrada para qualquer outra atividade e faça referência à saída em qualquer lugar que o conteúdo dinâmico tem suporte na atividade de destino.

Sintaxe


{
    "name": "MyWebHookActivity",
    "type": "WebHook",
    "typeProperties": {
        "method": "POST",
        "url": "<URLEndpoint>",
        "headers": {
            "Content-Type": "application/json"
        },
        "body": {
            "key": "value"
        },
        "timeout": "00:10:00",
        "reportStatusOnCallBack": false,
        "authentication": {
            "type": "ClientCertificate",
            "pfx": "****",
            "password": "****"
        }
    }
}

Propriedades de tipo

Propriedade Descrição Valores permitidos Obrigatório
name O nome da atividade do webhook. String Sim
tipo Deve ser definido como "WebHook". String Sim
method O método da API REST para o ponto de extremidade de destino. Cadeia de caracteres. O tipo com suporte é "POST". Sim
url O ponto de extremidade e o caminho de destino. Uma string ou uma expressão com o valor resultType de uma string. Sim
headers Cabeçalhos que são enviados para a solicitação. Aqui está um exemplo que define o idioma e o tipo em uma solicitação: "headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }. Uma string ou uma expressão com o valor resultType de uma string. Sim. Um cabeçalho Content-Type como "headers":{ "Content-Type":"application/json"} é necessário.
body Representa o conteúdo enviado para o ponto de extremidade. JSON válido ou uma expressão com o valor resultType de JSON. Confira Esquema de carga de solicitação para o esquema da carga de solicitação. Sim
autenticação O método de autenticação usado para chamar o ponto de extremidade. Os tipos com suporte são "Básico" e "ClientCertificate". Para obter mais informações, consulte Autenticação. Se a autenticação não for necessária, exclua essa propriedade. Uma string ou uma expressão com o valor resultType de uma string. No
timeout Quanto tempo a atividade espera que o retorno de chamada especificado por callBackUri seja invocado. O valor padrão é 10 minutos ("00:10:00"). Os valores têm o formato TimeSpan d.hh:mm:ss. String Não
Relatar status no retorno de chamada Permite que um usuário relate o status de falha de uma atividade do webhook. Boolean No

Autenticação

Uma atividade do webhook dá suporte aos seguintes tipos de autenticação.

Nenhum

Se a autenticação não for necessária, não inclua a propriedade de autenticação.

Basic

Especifique o nome de usuário e a senha a serem usados com a autenticação básica.

"authentication":{
   "type":"Basic",
   "username":"****",
   "password":"****"
}

Certificado do cliente

Especifique o conteúdo codificado em Base64 de um arquivo PFX e uma senha.

"authentication":{
   "type":"ClientCertificate",
   "pfx":"****",
   "password":"****"
}

Identidade gerenciada

Especifique o URI do recurso para o qual o token de acesso será solicitado usando a identidade gerenciada para a instância do workspace do data factory ou do Synapse. Para chamar a API de Gerenciamento de Recursos do Azure, use https://management.azure.com/. Para saber mais sobre como identidades gerenciadas funcionam, confira a Visão geral de identidades gerenciadas para recursos do Azure.

"authentication": {
    "type": "MSI",
    "resource": "https://management.azure.com/"
}

Observação

Se o serviço estiver configurado com um repositório Git, você precisará armazenar suas credenciais no Azure Key Vault para usar a autenticação básica ou de certificado do cliente. O serviço não armazena senhas no Git.

Observações adicionais

O serviço passa a propriedade adicional callBackUri no corpo enviado para o ponto de extremidade do URL. O serviço espera que essa URI seja chamada antes do valor de tempo limite especificado. Se a URI não for chamado, a atividade falhará com o status "TimedOut".

A atividade do webhook falha quando a chamada para o ponto de extremidade personalizado falha. Qualquer mensagem de erro pode ser adicionada ao corpo do retorno de chamada e usada em uma atividade posterior.

Para cada chamada à API REST, o cliente atinge o tempo limite se o ponto de extremidade não responder dentro de um minuto. Esse comportamento é a melhor prática de HTTP padrão. Para corrigir esse problema, implemente um padrão 202. No caso atual, o ponto de extremidade retorna 202 (Aceito) e o cliente pesquisa.

O tempo limite de um minuto na solicitação não tem nada a ver com o tempo limite da atividade. O último é usado para aguardar o retorno de chamada especificado por callbackUri.

O corpo devolvido à URI de retorno de chamada deve ser um JSON válido. Defina o cabeçalho Content-Type como application/json.

Ao usar a propriedade Relatar status no retorno de chamada, você deve adicionar o seguinte código ao corpo ao fazer o retorno de chamada:

{
    "Output": {
        // output object is used in activity output
        "testProp": "testPropValue"
    },
    "Error": {
        // Optional, set it when you want to fail the activity
        "ErrorCode": "testErrorCode",
        "Message": "error message to show in activity error"
    },
    "StatusCode": "403" // when status code is >=400, activity is marked as failed
}

Conteúdo relacionado

Há suporte para as seguintes atividades de fluxo de controle: