Parâmetros do Data Factory no Microsoft Fabric

Este artigo mostra como usar parâmetros em seus pipelines do Data Factory em Fabric para que você possa criar fluxos de trabalho flexíveis e reutilizáveis.

Usar parâmetros, expressões e funções em pipelines do Data Factory

Esta seção orienta você pelas noções básicas de criação de pipelines parametrizados no Data Factory para Fabric, usando exemplos claros ao longo do caminho. Parâmetros e expressões dinâmicas economizam tempo e permitem criar soluções flexíveis de extração, transformação e carregamento (ETL) ou de extração, carregamento e transformação (ELT). Eles reduzem a codificação rígida e permitem reutilizar objetos e processos, o que facilita a manutenção dos pipelines e permite que você envie novos recursos mais rapidamente.

Conceitos de parâmetro e expressão

Você pode usar parâmetros para passar valores externos para seus pipelines. Depois de definir um parâmetro, seu valor permanecerá o mesmo durante toda a execução. Os parâmetros permitem reutilizar o mesmo pipeline com valores diferentes a cada vez. Você pode usar parâmetros por conta própria ou dentro de expressões, com valores fixos ou calculados quando o pipeline é executado.

As expressões podem ir para qualquer lugar em um valor de cadeia de caracteres e sempre retornar outro valor de cadeia de caracteres. Por exemplo, se você usar @password, o pipeline tratará a senha como um parâmetro. Se o valor for uma expressão, remova o @ para obter o conteúdo real. Para usar uma cadeia de caracteres que começa com @, escape-a digitando @@. Os exemplos a seguir mostram como isso funciona na prática.

Valor do parâmetro	Result
"parameters"	Os “parâmetros” dos caracteres são retornados.
"parameters[1]"	Os caracteres 'parâmetros[1]' 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.

Expressões também podem aparecer dentro de strings por meio da interpolação de strings, em que você delimita expressões com @{ ... }. Por exemplo, a cadeia de caracteres a seguir inclui valores de parâmetro e valores de cadeia de caracteres literais:

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

A interpolação de cadeia de caracteres sempre retorna uma cadeia de caracteres. Por exemplo, se você definir myNumber como 42 e myString como foo:

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"	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 expressão de parâmetro

Criar e usar parâmetros

Para criar parâmetros, selecione o plano de fundo da área de desenho do editor de pipeline e, em seguida, selecione a guia Parâmetros da janela de propriedades na parte inferior. Selecione + Novo para adicionar um parâmetro ao pipeline e 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 em que seu pipeline dê suporte a conteúdo dinâmico. Neste exemplo, o parâmetro fornece dinamicamente o nome de um repositório de dados lakehouse na guia Origem da página de propriedades de uma atividade de Cópia.

A janela Adicionar conteúdo dinâmico é aberta. Use-o para especificar qualquer tipo de conteúdo dinâmico, incluindo parâmetros, variáveis do sistema, funções ou variáveis de pipeline. Neste exemplo, você seleciona o parâmetro definido anteriormente e a janela de conteúdo dinâmico preenche automaticamente com a expressão correta para referenciá-lo.

Parametrizar conexões

Para parametrizar conexões em pipelines, use o GUID (identificador global exclusivo) da conexão que você deseja substituir dinamicamente.

1. Antes de modificar dinamicamente a conexão em seu pipeline, obtenha o GUID da conexão que você deseja definir.
2. Vá para Configurações>Gerenciar conexões e gateways.
3. Localize o nome da conexão e selecione as reticências (...) ao lado dela.
4. Selecione Configurações e copie a ID da Conexão.
5. Cole o GUID em um parâmetro de cadeia de caracteres e referencie esse parâmetro em sua expressão dinâmica.

Exemplo de expressão complexa

A expressão a seguir 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 de ponto (.), como em 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 remove automaticamente os caracteres do seu conteúdo ao finalizar a edição. 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 anterior para a seguinte expressão:

MYDATA

Usar 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 de pipeline

Você pode referenciar essas variáveis de sistema em qualquer lugar no JSON do pipeline.

Nome da Variável	Description
@pipeline().DataFactory	Nome do espaço de trabalho em que a execução do pipeline está ocorrendo
@pipeline().Pipeline	Nome da linha
@pipeline().RunId	ID da execução específica do pipeline
@pipeline().TriggerId	ID do gatilho que invocou o pipeline
@pipeline().TriggerName	Nome do acionador que invocou o pipeline
@pipeline().TriggerTime	Tempo da execução do gatilho que invocou o pipeline. Esse valor é o horário em que o gatilho foi realmente acionado para invocar a execução do pipeline, e pode diferir ligeiramente do horário agendado do gatilho.
@pipeline().GroupId	ID do grupo ao qual a execução do pipeline pertence. Em Microsoft Fabric, um grupo é uma coleção de recursos relacionados que você gerencia juntos. Os grupos organizam e controlam o acesso aos recursos, o que facilita o gerenciamento de permissões e o monitoramento de atividades em vários pipelines.
@pipeline()?.TriggeredByPipelineName	Nome do pipeline que aciona a execução do pipeline. Aplica-se quando a atividade Executar Pipeline dispara a execução do pipeline. Avalia como Nulo em outros casos. Observe o ponto de interrogação após @pipeline().
@pipeline()?.TriggeredByPipelineRunId	ID de execução do pipeline que aciona a execução do fluxo de trabalho do pipeline. Aplica-se quando uma atividade Execute Pipeline aciona a execução de um pipeline. É avaliado como Nulo nos demais casos. Observe o ponto de interrogação após @pipeline().

Note

As variáveis de sistema de data/hora relacionadas a trigger (tanto no escopo do pipeline quanto no do trigger) retornam datas UTC (Tempo Universal Coordenado) no formato ISO 8601, por exemplo, 2017-06-01T22:20:00.4061448Z.

Funções de cadeia de caracteres

Para trabalhar com cadeias de caracteres, use essas funções de cadeia de caracteres e também algumas funções de coleção. Funções de cadeia de caracteres só funcionam com cadeias de caracteres.

Função de string	Task
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.
replace	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.
trim	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 como matrizes, cadeias de caracteres e dicionários, use essas funções de coleção.

Função de Coleção	Task
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

Use essas funções dentro das condições para avaliar qualquer tipo de lógica.

Função de comparação lógica	Task
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

Use essas funções para converter entre cada um dos tipos nativos no idioma:

• cadeia
• inteiro
• derivar
• boolean
• arrays
• dictionaries

Função de conversão	Task
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.
string	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ática

Use essas funções com ambos os tipos de números: inteiros e floats.

Função matemática	Task
add	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	Task
addDays	Adicionar um número de dias a um marca temporal.
addHours	Adicione um número de horas a um carimbo de data/hora.
addMinutes	Adicione um número de minutos a um timestamp.
addSeconds	Adicione um número de segundos a um timestamp.
addToTime	Adicione várias unidades de tempo a um carimbo de data e hora. Confira também getFutureTime.
convertFromUtc	Converta um carimbo de data/hora de UTC (Tempo Universal Coordenado) para o 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	Converta 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 em um 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