Parâmetros para o Data Factory no Microsoft Fabric

Este artigo mostra-lhe como usar parâmetros nos seus pipelines de Data Factory no Fabric para que possa construir fluxos de trabalho flexíveis e reutilizáveis.

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

Esta secção explica-te o básico para criar pipelines parametrizados no Data Factory for Fabric, usando exemplos claros ao longo do processo. Parâmetros e expressões dinâmicas poupam tempo e permitem-lhe construir soluções flexíveis de Extração, Transformação, Carga (ETL) ou Extração, Carga, Transformação (ELT). Reduzem a codificação rígida e permitem reutilizar objetos e processos, o que facilita a manutenção dos pipelines e permite lançar novas funcionalidades mais rapidamente.

Conceitos de parâmetro e expressão

Você pode usar parâmetros para passar valores externos para seus pipelines. Depois de definires um parâmetro, o seu valor mantém-se igual ao longo da corrida. Os parâmetros permitem reutilizar o mesmo pipeline com valores diferentes a cada vez. Podes usar parâmetros isoladamente ou dentro de expressões, com valores que são fixos ou calculados quando o pipeline é executado.

As expressões podem ir a qualquer lugar em um valor de cadeia de caracteres e sempre retornar outro valor de cadeia de caracteres. Por exemplo, se o utilizador usar @password, o pipeline tratará a password como um parâmetro. Se o valor for uma expressão, remova o @ para obter o conteúdo real. Para usar uma cadeia que comece por @, escape dela escrevendo @@. Os exemplos seguintes mostram como isto funciona na prática.

Valor do parâmetro	Result
"parameters"	Os caracteres 'parâmetros' são retornados.
"parameters[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 por meio de interpolação de cadeias de caracteres, em que as expressões são colocadas entre @{ ... }. Por exemplo, a cadeia de caracteres a seguir inclui valores de parâmetro e valores de cadeia de caracteres literal:

Nome próprio: @{pipeline().parameters.firstName} Apelido: @{pipeline().parameters.lastName}

A interpolação de strings devolve sempre uma string. Por exemplo, se definires 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('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 expressão de parâmetros

Criar e usar parâmetros

Para criar parâmetros, selecione o fundo da área de desenho do editor de pipeline e, em seguida, selecione o separador Parâmetros na janela de propriedades, na parte inferior. Selecione + Novo para adicionar um parâmetro ao pipeline e dê-lhe um nome, um tipo de dado e um valor predefinido:

Depois podes usar o parâmetro em qualquer lugar onde o teu pipeline suporte conteúdo dinâmico. Neste exemplo, o parâmetro fornece dinamicamente o nome de um arquivo de dados lakehouse no separador Source das páginas 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, seleciona o parâmetro que definiu anteriormente, e a janela de conteúdo dinâmico preenche-se automaticamente com a expressão correta para a referenciar.

Parametrizar ligações

Para parametrizar ligações em pipelines, utilize o identificador globalmente único (GUID) da ligação que pretende substituir de forma dinâmica.

1. Antes de modificares dinamicamente a ligação no teu pipeline, obtém o GUID da ligação que queres estabelecer.
2. Aceda a Definições>Gerir ligações e gateways.
3. Encontre o nome da ligação e selecione a reticência (...) ao lado.
4. Selecione Definições e copie o ID da Ligação.
5. Cola o GUID num parâmetro string e faz referência a esse parâmetro na tua expressão dinâmica.

Exemplo de expressão complexa

A expressão seguinte refere-se a um subcampo profundo de atividade de saída. Para referenciar um parâmetro de pipeline que é avaliado como um subcampo, utilize 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 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 anterior para a seguinte expressão:

MYDATA

Usar funções e variáveis nas expressões

Você pode chamar funções e usar variáveis dentro de expressões. As seguintes secções fornecem informações sobre as funções que podem ser utilizadas numa expressão.

Variáveis de escopo do pipeline

Pode referenciar estas variáveis do sistema em qualquer parte do pipeline em JSON.

Nome da variável	Description
@pipeline().DataFactory	Nome do espaço de trabalho onde a execução do pipeline está em execução
@pipeline().Pipeline	Nome do gasoduto
@pipeline().RunId	ID da execução específica do pipeline
@pipeline().TriggerId	ID do gatilho que invocou o pipeline
@pipeline().TriggerName	Nome do gatilho que acionou o pipeline
@pipeline().TriggerTime	Momento da execução do gatilho que invocou o pipeline. Este valor é o momento em que o disparador foi efetivamente acionado para iniciar a execução do pipeline e pode diferir ligeiramente da hora agendada do disparador.
@pipeline().GroupId	ID do grupo ao qual a execução do pipeline pertence. No Microsoft Fabric, um grupo é um conjunto de recursos relacionados que pode gerir em conjunto. Os grupos organizam e controlam o acesso aos recursos, o que facilita a gestão de permissões e a monitorização de atividades em múltiplos pipelines.
@pipeline()?. TriggeredByPipelineName	Nome do pipeline que aciona a execução do mesmo. Aplica-se quando uma atividade Executar Pipeline desencadeia a execução do pipeline. Resulta em Null nos outros casos. Note o ponto de interrogação após @pipeline().
@pipeline()?. TriggeredByPipelineRunId	ID de execução do pipeline que o inicia. Aplica-se quando a atividade "Executar Pipeline" aciona a execução do pipeline. Retorna Null noutros casos. Note o ponto de interrogação após @pipeline().

Note

As variáveis de sistema de data/hora associadas ao acionador (tanto ao nível do pipeline como do acionador) devolvem datas em Tempo Universal Coordenado (UTC) no formato ISO 8601, por exemplo, 2017-06-01T22:20:00.4061448Z.

Funções de cadeia de caracteres

Para trabalhar com cadeias, use estas funções de cadeia e também algumas funções de coleção. As funções de cadeia de caracteres funcionam apenas em cadeias de caracteres.

Função String	Task
concat	Combine duas ou mais cadeias de caracteres e devolva a cadeia de caracteres combinada.
endsWith	Verifique se uma cadeia de caracteres termina com a subcadeia especificada.
guid	Gere um identificador globalmente único (GUID) como uma cadeia de caracteres.
indexOf	Retorne a posição inicial da 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.
startsWith	Verifique se uma cadeia de caracteres começa com uma subcadeia de caracteres específica.
substring	Retorne os caracteres de uma cadeia de texto, começando da posição especificada.
toLower	Retornar uma cadeia de caracteres em formato minúsculo.
toUpper	Retornar uma cadeia de caracteres em formato maiúsculo.
trim	Remova os espaços em branco no início e no final de uma cadeia de caracteres e devolva a cadeia atualizada.

Funções de recolha

Para trabalhar com coleções como arrays, strings e dicionários, utilize estas funções de coleção.

Função de recolha	Task
contains	Verifique se uma coleção contém um item específico.
empty	Verifique se uma coleção está vazia.
first	Retorne o primeiro item de uma coleção.
intersection	Retorne uma coleção que contenha apenas os itens comuns entre as coleções especificadas.
join	Retorna uma cadeia de caracteres que contém todos os itens de um array, separados pelo caractere especificado.
last	Devolver o último item de uma coleção.
length	Retornar o número de itens em uma cadeia de caracteres ou matriz.
skip	Remova itens da frente de uma coleção e devolva todos os outros itens.
take	Devolver itens da parte inicial de uma coleção.
union	Devolva uma coleção que tenha todos os itens das coleções especificadas.

Funções lógicas

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

Função de comparação lógica	Task
and	Verifique se todas as expressões são verdadeiras.
equals	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.
if	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 valor.
lessOrEquals	Verifique se o primeiro valor é menor ou igual ao segundo valor.
not	Verifique se uma expressão é falsa.
or	Verifique se pelo menos uma expressão é verdadeira.

Funções de conversão

Use estas funções para converter entre cada um dos tipos nativos da linguagem:

• cadeia (de caracteres)
• número inteiro
• float
• boolean
• arrays
• dictionaries

Função de conversão	Task
array	Retornar um array a partir de uma única entrada especificada. Para várias entradas, veja createArray.
base64	Devolve a versão codificada em base64 de uma string.
base64ToBinary	Devolver a versão binária de uma string codificada em base64.
base64ToString	Retorne a versão da cadeia de caracteres para uma cadeia de caracteres codificada em base64.
binary	Retornar a versão binária para um valor de entrada.
bool	Retorne a versão booleana para um valor fornecido.
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 forma binária de um URI de dados.
dataUriToString	Retornar a versão em string de um URI de dados.
decodeBase64	Retorne a versão da cadeia de caracteres para uma cadeia de caracteres codificada em base64.
decodeDataUri	Retornar a forma binária de 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.
float	Retorna um número de ponto flutuante para um valor de entrada.
int	Retorne a versão inteira de uma string.
json	Retorne o valor ou objeto do tipo JSON (JavaScript Object Notation) para uma cadeia de caracteres ou XML.
string	Devolva a representação em forma de cadeia de caracteres de um valor de entrada.
uriComponent	Retorne a versão codificada por URI de um valor de entrada, substituindo os caracteres não seguros para URL por caracteres de escape.
uriComponentToBinary	Retorne a versão binária de 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 de uma string.
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

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

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 ou de uma matriz.
min	Retorna o valor mais baixo de um conjunto de números ou de uma matriz.
mod	Devolver o resto da divisão de dois números.
mul	Retornar o produto da multiplicação de 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	Retorne o resultado de subtrair o segundo número do primeiro número.

Funções de data

Função de data ou hora	Task
addDays	Adicione um número de dias a um timestamp.
addHours	Adicione um número de horas a um registo de hora.
addMinutes	Adicione um número de minutos a um timestamp.
addSeconds	Adicione um número de segundos a um timestamp.
addToTime	Adicione um número de unidades de tempo a um timestamp. Consulte também getFutureTime.
convertFromUtc	Converta uma marca temporal do Tempo Universal Coordenado (UTC) para o fuso horário de destino.
convertTimeZone	Converta uma marca temporal do fuso horário de origem para o fuso horário de destino.
convertToUtc	Converter um carimbo temporal do fuso horário de origem para o Tempo Universal Coordenado (UTC).
dayOfMonth	Retorne o componente do dia do mês de um timestamp.
dayOfWeek	Obter o componente dia da semana de um timestamp.
dayOfYear	Devolver o componente do 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	Retornar a marca temporal atual somada às unidades de tempo especificadas. Ver também addToTime.
getPastTime	Devolva o timestamp atual subtraindo das unidades de tempo especificadas. Consulte também subtractFromTime.
startOfDay	Retorne o início do dia para um carimbo de data/hora.
startOfHour	Devolver o início da hora para um carimbo de data/hora.
startOfMonth	Devolver o início do mês para um carimbo de data/hora.
subtractFromTime	Subtraia um número de unidades de tempo de uma data/hora. Consulte também getPastTime.
ticks	Retorne o valor da propriedade ticks para um carimbo de data/hora especificado.
utcNow	Retorne o carimbo de data/hora atual como uma cadeia de caracteres.

Conteúdo relacionado

• Linguagem de expressão