Como usar os parâmetros, expressões e funções no Azure Data Factory
APLICA-SE A:
Azure Data Factory Azure Synapse Analytics
Dica
Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange desde movimentação de dados até ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma avaliação gratuita!
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 são complementos notáveis ao ADF (Azure Data Factory), pois elas podem economizar bastante tempo e permitir Extrair, Transformar e Carregar (ETL) de uma forma mais flexível, ou permitir uma solução de extração, transformação, carregamento (ETL), o que reduzirá drasticamente o custo da manutenção da solução e acelerará a implementação de novos recursos nas 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.
Interface do usuário e parâmetros do Azure Data Factory
Se você não tiver familiaridade com o Azure Data Factory e não souber usar os parâmetros na interface do usuário do ADF, examine a Interface do usuário do Data Factory para serviços vinculados com parâmetros e a Interface do usuário do Data Factory para pipelines controlados por metadados com parâmetros para obter acesso a uma explicação visual.
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 JSON na definição podem ser literais ou expressões que são avaliadas no runtime.
Por exemplo:
"name": "value"
ou
"name": "@pipeline().parameters.password"
As expressões podem aparecer em qualquer lugar em um valor de cadeia de caracteres JSON e sempre retornam outro valor JSON. Aqui, a senha é um parâmetro de pipeline na expressão. Se um valor JSON for uma expressão, o corpo da expressão será extraído removendo a 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 JSON | Result |
|---|---|
| "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: "name" : "First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"
Usando interpolação de cadeia de caracteres, o resultado é sempre uma cadeia de caracteres. Digamos que defini myNumber como 42 e myString como foo:
| Valor JSON | 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 como usar 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 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.
{
"type": "@{if(equals(1, 2), 'Blob', 'Table' )}",
"name": "@{toUpper('myData')}"
}
O editor de conteúdo dinâmico converte o conteúdo acima em 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, como mostra o exemplo abaixo.
{
"type": "Table",
"name": "MYDATA"
}
Um conjunto de dados com parâmetros
No exemplo a seguir, o BlobDataset usa um parâmetro denominado path. Seu valor é usado para definir um valor para a propriedade folderPath usando as expressões: dataset().path.
{
"name": "BlobDataset",
"properties": {
"type": "AzureBlob",
"typeProperties": {
"folderPath": "@dataset().path"
},
"linkedServiceName": {
"referenceName": "AzureStorageLinkedService",
"type": "LinkedServiceReference"
},
"parameters": {
"path": {
"type": "String"
}
}
}
}
Um pipeline com parâmetros
No exemplo a seguir, o pipeline usa os parâmetros inputPath e outputPath. O path para o conjunto de dados de blob com parâmetros é definido usando os valores desses parâmetros. A sintaxe usada aqui é: 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"
}
}
}
}
Chamando funções dentro de expressões
Você pode chamar funções dentro de expressões. As seções a seguir fornecem informações sobre as funções que podem ser usados em uma expressão.
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. |
Exemplos detalhados para a prática
Pipeline de cópia do Azure Data Factory detalhado com parâmetros
Este Tutorial instrui você a passar parâmetros de pipeline de cópia do Azure Data Factory entre um pipeline e uma atividade, bem como entre as atividades.
Pipeline de fluxo de dados de mapeamento detalhado com parâmetros
Acesse o fluxo de dados de mapeamento com parâmetros para ver um exemplo completo de como usar parâmetros no fluxo de dados.
Pipeline controlado por metadados detalhado com parâmetros
Acesse o pipeline controlado por metadados com parâmetros para saber mais sobre como usar parâmetros para criar pipelines controlados por metadados. Esse é um caso comum de uso para parâmetros.
Conteúdo relacionado
Para obter uma lista de variáveis de sistema que você pode usar em expressões, consulte Variáveis do sistema.