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

Artigo
09/25/2024

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!

A atividade da Web pode ser usada para chamar um ponto de extremidade REST personalizado de um pipeline do Azure Data Factory ou do Synapse. Você pode passar conjuntos de dados e serviços vinculados a serem consumidos e acessados pela atividade.

Observação

A atividade da Web também pode invocar URLs que são hospedadas em uma rede virtual privada aproveitando o runtime de integração auto-hospedada. O runtime de integração deve ter uma linha de visão para o ponto de extremidade da URL.

Observação

O tamanho máximo do conteúdo de resposta de saída com suporte é de 4 MB.

Criar uma atividade da Web com interface do usuário

Para usar uma atividade da Web em um pipeline, siga estas etapas:

Procure 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 a guia Configurações para editar os detalhes.
Especifique uma URL, que pode ser uma expressão de cadeia de caracteres literais ou 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":"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 de tipo

Propriedade	Descrição	Valores permitidos	Obrigatório
name	Nome da atividade da Web	String	Sim
type	Deve ser definido como WebActivity.	String	Sim
method	Método da API REST para o ponto de extremidade de destino.	Cadeia de caracteres. Tipos com suporte: "GET", "POST", "PUT", "PATCH", "DELETE"	Sim
url	Ponto de extremidade de destino e o caminho	Cadeia de caracteres (ou expressão com um resultType de cadeia de caracteres). A atividade atingirá o tempo limite em 1 minuto com um erro se não receber uma resposta do ponto de extremidade. 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 especificado explicitamente, o padrão será 00:01:00	Não
headers	Cabeçalhos que são enviados para a solicitação. Por exemplo, para definir o idioma e o tipo em uma solicitação: `"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`.	Cadeia de caracteres (ou expressão com um resultType de cadeia de caracteres)	Não
body	Representa o conteúdo enviado para o ponto de extremidade.	Cadeia de caracteres (ou expressão com um resultType de cadeia de caracteres). Consulte o esquema da carga de solicitação na seção Esquema de carga de solicitação.	Necessário para os métodos PUT/POST/PATCH. Opcional para o método DELETE.
autenticação	Método de autenticação usado para chamar o ponto de extremidade. Os tipos com suporte são "Basic, Client Certificate, System-assigned Managed Identity, User-assigned Managed Identity, Service Principal". Para obter mais informações, consulte a seção Autenticação. Se a autenticação não for necessária, exclua essa propriedade.	Cadeia de caracteres (ou expressão com um resultType de cadeia de caracteres)	Não
turnOffAsync	Opção para desabilitar a invocação de HTTP GET no campo local no cabeçalho de resposta de uma resposta HTTP 202. Se definido como true, ele para de invocar HTTP GET no local http fornecido no cabeçalho de resposta. Se definido como false, ele continuará invocando 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 recomendado, a menos que você esteja se conectando a um servidor confiável que não usa 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 do conjunto de dados. Pode ser uma matriz vazia.	Sim
linkedServices	Lista de serviços vinculados passado ao ponto de extremidade.	Matriz de referências de serviço vinculado. Pode ser uma matriz vazia.	Sim
connectVia	O runtime de integração a ser usado para se conectar ao armazenamento de dados. Use o runtime de integração do Azure ou o runtime de integração auto-hospedada (se o seu armazenamento de dados estiver em uma rede privada). Se essa propriedade não for especificada, o serviço usará o runtime de integração do Azure padrão.	A referência de runtime de integração.	Não

Observação

Os pontos de extremidade REST que invoca a atividade da Web invoca devem retornar para uma resposta do JSON de tipo. A atividade atingirá o tempo limite em 1 minuto com um erro se não receber uma resposta do ponto de extremidade. Para pontos de extremidade que dão suporte ao padrão de Solicitação/Resposta assíncronos, a atividade da Web continuará aguardando sem atingir o tempo limite (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 da solicitação	Corpo da resposta
Objeto JSON	Com suporte	Com suporte
Matriz JSON	com suporte (No momento, matrizes JSON não funcionam como resultado de um bug. Uma correção está em andamento.)	Sem suporte
Valor JSON	Com suporte	Sem suporte
Tipo não-JSON	Sem suporte	Sem suporte

Autenticação

Veja abaixo os tipos de autenticação compatíveis com a atividade da Web.

Nenhum

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

Basic

Especifique o nome de usuário e 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 a senha.

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

O certificado precisa ser um certificado x509. Para conversão em arquivo PFX, você pode usar seu utilitário de preferência. Para codificação de base 64, você pode usar o snippet do PowerShell a seguir.

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

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

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 obter mais informações sobre como identidades gerenciadas funcionam, confira a página de visão geral de identidades gerenciadas para recursos do Azure.

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

Observação

Se o workspace do data factory ou do Synapse 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.

Entidade de serviço

Especifique a ID do locatário, a ID da entidade de serviço e a chave da entidade de serviço, usando uma cadeia de caracteres segura para o segredo do cliente.

"authentication": {
            "type": "ServicePrincipal",
            "tenant": "your_tenant_id",
            "servicePrincipalId": "your_client_id",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "your_client_secret"
            },
            "resource": "https://management.azure.com/"
}

Solicitar esquema de carga

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

{
    "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 do 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 do SQL do Azure para se conectar ao servidor SQL lógico e retorna o nome da instância do servidor SQL.

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 de parâmetro do pipeline

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

Código do ponto de extremidade de 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 com suporte:

Compartilhar via

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

Criar uma atividade da Web com interface do usuário

Sintaxe

Propriedades de tipo

Autenticação

Nenhum

Basic

Certificado do cliente

Identidade Gerenciada

Entidade de serviço

Solicitar esquema de carga

Exemplo

Definição de pipeline

Valores de parâmetro do pipeline

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

Comentários

Recursos adicionais

Compartilhar via

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

Criar uma atividade da Web com interface do usuário

Sintaxe

Propriedades de tipo

Autenticação

Nenhum

Basic

Certificado do cliente

Identidade Gerenciada

Entidade de serviço

Solicitar esquema de carga

Exemplo

Definição de pipeline

Valores de parâmetro do pipeline

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

Conteúdo relacionado

Comentários

Recursos adicionais