Transformar dados usando a atividade Script no Azure Data Factory ou no Synapse Analytics

  • 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!

Use atividades de transformação de dados em um pipeline do Data Factory ou do Synapse para transformar e processar dados brutos em previsões e informações. A atividade Script é uma das atividades de transformação compatíveis com os pipelines. Este artigo baseia-se no artigo Transformar dados, que apresenta uma visão geral da transformação de dados e das atividades de transformação compatíveis.

Usando a atividade Script, você pode executar operações comuns com a DML (linguagem de manipulação de dados) e a DDL (linguagem de definição de dados). Instruções DML como INSERT, UPDATE, DELETE e SELECT permitem que os usuários insiram, modifiquem, excluam e recuperem dados no banco de dados. Instruções DDL como CREATE, ALTER e DROP permitem que um gerente de banco de dados crie, modifique e remova objetos de banco de dados, como tabelas, índices e usuários.

Use a atividade Script para invocar um script SQL em um dos seguintes armazenamentos de dados na sua empresa ou em uma VM (máquina virtual) do Azure:

  • Banco de Dados SQL do Azure
  • Azure Synapse Analytics
  • Banco de Dados do SQL Server. Se estiver usando o SQL Server, instale o Integration Runtime (auto-hospedado) no mesmo computador que hospeda o banco de dados ou em um computador separado com acesso ao banco de dados. O Integration Runtime (auto-hospedado) é um componente que conecta fontes de dados locais ou em uma VM do Azure aos serviços de nuvem de maneira segura e gerenciada. Confira o artigo Runtime de integração auto-hospedada para obter detalhes.
  • Oracle
  • Snowflake

O script pode conter uma só instrução SQL ou várias instruções SQL que são executadas em sequência. A tarefa Script pode ser usada para os seguintes propósitos:

  • Corte uma tabela em preparação para inserir dados.
  • Criar, alterar e descartar objetos de banco de dados como tabelas e exibições.
  • Recriar tabelas de fatos e de dimensões antes de carregar dados nelas.
  • Executar procedimentos armazenados. Se a instrução SQL invocar um procedimento armazenado que retorne resultados de uma tabela temporária, use a opção de WITH RESULT SETS para definir metadados para o conjunto de resultados.
  • Salve o conjunto de linhas retornado de uma consulta como uma saída da atividade para consumo downstream.

Detalhes da sintaxe

Este é o formato JSON para definir uma atividade Script:

{ 
   "name": "<activity name>", 
   "type": "Script", 
   "linkedServiceName": { 
      "referenceName": "<name>", 
      "type": "LinkedServiceReference" 
    }, 
   "typeProperties": { 
      "scripts" : [ 
         { 
            "text": "<Script Block>", 
            "type": "<Query> or <NonQuery>", 
            "parameters":[ 
               { 
                  "name": "<name>", 
                  "value": "<value>", 
                  "type": "<type>", 
                  "direction": "<Input> or <Output> or <InputOutput>", 
                  "size": 256 
               }, 
               ... 
            ] 
         }, 
         ... 
      ],     
         ... 
         ] 
      }, 
      "scriptBlockExecutionTimeout": "<time>",  
      "logSettings": { 
         "logDestination": "<ActivityOutput> or <ExternalStore>", 
         "logLocationSettings":{ 
            "linkedServiceName":{ 
               "referenceName": "<name>", 
               "type": "<LinkedServiceReference>" 
            }, 
            "path": "<folder path>" 
         } 
      } 
    } 
}

A seguinte tabela descreve essas propriedades JSON:

Nome da propriedade Descrição Obrigatório
name O nome da atividade. Sim
type O tipo da atividade, definido como “Script”. Sim
typeProperties Especifique as propriedades para configurar a atividade Script. Sim
linkedServiceName O banco de dados de destino em que o script será executado. Ele deve ser uma referência a um serviço vinculado. Sim
scripts Uma matriz de objetos para representar o script. Não
scripts.text O texto sem formatação de um bloco de consultas. No
scripts.type O tipo do bloco de consultas. Pode ser Query ou NonQuery. Padrão: Query. No
scripts.parameter A matriz de parâmetros do script. No
scripts.parameter.name O nome do parâmetro. No
scripts.parameter.value O valor do parâmetro. No
scripts.parameter.type O tipo de dados do parâmetro. O tipo é do tipo lógico e segue o mapeamento de tipo de cada conector. No
scripts.parameter.direction A direção do parâmetro. Pode ser Input, Output ou InputOutput. O valor será ignorado se a direção for Output. Não há suporte para o tipo ReturnValue. Defina o valor retornado de SP como um parâmetro de saída para recuperá-lo. No
scripts.parameter.size O tamanho máximo do parâmetro. Aplica-se somente ao parâmetro de direção Output/InputOutput do tipo string/byte[]. Não
scriptBlockExecutionTimeout O tempo de espera para que a operação de execução do bloco de script seja concluída antes de atingir o tempo limite. Não
logSettings As configurações usadas para armazenar os logs de saída. Se isso não for especificado, o log de script será desabilitado. No
logSettings.logDestination O destino da saída de log. Pode ser ActivityOutput ou ExternalStore. Padrão: ActivityOutput. Não
logSettings.logLocationSettings As configurações do local de destino, se o logDestination for ExternalStore. Não
logSettiongs.logLocationSettings.linkedServiceName O serviço vinculado do local de destino. Só há suporte para o armazenamento de blobs. No
logSettings.logLocationSettings.path O caminho da pasta na qual os logs serão armazenados. No

Saída de Atividade

Saída de exemplo:

{ 
    "resultSetCount": 2, 
    "resultSets": [ 
        { 
            "rowCount": 10, 
            "rows":[ 
                { 
                    "<columnName1>": "<value1>", 
                    "<columnName2>": "<value2>", 
                    ... 
                } 
            ] 
        }, 
        ... 
    ], 
    "recordsAffected": 123, 
    "outputParameters":{ 
        "<parameterName1>": "<value1>", 
        "<parameterName2>": "<value2>" 
    }, 
    "outputLogs": "<logs>", 
    "outputLogsLocation": "<folder path>", 
    "outputTruncated": true, 
    ... 
}
Nome da propriedade Descrição Condição
resultSetCount A contagem de conjuntos de resultados retornados pelo script. Sempre
resultSets A matriz que contém todos os conjuntos de resultados. Sempre
resultSets.rowCount Total de linhas no conjunto de resultados. Sempre
resultSets.rows A matriz de linhas no conjunto de resultados. Sempre
recordsAffected A contagem de linhas afetadas pelo script. Se scriptType for NonQuery.
outputParameters Os parâmetros de saída do script. Se o tipo de parâmetro for Output ou InputOutput.
outputLogs Os logs gravados pelo script, por exemplo, a instrução print. Se o conector der suporte à instrução log e enableScriptLogs for verdadeiro e logLocationSettings não for fornecido.
outputLogsPath O caminho completo do arquivo de log. Se enableScriptLogs for verdadeiro e logLocationSettings for fornecido.
outputTruncated Indica se a saída excede os limites e se fica truncada. Se a saída exceder os limites.

Observação

  • A saída é coletada toda vez que um bloco de script é executado. A saída final é o resultado mesclado de todas as saídas de bloco de script. O parâmetro de saída com o mesmo nome em um bloco de script diferente será substituído.
  • Como a saída tem uma limitação de tamanho/linhas, a saída será truncada na seguinte ordem: logs -> parâmetros -> linhas. Observe que isso se aplica a um só bloco de script, o que significa que as linhas de saída do próximo bloco de script não removerão os logs anteriores.
  • Qualquer erro causado pelo log não causará uma falha na atividade.
  • Para consumir os resultSets da saída da atividade na atividade downstream, confira a documentação Resultados da atividade de pesquisa.
  • Use outputLogs quando estiver usando instruções 'PRINT' para fins de log. Se a consulta retornar resultSets, ela estará disponível na saída da atividade e será limitada a 5 mil linhas/limite de tamanho de 4 MB.

Configurar a atividade Script usando a interface do usuário

Script embutido

Screenshot showing the UI to configure an inline script.

Os scripts embutidos se integram bem ao CI/CD do pipeline, pois o script é armazenado como parte dos metadados do pipeline.

Logging

Screenshot showing the UI for the logging settings for a script.

Opções de log:

  • Desabilitar – nenhuma saída de execução é registrada.
  • Saída da atividade - A saída da execução do script é anexada à saída da atividade. Ela pode ser consumida por atividades de downstream. O tamanho de saída é limitado a 4 MB.
  • Armazenamento externo - Persiste a saída para armazenamento. Use essa opção se o tamanho da saída for maior que 2 MB ou se quiser persistir a saída explicitamente na sua conta de armazenamento.

Observação

Cobrança – A atividade Script será cobrada como atividades de pipeline.

Conteúdo relacionado

Consulte os seguintes artigos que explicam como transformar dados de outras maneiras: