Atividade da Web no Azure Data Factory e no Azure Synapse Analytics

Artigo
12/09/2023

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Gorjeta

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

A Atividade da Web pode ser usada para chamar um ponto de extremidade REST personalizado de um pipeline do Azure Data Factory ou Synapse. Pode transmitir conjuntos de dados e serviços ligados aos quais a atividade tem acesso e que pode consumir.

Nota

A Atividade Web é suportada para invocar URLs que são alojados numa rede virtual privada e para tirar partido do runtime de integração autoalojado. O runtime de integração deve ter uma linha visual para o ponto final do URL.

Nota

O tamanho máximo da carga útil de resposta de saída suportada é de 4 MB.

Criar uma atividade da Web com a interface do usuário

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

Pesquise Web no painel Atividades do pipeline e arraste uma atividade da Web para a tela do pipeline.
Selecione a nova atividade da Web na tela, se ainda não estiver selecionada, e sua guia Configurações , para editar seus detalhes.
Especifique uma URL, que pode ser uma cadeia de caracteres de URL literal ou qualquer combinação de expressões dinâmicas , funções, variáveis de sistema ou saídas de outras atividades. Forneça outros detalhes a serem apresentados com o pedido.
Use a saída da atividade como entrada para qualquer outra atividade e faça referência à saída em qualquer lugar em que o conteúdo dinâmico seja suportado na atividade de destino.

Sintaxe

{
   "name":"MyWebActivity",
   "type":"WebActivity",
   "typeProperties":{
      "method":"Post",
      "url":"<URLEndpoint>",
      "httpRequestTimeout": "00:01:00"
      "connectVia": {
          "referenceName": "<integrationRuntimeName>",
          "type": "IntegrationRuntimeReference"
      }
      "headers":{
         "Content-Type":"application/json"
      },
      "authentication":{
         "type":"ClientCertificate",
         "pfx":"****",
         "password":"****"
      },
      "datasets":[
         {
            "referenceName":"<ConsumedDatasetName>",
            "type":"DatasetReference",
            "parameters":{
               ...
            }
         }
      ],
      "linkedServices":[
         {
            "referenceName":"<ConsumedLinkedServiceName>",
            "type":"LinkedServiceReference"
         }
      ]
   }
}

Propriedades do tipo

Propriedade	Description	Valores permitidos	Necessário
nome	Nome da atividade web	Cadeia (de carateres)	Sim
tipo	Deve ser definido como WebActivity.	Cadeia (de carateres)	Sim
método	Método de API REST para o ponto de extremidade de destino.	String. Tipos suportados: "GET", "POST", "PUT", "PATCH", "DELETE"	Sim
URL	Ponto de extremidade e caminho de destino	String (ou expressão com resultType de string). A atividade excederá o tempo limite após um minuto com um erro se não receber uma resposta do ponto final. Você pode aumentar esse tempo limite de resposta em até 10 minutos atualizando a propriedade httpRequestTimeout	Sim
httpRequestTimeout	Duração do tempo limite de resposta	hh:mm:ss com o valor máximo como 00:10:00. Se não for explicitamente especificado, o padrão é 00:01:00	Não
cabeçalhos	Cabeçalhos que são enviados para a solicitação. Por exemplo, para definir o idioma e digitar em uma solicitação: `"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`.	String (ou expressão com resultType de string)	Não
corpo	Representa a carga útil enviada para o ponto de extremidade.	String (ou expressão com resultType de string). Consulte o esquema da carga útil da solicitação na seção Esquema da carga útil da solicitação.	Necessário para métodos POST/PUT/PATCH. Opcional para o método DELETE.
autenticação	Método de autenticação usado para chamar o ponto de extremidade. Os tipos suportados são "Básico, Certificado de cliente, Identidade gerenciada atribuída pelo sistema, Identidade gerenciada atribuída pelo usuário, Entidade de serviço". Para obter mais informações, consulte a seção Autenticação . Se a autenticação não for necessária, exclua esta propriedade.	String (ou expressão com resultType de string)	Não
turnOffAsync	Opção para desativar a invocação do campo HTTP GET no local no cabeçalho de resposta de uma resposta HTTP 202. Se definido true, ele para de invocar HTTP GET no local http fornecido no cabeçalho da resposta. Se definido false, ele continua a invocar a chamada HTTP GET no local fornecido nos cabeçalhos de resposta http.	Os valores permitidos são false (padrão) e true.	Não
disableCertValidation	Remove a validação de certificado do lado do servidor (não recomendada, a menos que você esteja se conectando a um servidor confiável que não use um certificado de autoridade de certificação padrão).	Os valores permitidos são false (padrão) e true.	Não
conjuntos de dados	Lista de conjuntos de dados passados para o ponto de extremidade.	Matriz de referências de conjunto de dados. Pode ser uma matriz vazia.	Sim
linkedServiços	Lista de serviços vinculados passados para o ponto de extremidade.	Matriz de referências de serviço vinculado. Pode ser uma matriz vazia.	Sim
ConecteVia	O tempo de execução de integração a ser usado para se conectar ao armazenamento de dados. Você pode usar o tempo de execução de integração do Azure ou o tempo de execução de integração auto-hospedado (se seu armazenamento de dados estiver em uma rede privada). Se essa propriedade não for especificada, o serviço usará o tempo de execução de integração padrão do Azure.	A referência de tempo de execução de integração.	Não

Nota

Os pontos finais REST que a atividade Web invoca têm de devolver uma resposta do tipo JSON. A atividade excederá o tempo limite após um minuto com um erro se não receber uma resposta do ponto final. Para pontos de extremidade que suportam o padrão de solicitação-resposta assíncrona, a atividade na Web continuará a aguardar sem expirar (até 7 dias) ou até que os pontos de extremidade sinalizem a conclusão do trabalho.

A tabela a seguir mostra os requisitos para o conteúdo JSON:

Tipo de Valor	Corpo do pedido	Corpo da resposta
Objeto JSON	Suportado	Suportado
Matriz JSON	Suportado (Atualmente, as matrizes JSON não funcionam como resultado de um bug. Uma correção está em andamento.)	Não suportado
Valor JSON	Suportado	Não suportado
Tipo não-JSON	Não suportado	Não suportado

Autenticação

Abaixo estão os tipos de autenticação suportados na atividade da Web.

Nenhuma

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

Básica

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

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

Certificado de cliente

Especifique o conteúdo codificado em base64 de um arquivo PFX e a senha.

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

O certificado precisa ser um certificado x509. Para conversão para o arquivo PFX, você pode usar seu utilitário favorito. Para codificação base-64, você pode usar o seguinte trecho do PowerShell.

$fileContentBytes = get-content 'enr.dev.webactivity.pfx' -AsByteStream

[System.Convert]::ToBase64String($fileContentBytes) | Out-File ‘pfx-encoded-bytes.txt’

Identidade Gerida

Especifique o uri do recurso para o qual o token de acesso será solicitado usando a identidade gerenciada para o data factory ou a instância do espaço de trabalho Synapse. Para chamar a API de Gerenciamento de Recursos do Azure, use https://management.azure.com/. Para obter mais informações sobre como as identidades gerenciadas funcionam, consulte a página de visão geral de identidades gerenciadas para recursos do Azure.

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

Nota

Se sua fábrica de dados ou espaço de trabalho Synapse estiver configurado com um repositório git, você deverá armazenar suas credenciais no Cofre da Chave do Azure para usar a autenticação de certificado básica ou de cliente. O serviço não armazena senhas no git.

Solicitar esquema de carga útil

Quando você usa o método POST/PUT, a propriedade body representa a carga útil que é enviada para o ponto de extremidade. Você pode passar serviços vinculados e conjuntos de dados como parte da carga útil. Aqui está o esquema para a carga útil:

{
    "body": {
        "myMessage": "Sample",
        "datasets": [{
            "name": "MyDataset1",
            "properties": {
                ...
            }
        }],
        "linkedServices": [{
            "name": "MyStorageLinkedService1",
            "properties": {
                ...
            }
        }]
    }
}

Exemplo

Neste exemplo, a atividade da Web no pipeline chama um ponto de extremidade REST. Ele passa um serviço vinculado SQL do Azure e um conjunto de dados SQL do Azure para o ponto de extremidade. O ponto de extremidade REST usa a cadeia de conexão SQL do Azure para se conectar ao servidor SQL lógico e retorna o nome da instância do SQL Server.

Definição de pipeline

{
    "name": "<MyWebActivityPipeline>",
    "properties": {
        "activities": [
            {
                "name": "<MyWebActivity>",
                "type": "WebActivity",
                "typeProperties": {
                    "method": "Post",
                    "url": "@pipeline().parameters.url",
                    "headers": {
                        "Content-Type": "application/json"
                    },
                    "authentication": {
                        "type": "ClientCertificate",
                        "pfx": "*****",
                        "password": "*****"
                    },
                    "datasets": [
                        {
                            "referenceName": "MySQLDataset",
                            "type": "DatasetReference",
                            "parameters": {
                                "SqlTableName": "@pipeline().parameters.sqlTableName"
                            }
                        }
                    ],
                    "linkedServices": [
                        {
                            "referenceName": "SqlLinkedService",
                            "type": "LinkedServiceReference"
                        }
                    ]
                }
            }
        ],
        "parameters": {
            "sqlTableName": {
                "type": "String"
            },
            "url": {
                "type": "String"
            }
        }
    }
}

Valores dos parâmetros do pipeline

{
    "sqlTableName": "department",
    "url": "https://adftes.azurewebsites.net/api/execute/running"
}

Código de ponto de extremidade do serviço Web


[HttpPost]
public HttpResponseMessage Execute(JObject payload)
{
    Trace.TraceInformation("Start Execute");

    JObject result = new JObject();
    result.Add("status", "complete");

    JArray datasets = payload.GetValue("datasets") as JArray;
    result.Add("sinktable", datasets[0]["properties"]["typeProperties"]["tableName"].ToString());

    JArray linkedServices = payload.GetValue("linkedServices") as JArray;
    string connString = linkedServices[0]["properties"]["typeProperties"]["connectionString"].ToString();

    System.Data.SqlClient.SqlConnection sqlConn = new System.Data.SqlClient.SqlConnection(connString);

    result.Add("sinkServer", sqlConn.DataSource);

    Trace.TraceInformation("Stop Execute");

    return this.Request.CreateResponse(HttpStatusCode.OK, result);
}

Veja outras atividades de fluxo de controle suportadas:

Atividade da Web no Azure Data Factory e no Azure Synapse Analytics

Criar uma atividade da Web com a interface do usuário

Sintaxe

Propriedades do tipo

Autenticação

Nenhuma

Básica

Certificado de cliente

Identidade Gerida

Solicitar esquema de carga útil

Exemplo

Definição de pipeline

Valores dos parâmetros do pipeline

Código de ponto de extremidade do serviço Web

Conteúdos relacionados

Recursos adicionais