How to use parameters, expressions and functions in Azure Data Factory

2025-04-16

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Tip

Try out Data Factory in Microsoft Fabric, an all-in-one analytics solution for enterprises. Microsoft Fabric covers everything from data movement to data science, real-time analytics, business intelligence, and reporting. Learn how to start a new trial for free!

In this document, we will primarily focus on learning fundamental concepts with various examples to explore the ability to create parameterized data pipelines within Azure Data Factory. A parametrização e as expressões dinâmicas são adições tão notáveis ao ADF porque podem poupar uma quantidade enorme de tempo e permitir uma solução ETL (Extrair, Transformar, Carregar) ou ELT (Extrair, Carregar, Transformar) muito mais flexível, o que reduzirá dramaticamente o custo de manutenção da solução e acelerará a implementação de novas funcionalidades em pipelines existentes. Esses ganhos são porque a parametrização minimiza a quantidade de codificação fixa e aumenta o número de objetos e processos reutilizáveis em uma solução.

Interface do Azure Data Factory e parâmetros

Se é novo na utilização de parâmetros no interface de utilizador do Azure Data Factory, por favor reveja Data Factory UI for linked services with parameters e Data Factory UI for metadata driven pipeline with parameters para uma explicação visual.

Conceitos de parâmetro e expressão

You can use parameters to pass external values into pipelines, datasets, linked services, and data flows. Depois de o parâmetro ter sido passado para o recurso, não pode ser alterado. By parameterizing resources, you can reuse them with different values each time. Os parâmetros podem ser utilizados individualmente ou como parte de expressões. JSON values in the definition can be literal or expressions that are evaluated at runtime.

For example:

"name": "value"

"name": "@pipeline().parameters.password"

As expressões podem aparecer em qualquer lugar em um valor de string JSON e sempre resultam em outro valor JSON. Neste caso, password é um parâmetro de pipeline na expressão. If a JSON value is an expression, the body of the expression is extracted by removing the at-sign (@). Se for necessária uma cadeia literal que comece com @, deve ser escapada utilizando @@. Os exemplos seguintes mostram como as expressões são avaliadas.

JSON value	Result
"parameters"	The characters 'parameters' are returned.
parâmetros[1]	Os caracteres 'parameters[1]' são retornados.
"@@"	É retornada uma string de 1 carácter que contém '@'.
" @"	A 2 character string that contains ' @' is returned.

As expressões também podem aparecer dentro de strings, utilizando uma funcionalidade chamada string interpolation, onde as expressões são envolvidas em @{ ... }. Por exemplo: "name" : "First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"

Utilizando a interpolação de strings, o resultado é sempre uma string. Suponha que defini myNumber como 42 e myString como foo:

valor JSON	Resultado
"@pipeline().parameters.myString"	Returns `foo` as a string.
"@{pipeline().parameters.myString}"	Returns `foo` as a string.
"@pipeline().parameters.myNumber"	Returns `42` as a number.
"@{pipeline().parameters.myNumber}"	Retorna `42` como uma cadeia de caracteres.
"Answer is: @{pipeline().parameters.myNumber}"	Returns the string `Answer is: 42`.
"@concat('Answer is: ', string(pipeline().parameters.myNumber))"	Returns the string `Answer is: 42`
"Answer is: @@{pipeline().parameters.myNumber}"	Returns the string `Answer is: @{pipeline().parameters.myNumber}`.

Exemplos de uso de parâmetros em expressões

Exemplo de expressão complexa

O exemplo abaixo mostra um exemplo complexo que faz referência a um subcampo profundo do resultado de atividade. Para referenciar um parâmetro de pipeline que avalia para um subcampo, use a sintaxe [] em vez do operador de ponto (.) (como no caso de 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 automaticamente escapa caracteres no seu conteúdo quando terminar de editar. Por exemplo, o seguinte conteúdo no editor de conteúdo é uma interpolação de string com duas funções de expressão.

{ 
  "type": "@{if(equals(1, 2), 'Blob', 'Table' )}",
  "name": "@{toUpper('myData')}"
}

O editor de conteúdos dinâmicos converte o conteúdo acima na expressão "{ \n \"type\": \"@{if(equals(1, 2), 'Blob', 'Table' )}\",\n \"name\": \"@{toUpper('myData')}\"\n}". O resultado dessa expressão é uma cadeia de caracteres de formato JSON mostrada abaixo.

{
  "type": "Table",
  "name": "MYDATA"
}

A dataset with parameters

In the following example, the BlobDataset takes a parameter named path. O valor é usado para definir um valor para a propriedade folderPath usando a expressão: dataset().path.

{
    "name": "BlobDataset",
    "properties": {
        "type": "AzureBlob",
        "typeProperties": {
            "folderPath": "@dataset().path"
        },
        "linkedServiceName": {
            "referenceName": "AzureStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "parameters": {
            "path": {
                "type": "String"
            }
        }
    }
}

Uma canalização com parâmetros

In the following example, the pipeline takes inputPath and outputPath parameters. O caminho para o conjunto de dados blob parametrizado é definido usando os valores destes parâmetros. The syntax used here is: pipeline().parameters.parametername.

{
    "name": "Adfv2QuickStartPipeline",
    "properties": {
        "activities": [
            {
                "name": "CopyFromBlobToBlob",
                "type": "Copy",
                "inputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.inputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "outputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.outputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "typeProperties": {
                    "source": {
                        "type": "BlobSource"
                    },
                    "sink": {
                        "type": "BlobSink"
                    }
                }
            }
        ],
        "parameters": {
            "inputPath": {
                "type": "String"
            },
            "outputPath": {
                "type": "String"
            }
        }
    }
}

Chamar funções dentro de expressões

Pode chamar funções dentro de expressões. As seguintes secções fornecem informações sobre as funções que podem ser utilizadas numa expressão.

String functions

To work with strings, you can use these string functions and also some collection functions. String functions work only on strings.

Função de cadeia de caracteres	Task
concat	Combine duas ou mais cadeias de caracteres e devolva a cadeia de caracteres combinada.
endsWith	Verifique se uma string termina com a substring especificada.
guid	Gere um identificador globalmente único (GUID) como uma cadeia de caracteres.
indexOf	Devolver a posição inicial de uma substring.
lastIndexOf	Return the starting position for the last occurrence of a substring.
replace	Replace a substring with the specified string, and return the updated string.
split	Return an array that contains substrings, separated by commas, from a larger string based on a specified delimiter character in the original string.
startsWith	Verifique se uma string começa com uma substring específica.
substring	Retorne os caracteres de uma cadeia de texto, começando da posição especificada.
toLower	Devolve uma string em minúsculas.
toUpper	Retornar uma string em maiúsculas.
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 coleção

Para trabalhar com coleções, geralmente arrays, strings, e por vezes, dicionários, pode utilizar estas funções de coleção.

Função de coleta	Tarefa
contains	Verifique se uma coleção contém um item específico.
empty	Verifique se uma coleção está vazia.
primeiro	Retorne o primeiro item de uma coleção.
interseção	Retorne uma coleção que contenha apenas os itens comuns entre as coleções especificadas.
join	Return a string that has all the items from an array, separated by the specified character.
último	Devolver o último item de uma coleção.
length	Return the number of items in a string or array.
skip	Remova itens da frente de uma coleção e devolva todos os outros itens.
take	Return items from the front of a collection.
union	Devolva uma coleção que tenha todos os itens das coleções especificadas.

Logical functions

These functions are useful inside conditions, they can be used to evaluate any type of logic.

Logical comparison function	Task
and	Verifique se todas as expressões são verdadeiras.
igual a	Verifique se ambos os valores são equivalentes.
maior	Check whether the first value is greater than the second value.
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.
menos	Verifique se o primeiro valor é menor que o segundo valor.
lessOrEquals	Check whether the first value is less than or equal to the second value.
not	Verifique se uma expressão é falsa.
or	Check whether at least one expression is true.

Conversion functions

These functions are used to convert between each of the native types in the language:

string
integer
flutuar
boolean
arrays
dictionaries

Conversion function	Tarefa
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	Return the string version for a base64-encoded string.
binary	Return the binary version for an input value.
bool	Return the Boolean version for an input value.
coalesce	Devolva o primeiro valor não nulo de um ou mais parâmetros.
createArray	Return an array from multiple inputs.
dataUri	Return the data URI for an input value.
dataUriToBinary	Retorne a versão binária para um URI de dados.
dataUriToString	Devolve a versão em cadeia para um URI de dados.
decodeBase64	Devolve a versão em string para uma string codificada em base64.
decodeDataUri	Devolva a versão binária de um URI de dados.
decodeUriComponent	Retorne uma string que substitua os caracteres de escape por versões decodificadas.
encodeUriComponent	Devolve uma cadeia que substitui os caracteres inseguros para URLs por caracteres de escape.
float	Devolve um número de ponto flutuante para um valor de entrada.
int	Retorne a versão inteira de uma string.
json	Devolva o valor ou objeto do tipo JavaScript Object Notation (JSON) para uma string ou XML.
string	Retorne a versão em cadeia para 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	Devolver a versão de string para uma string codificada em URI.
xml	Devolva a versão XML de uma cadeia de caracteres.
xpath	Check XML for nodes or values that match an XPath (XML Path Language) expression, and return the matching nodes or values.

Funções Matemáticas

Estas funções podem ser usadas para ambos os tipos de números: inteiros e pontos flutuantes.

Math function	Tarefa
add	Devolver o resultado da adição de dois números.
div	Return the result from dividing two numbers.
max	Return the highest value from a set of numbers or an array.
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	Devolva um número inteiro aleatório de um intervalo especificado.
intervalo	Devolva um array de números inteiros que comece 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	Tarefa
addDays	Adicione um número de dias a um timestamp.
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 carimbo de data/hora.
addToTime	Adicione um número de unidades de tempo a um carimbo de data/hora. See also 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	Convert a timestamp from the source time zone to Universal Time Coordinated (UTC).
dayOfMonth	Return the day of the month component from a timestamp.
dayOfWeek	Return the day of the week component from a timestamp.
dayOfYear	Devolver o componente do dia do ano de um carimbo de data/hora.
formatDateTime	Devolva o carimbo de data/hora como uma cadeia de caracteres em formato opcional.
getFutureTime	Retornar a marca temporal atual somada às unidades de tempo especificadas. Ver também addToTime.
getPastTime	Devolve o carimbo de data/hora atual menos as unidades de tempo especificadas. See also subtractFromTime.
startOfDay	Return the start of the day for a timestamp.
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	Subtract a number of time units from a timestamp. Consulte também getPastTime.
ticks	Return the `ticks` property value for a specified timestamp.
utcNow	Return the current timestamp as a string.

Detailed examples for practice

Detalhada cópia de pipelina de Azure Data Factory com parâmetros

This Azure Data Factory copy pipeline parameter passing tutorial walks you through how to pass parameters between a pipeline and activity as well as between the activities.

Mapeamento Detalhado do pipeline de fluxo de dados com parâmetros

Please follow Mapping data flow with parameters for comprehensive example on how to use parameters in data flow.

Detailed Metadata driven pipeline with parameters

Please follow Metadata driven pipeline with parameters to learn more about how to use parameters to design metadata driven pipelines. Este é um caso de uso popular para parâmetros.

Para uma lista de variáveis do sistema que pode usar em expressões, consulte Variáveis do sistema.