Atividade do webhook no Azure Data Factory

Artigo
10/20/2023

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:

Procure Webhook no painel Atividades do pipeline e arraste uma atividade Webhook para a tela do pipeline.
Selecione a nova atividade de webhook na tela, se ela ainda não estiver selecionada, e a guia Configurações para editar seus detalhes.
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.
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
}

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