Parâmetros para o Data Factory no Microsoft Fabric

Este documento descreve como usar parâmetros em seus pipelines para o Data Factory na malha.

Como usar parâmetros, expressões e funções em pipelines para o Data Factory na malha

Neste documento, nos concentramos em aprender conceitos fundamentais com vários exemplos para explorar a capacidade de criar pipelines de dados parametrizados no Data Factory in Fabric. A parametrização e as expressões dinâmicas podem economizar uma enorme quantidade de tempo e permitir uma solução muito mais flexível de Extrair, Transformar, Carregar (ETL) ou Extrair, Carregar, Transformar (ELT), o que reduzirá drasticamente o custo de manutenção da solução e acelerará a implementação de novos recursos em pipelines existentes. Esses ganhos ocorrem porque a parametrização minimiza a quantidade de codificação rígida e aumenta o número de objetos e processos reutilizáveis em uma solução.

Conceitos de parâmetros e expressões

Você pode usar parâmetros para passar valores externos para pipelines. Uma vez que o parâmetro tenha sido passado para o recurso, ele não pode ser alterado. Ao parametrizar recursos, você pode reutilizá-los com valores diferentes a cada vez. Os parâmetros podem ser usados individualmente ou como parte de expressões. Os valores de parâmetros na definição podem ser literais ou expressões que são avaliadas em tempo de execução.

As expressões podem aparecer em qualquer lugar em um valor de cadeia de caracteres e sempre gerar outro valor de cadeia de caracteres. Aqui, senha é um parâmetro de pipeline na expressão. Se um valor de parâmetro for uma expressão, o corpo da expressão será extraído removendo o sinal de at-sign (@). Se for necessária uma cadeia de caracteres literal que comece com @, ela deverá ser escapada usando @@. Os exemplos a seguir mostram como as expressões são avaliadas.

Valor do parâmetro Result
"parâmetros" Os caracteres 'parâmetros' são retornados.
"parâmetros[1]" Os caracteres 'parameters[1]' são retornados.
"@@" Uma cadeia de caracteres de 1 caractere que contém '@' é retornada.
" @" Uma cadeia de 2 caracteres que contém ' @' é retornada.

As expressões também podem aparecer dentro de cadeias de caracteres, usando um recurso chamado interpolação de cadeia de caracteres, onde as expressões são encapsuladas em @{ ... }. Por exemplo, a cadeia de caracteres a seguir inclui valores de parâmetro e valores de cadeia de caracteres literal:

"Nome: @{pipeline().parameters.firstName} Sobrenome: @{pipeline().parameters.lastName}"

Usando interpolação de cadeia de caracteres, o resultado é sempre uma cadeia de caracteres. Por exemplo, se você definiu myNumber como e myString comofoo42:

Valor do parâmetro Result
"@pipeline().parameters.myString" Retorna foo como uma cadeia de caracteres.
"@{pipeline().parameters.myString}" Retorna foo como uma cadeia de caracteres.
"@pipeline().parameters.myNumber" Devolve 42 como um número.
"@{pipeline().parameters.myNumber}" Retorna 42 como uma cadeia de caracteres.
"A resposta é: @{pipeline().parameters.myNumber}" Retorna a cadeia de caracteres Answer is: 42.
"@concat('A resposta é: ', string(pipeline().parameters.myNumber))" Retorna a cadeia de caracteres Answer is: 42
"A resposta é: @@{pipeline().parameters.myNumber}" Retorna a cadeia de caracteres Answer is: @{pipeline().parameters.myNumber}.

Exemplos de uso de parâmetros em expressões

Criação e utilização de parâmetros

Para criar parâmetros, selecione o plano de fundo da tela do editor de pipeline e, em seguida, a guia Parâmetros da janela de propriedades na parte inferior. Selecione o botão + Novo para adicionar um novo parâmetro ao pipeline, dê a ele um nome, um tipo de dados e um valor padrão:

Screenshot showing the Parameters editor on the properties pages for a pipeline.

Em seguida, você pode usar o parâmetro em qualquer lugar do pipeline em que o conteúdo dinâmico seja suportado. Neste exemplo, o parâmetro é usado para fornecer dinamicamente o nome de um armazenamento de dados Lakehouse na guia Source das páginas de propriedades de uma atividade de cópia.

Screenshot showing the Source tab of a copy activity's property pages, highlighting the Add dynamic content option.

A janela Adicionar conteúdo dinâmico é exibida, permitindo especificar qualquer tipo de conteúdo dinâmico, incluindo parâmetros, variáveis do sistema, funções ou variáveis de pipeline. Neste exemplo, o parâmetro definido anteriormente é selecionado e a janela de conteúdo dinâmico é preenchida automaticamente com a expressão correta para fazer referência ao parâmetro.

Screenshot showing the Add dynamic content window with a pipeline parameter selected.

Exemplo de expressão complexa

O exemplo abaixo mostra um exemplo complexo que faz referência a um subcampo profundo da saída da atividade. Para fazer referência a um parâmetro de pipeline que é avaliado para um subcampo, use a sintaxe [] em vez do operador dot(.) (como no caso do subcampo1 e subcampo2)

@activity('*activityName*').output.*subfield1*.*subfield2*[pipeline().parameters.*subfield3*].*subfield4*

Editor de conteúdo dinâmico

O editor de conteúdo dinâmico escapa automaticamente dos caracteres do seu conteúdo quando você termina de editar. Por exemplo, o seguinte conteúdo no editor de conteúdo é uma interpolação de cadeia de caracteres com uma função de expressão:

@{toUpper('myData')}

O editor de conteúdo dinâmico converte o conteúdo acima para a seguinte expressão:

MYDATA

Usando funções e variáveis em expressões

Você pode chamar funções e usar variáveis dentro de expressões. As seções a seguir fornecem informações sobre as funções que podem ser usadas em uma expressão.

Variáveis de escopo do pipeline

Essas variáveis de sistema podem ser referenciadas em qualquer lugar no pipeline JSON.

Nome da variável Description
@pipeline().DataFactory Nome dos dados ou espaço de trabalho Synapse em que o pipeline executado está sendo executado
@pipeline().Pipeline Nome do gasoduto
@pipeline().RunId ID da execução do pipeline específico
@pipeline().TriggerId ID do gatilho que invocou o pipeline
@pipeline().TriggerName Nome do gatilho que invocou o pipeline
@pipeline().TriggerTime Hora da execução do gatilho que invocou o pipeline. Este é o momento em que o gatilho realmente disparou para invocar a execução do pipeline, e pode diferir ligeiramente do tempo agendado do gatilho.
@pipeline().GroupId ID do grupo ao qual o pipeline é executado.
@pipeline()?. TriggeredByPipelineName Nome do pipeline que aciona a execução do pipeline. Aplicável quando a execução do pipeline é acionada por uma atividade ExecutePipeline. Avalie como Nulo quando usado em outras circunstâncias. Observe o ponto de interrogação após @pipeline()
@pipeline()?. TriggeredByPipelineRunId ID de execução do pipeline que dispara a execução do pipeline. Aplicável quando a execução do pipeline é acionada por uma atividade ExecutePipeline. Avalie como Nulo quando usado em outras circunstâncias. Observe o ponto de interrogação após @pipeline()

Nota

As variáveis do sistema de data/hora relacionadas ao gatilho (nos escopos de pipeline e gatilho) retornam datas UTC no formato ISO 8601, por exemplo, 2017-06-01T22:20:00.4061448Z.

Funções de cadeia

Para trabalhar com cadeias de caracteres, você pode usar essas funções de cadeia de caracteres e também algumas funções de coleção. As funções de cadeia de caracteres funcionam apenas em cadeias de caracteres.

Função da cadeia de carateres Tarefa
concat Combine duas ou mais cadeias de caracteres e retorne a cadeia combinada.
termina com Verifique se uma cadeia de caracteres termina com a subcadeia especificada.
GUID Gere um identificador global exclusivo (GUID) como uma cadeia de caracteres.
indexOf Retornar a posição inicial de uma substring.
lastIndexOf Retorne a posição inicial para a última ocorrência de uma substring.
replace Substitua uma substring pela string especificada e retorne a string atualizada.
split Retorna uma matriz que contém substrings, separadas por vírgulas, de uma cadeia de caracteres maior com base em um caractere delimitador especificado na cadeia de caracteres original.
começaCom Verifique se uma cadeia de caracteres começa com uma subcadeia de caracteres específica.
substring Retorna caracteres de uma cadeia de caracteres, começando a partir da posição especificada.
paraMais baixo Retornar uma cadeia de caracteres em formato minúsculo.
toUpper Retornar uma cadeia de caracteres em formato maiúsculo.
guarnição Remova o espaço em branco à esquerda e à direita de uma cadeia de caracteres e retorne a cadeia de caracteres atualizada.

Funções de recolha

Para trabalhar com coleções, geralmente matrizes, cadeias de caracteres e, às vezes, dicionários, você pode usar essas funções de coleção.

Função de recolha Tarefa
contém: Verifique se uma coleção tem um item específico.
empty Verifique se uma coleção está vazia.
primeiro Retornar o primeiro item de uma coleção.
intersecção Retornar uma coleção que tenha apenas os itens comuns nas coleções especificadas.
aderir Retorna uma cadeia de caracteres que tem todos os itens de uma matriz, separados pelo caractere especificado.
último Retornar o último item de uma coleção.
length Retornar o número de itens em uma cadeia de caracteres ou matriz.
pular Remova itens da frente de uma coleção e devolva todos os outros itens.
tomar Devolver itens da frente de uma coleção.
União Retornar uma coleção que tenha todos os itens das coleções especificadas.

Funções lógicas

Estas funções são úteis dentro das condições, elas podem ser usadas para avaliar qualquer tipo de lógica.

Função de comparação lógica Tarefa
and Verifique se todas as expressões são verdadeiras.
igual a Verifique se ambos os valores são equivalentes.
greater Verifique se o primeiro valor é maior que o segundo.
greaterOrEquals Verifique se o primeiro valor é maior ou igual ao segundo valor.
se Verifique se uma expressão é verdadeira ou falsa. Com base no resultado, retorne um valor especificado.
less Verifique se o primeiro valor é menor que o segundo.
lessOrEquals Verifique se o primeiro valor é menor ou igual ao segundo valor.
não Verifique se uma expressão é falsa.
ou Verifique se pelo menos uma expressão é verdadeira.

Funções de conversão

Essas funções são usadas para converter entre cada um dos tipos nativos na linguagem:

  • string
  • integer
  • flutuante
  • boolean
  • matrizes
  • dicionários
Função de conversão Tarefa
matriz Retornar uma matriz de uma única entrada especificada. Para várias entradas, consulte createArray.
base64 Retorne a versão codificada em base64 para uma cadeia de caracteres.
base64ToBinary Retorne a versão binária para uma cadeia de caracteres codificada em base64.
base64ToString Retorne a versão da cadeia de caracteres para uma cadeia de caracteres codificada em base64.
binário Retornar a versão binária para um valor de entrada.
Bool Retorne a versão booleana para um valor de entrada.
coalesce Retorna o primeiro valor não nulo de um ou mais parâmetros.
createArray Retornar uma matriz de várias entradas.
dataUri Retornar o URI de dados para um valor de entrada.
dataUriToBinary Retornar a versão binária para um URI de dados.
dataUriToString Retornar a versão da cadeia de caracteres para um URI de dados.
decodeBase64 Retorne a versão da cadeia de caracteres para uma cadeia de caracteres codificada em base64.
decodeDataUri Retornar a versão binária para um URI de dados.
decodeUriComponent Retorna uma cadeia de caracteres que substitui caracteres de escape por versões decodificadas.
encodeUriComponent Retorna uma cadeia de caracteres que substitui caracteres não seguros de URL por caracteres de escape.
flutuar Retorna um número de ponto flutuante para um valor de entrada.
Int Retorne a versão inteira para uma cadeia de caracteres.
Json Retorne o valor ou objeto do tipo JSON (JavaScript Object Notation) para uma cadeia de caracteres ou XML.
string Retorne a versão da cadeia de caracteres para um valor de entrada.
uriComponent Retorne a versão codificada por URI para um valor de entrada substituindo caracteres não seguros de URL por caracteres de escape.
uriComponentToBinary Retorne a versão binária para uma cadeia de caracteres codificada por URI.
uriComponentToString Retorne a versão da cadeia de caracteres para uma cadeia de caracteres codificada por URI.
xml Retornar a versão XML para uma cadeia de caracteres.
XPath Verifique se há nós ou valores que correspondam a uma expressão XPath (XML Path Language) e retorne os nós ou valores correspondentes.

Funções matemáticas

Estas funções podem ser usadas para qualquer tipo de números: inteiros e flutuantes.

Função matemática Tarefa
adicionar Retornar o resultado da adição de dois números.
div Retornar o resultado da divisão de dois números.
máx. Retornar o valor mais alto de um conjunto de números ou de uma matriz.
min Retornar o menor valor de um conjunto de números ou de uma matriz.
Mod Retorne o restante da divisão de dois números.
Mul Devolva o produto multiplicando dois números.
RAND Retornar um inteiro aleatório de um intervalo especificado.
range Retornar uma matriz inteira que começa a partir de um inteiro especificado.
sub Retornar o resultado subtraindo o segundo número do primeiro número.

Funções de data

Função de data ou hora Tarefa
addDias Adicione um número de dias a um carimbo de data/hora.
addHours Adicione um número de horas a um carimbo de data/hora.
adicionarMinutos Adicione alguns minutos a um carimbo de data/hora.
addSeconds Adicione alguns segundos a um carimbo de data/hora.
addToTime Adicione várias unidades de tempo a um carimbo de data/hora. Consulte também getFutureTime.
convertFromUtc Converta um carimbo de data/hora de Universal Time Coordinated (UTC) para o fuso horário de destino.
convertTimeZone Converta um carimbo de data/hora do fuso horário de origem para o fuso horário de destino.
convertToUtc Converta um carimbo de data/hora do fuso horário de origem em Universal Time Coordinated (UTC).
diadeMês Retornar o componente dia do mês de um carimbo de data/hora.
diadesemana Retornar o componente dia da semana de um carimbo de data/hora.
diadeano Retornar o componente dia do ano de um carimbo de data/hora.
formatDateTime Retorne o carimbo de data/hora como uma cadeia de caracteres no formato opcional.
getFutureTime Retorne o carimbo de data/hora atual mais as unidades de tempo especificadas. Consulte também addToTime.
getPastTime Retorne o carimbo de data/hora atual menos as unidades de tempo especificadas. Consulte também subtractFromTime.
inícioOfDay Retorne o início do dia para um carimbo de data/hora.
iníciodehora Retorne o início da hora para um carimbo de data/hora.
iníciodemês Retorne o início do mês para um carimbo de data/hora.
subtrairFromTime Subtraia várias unidades de tempo de um carimbo de data/hora. Consulte também getPastTime.
carrapatos Retornar o valor da propriedade para um carimbo ticks de data/hora especificado.
utcAgora Retorne o carimbo de data/hora atual como uma cadeia de caracteres.