Parâmetros do Data Factory no Microsoft Fabric

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

Como usar os parâmetros, expressões e funções no Azure Data Factory

Neste documento, vamos focar nos conceitos fundamentais de aprendizagem e analisar vários exemplos para explorar a capacidade de criar pipelines de dados com parâmetros dentro do Azure Data Factory. A parametrização e as expressões dinâmicas podem economizar muito tempo e permitir uma solução Extrair, Transformar, Carregar (ETL) ou Extrair, Carregar, Transformar (ELT) muito mais flexível, o que reduzirá drasticamente o custo de manutenção da solução e acelerará a implementação de novos recursos em pipelines existentes. Você ganha esses benefícios porque a parametrização reduz 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âmetro e expressão

Você pode usar parâmetros para passar valores externos em pipelines, conjuntos de dados, serviços vinculados e fluxos de dados. O parâmetro não pode ser alterado depois que passar para o recurso. Ao parametrizar recursos, você pode reutilizá-los com valores diferentes sempre que desejar. Os parâmetros podem ser usados individualmente ou como parte de expressões. Os valores de parâmetro na definição podem ser literais ou expressões que são avaliadas no runtime.

As expressões podem aparecer em qualquer lugar em um valor de string e sempre gerar outro valor de string. Aqui, a 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 arroba (@). Se for necessária uma cadeia de caracteres literal que começa com @, seu escape deverá ser feito usando @@. Os exemplos a seguir mostram como as expressões são avaliadas.

Valor do parâmetro	Resultado
"parameters"	Os “parâmetros” dos caracteres são retornados.
"parameters[1]"	Os “parâmetros[1]” dos caracteres são retornados.
"@@"	Uma cadeia de caracteres de 1 caractere que contém \'\@\' será retornada.
" @"	Uma cadeia de caracteres de 2 caracteres que contém ' \@\' será retornada.

As expressões também podem aparecer dentro de cadeias de caracteres usando um recurso chamado interpolação de cadeia de caracteres em que as expressões estã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 42 e myString como foo:

Valor do parâmetro	Resultado
"@pipeline().parameters.myString"	Retorna foo como uma cadeia de caracteres.
"@{pipeline().parameters.myString}"	Retorna foo como uma cadeia de caracteres.
"@pipeline().parameters.myNumber"	Retorna 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('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 como usar parâmetros em expressões

Como criar e usando parâmetros

Para criar parâmetros, selecione a tela 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:

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

A janela Adicionar conteúdo dinâmico é exibida, permitindo que você especifique 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 .

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 como um subcampo, use a sintaxe [] em vez do operador ponto (.) (como no caso de subfield1 e subfield2)

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

Editor de conteúdo dinâmico

O editor de conteúdo dinâmico automaticamente dá escape nos caracteres do conteúdo quando você termina de editá-lo. Por exemplo, o conteúdo a seguir, no editor de conteúdo, é uma interpolação de cadeia de caracteres com duas funções de expressão:

@{toUpper('myData')}

O editor de conteúdo dinâmico converte o conteúdo acima na 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 usados em uma expressão.

Variáveis de escopo do pipeline

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

Nome da variável	Descrição
@pipeline().DataFactory	Nome dos dados ou do workspace do Synapse em que a execução de pipeline está ocorrendo
@pipeline().Pipeline	Nome do pipeline
@pipeline().RunId	ID da execução do pipeline específica
@pipeline().TriggerId	ID do gatilho que invocou o pipeline
@pipeline().TriggerName	Nome do gatilho que invocou o pipeline
@pipeline().TriggerTime	Horário de execução de gatilho que invocou o pipeline. Esse é o horário em que o gatilho realmente foi disparado para invocar a execução de pipeline e pode ser ligeiramente diferente do horário agendado do gatilho.
@pipeline().GroupId	ID do grupo ao qual a execução de pipeline pertence.
@pipeline()?.TriggeredByPipelineName	Nome do pipeline que aciona a execução de pipeline. Aplicável quando a execução de 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 de pipeline que aciona a execução de pipeline. Aplicável quando a execução de pipeline é acionada por uma atividade ExecutePipeline. Avalie como Nulo quando usado em outras circunstâncias. Observe o ponto de interrogação após @pipeline()

Observação

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 de caracteres

Para trabalhar com cadeias de caracteres, você pode usar essas funções de cadeia de caracteres e algumas funções de coleta. Funções de cadeia de caracteres só funcionam com cadeias de caracteres.

Função de cadeia de caracteres	Tarefa
concat	Combinar duas ou mais cadeias de caracteres e retornar a cadeia de caracteres combinada.
endsWith	Verificar se uma cadeia de caracteres termina com a subcadeia de caracteres especificada.
guid	Gerar um GUID (identificador global exclusivo) como uma cadeia de caracteres.
indexOf	Retornar a posição inicial de uma subcadeia de caracteres.
lastIndexOf	Retorna a posição inicial da última ocorrência de uma subcadeia de caracteres.
substitui	Substituir uma subcadeia de caracteres pela cadeia de caracteres especificada e retornar a cadeia de caracteres atualizada.
split	Retorna uma matriz contendo subcadeias de caracteres, separadas por vírgulas, de uma cadeia de caracteres maior baseada em um caractere delimitador especificado na cadeia de caracteres original.
startsWith	Verificar se uma cadeia de caracteres começa com uma subcadeia de caracteres específica.
substring	Retornar caracteres de uma cadeia de caracteres, começando na posição especificada.
toLower	Retornar uma cadeia de caracteres em letras minúsculas.
toUpper	Retornar uma cadeia de caracteres em letras maiúsculas.
cortar	Remover espaços em branco à esquerda e à direita de uma cadeia de caracteres e retornar a cadeia de caracteres atualizada.

Funções de coleção

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

Função de coleção	Tarefa
contains	Verificar se uma coleção tem um item específico.
empty	Verifique se uma coleção está vazia.
first	Retornar o primeiro item de uma coleção.
intersection	Retornar uma coleção que tem somente os itens comuns entre as coleções especificadas.
join	Retornar uma cadeia de caracteres que tem todos os itens de uma matriz, separados pelo caractere especificado.
last	Retornar o último item de uma coleção.
length	Retornar o número de itens em uma cadeia de caracteres ou matriz.
skip	Remover itens do início de uma coleção e retornar todos os outros itens.
take	Retornar itens do início de uma coleção.
union	Retornar uma coleção que tem todos os itens das coleções especificadas.

Funções lógicas

Essas funções são úteis em condições e podem ser usadas para avaliar qualquer tipo de lógica.

Função de comparação lógica	Tarefa
and	Verificar se todas as expressões são verdadeiras.
equals	Verificar se os dois valores são equivalentes.
greater	Verificar se o primeiro valor é maior que o segundo valor.
greaterOrEquals	Verificar se o primeiro valor é superior ou igual ao segundo.
if	Verificar se uma expressão é verdadeira ou falsa. Com base no resultado, retornar um valor especificado.
less	Verificar se o primeiro valor é menor que o segundo valor.
lessOrEquals	Verificar se o primeiro valor é inferior ou igual ao segundo valor.
not	Verificar se uma expressão é falsa.
or	Verificar 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 no idioma:

• string
• inteiro
• FLOAT
• booleano
• matrizes
• dicionários

Função de conversão	Tarefa
array	Retornar uma matriz de uma única entrada especificada. Para várias entradas, confira createArray.
base64	Retornar a versão codificada em Base64 de uma cadeia de caracteres.
base64ToBinary	Retornar a versão binária de uma cadeia de caracteres codificada em Base64.
base64ToString	Retornar a versão de cadeia de caracteres de uma cadeia de caracteres codificada em Base64.
binary	Retornar a versão binária de um valor de entrada.
bool	Retornar a versão booliana de um valor de entrada.
coalesce	Retornar 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 de um valor de entrada.
dataUriToBinary	Retornar a versão binária de um URI de dados.
dataUriToString	Retornar a versão de cadeia de caracteres de um URI de dados.
decodeBase64	Retornar a versão de cadeia de caracteres de uma cadeia de caracteres codificada em Base64.
decodeDataUri	Retornar a versão binária de um URI de dados.
decodeUriComponent	Retornar uma cadeia de caracteres que substitui caracteres de escape por versões decodificadas.
encodeUriComponent	Retornar uma cadeia de caracteres que substitui caracteres não seguros para URL por caracteres de escape.
float	Retornar um número de ponto flutuante correspondente a um valor de entrada.
int	Retornar a versão em inteiros de uma cadeia de caracteres.
json	Retornar o objeto ou valor de tipo JSON (JavaScript Object Notation) correspondente a uma cadeia de caracteres ou XML.
cadeia de caracteres	Retornar a versão de cadeia de caracteres de um valor de entrada.
uriComponent	Retornar a versão codificada para URI correspondente a um valor de entrada substituindo caracteres não seguros para URL por caracteres de escape.
uriComponentToBinary	Retornar a versão binária de uma cadeia de caracteres codificada como URI.
uriComponentToString	Retornar a versão de cadeia de caracteres correspondente a uma cadeia de caracteres codificada como URI.
xml	Retornar a versão XML de uma cadeia de caracteres.
xpath	Verificar o XML em busca de nós ou valores correspondentes a uma expressão XPath (Linguagem XPath) e retornar esses nós ou valores.

Funções matemáticas

Essas funções podem ser usadas para qualquer um dos tipos de números: inteiros e floats.

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.
max	Retornar o valor mais alto de um conjunto de números em uma matriz.
min	Retornar o valor mais baixo de um conjunto de números ou de uma matriz.
mod	Retornar o resto da divisão de dois números.
mul	Retornar o produto da multiplicação de dois números.
rand	Retornar um número inteiro aleatório de um intervalo especificado.
range	Retornar uma matriz de inteiros que começa em um inteiro especificado.
sub	Retornar o resultado da subtração do segundo número do primeiro.

Funções de data

Função de data ou hora	Tarefa
addDays	Adicionar um número de dias a um carimbo de data/hora.
addHours	Adicionar um número de horas a um carimbo de data/hora.
addMinutes	Adicionar um número de minutos a um carimbo de data/hora.
addSeconds	Adicionar um número de segundos a um carimbo de data/hora.
addToTime	Adicionar um número de unidades de tempo a um carimbo de data/hora. Confira também getFutureTime.
convertFromUtc	Converter um carimbo de data/hora de UTC (Tempo Universal Coordenado) no fuso horário de destino.
convertTimeZone	Converter um carimbo de data/hora do fuso horário de origem no fuso horário de destino.
convertToUtc	Converter um carimbo de data/hora do fuso horário de origem em UTC (Tempo Universal Coordenado).
dayOfMonth	Retornar o componente de dia do mês de um carimbo de data/hora.
dayOfWeek	Retornar o componente de dia da semana de um carimbo de data/hora.
dayOfYear	Retornar o componente de dia do ano de um carimbo de data/hora.
formatDateTime	Retorna o carimbo de data/hora como uma cadeia de caracteres no formato opcional.
getFutureTime	Retornar o carimbo de data/hora atual mais as unidades de tempo especificadas. Confira também addToTime.
getPastTime	Retornar o carimbo de data/hora atual menos as unidades de tempo especificadas. Confira também subtractFromTime.
startOfDay	Retornar o início do dia de um carimbo de data/hora.
startOfHour	Retornar o início da hora de um carimbo de data/hora.
startOfMonth	Retornar o início do mês de um carimbo de data/hora.
subtractFromTime	Subtrair um número de unidades de tempo de um carimbo de data/hora. Confira também getPastTime.
ticks	Retornar o valor de propriedade ticks de um carimbo de data/hora especificado.
utcNow	Retornar o carimbo de data/hora atual como uma cadeia de caracteres.

Conteúdo relacionado

• Linguagem de expressão