Como usar parâmetros, expressões e funções no Azure Data Factory
APLICA-SE A:
Azure Data Factory Azure Synapse Analytics
Gorjeta
Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange tudo, desde a movimentação de dados até ciência de dados, análises em tempo real, business intelligence e relatórios. Saiba como iniciar uma nova avaliação gratuitamente!
Neste documento, vamos nos concentrar principalmente em aprender conceitos fundamentais com vários exemplos para explorar a capacidade de criar pipelines de dados parametrizados no Azure Data Factory. Parametrização e expressões dinâmicas são adições notáveis ao ADF porque podem economizar uma enorme quantidade de tempo e permitir uma solução muito mais flexível de Extrair, Transformar, Carregar (ETL) ou Extrair, Carregar, Transformar (ELT), o que reduzirá drasticamente o custo de manutenção da solução e acelerará a implementação de novos recursos em pipelines existentes. Esses ganhos ocorrem porque a parametrização minimiza 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ê for novo no uso de parâmetros do Azure Data Factory na interface do usuário do ADF, consulte 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 pipeline controlado por metadados com parâmetros para obter uma explicação visual.
Conceitos de parâmetros e expressões
Você pode usar parâmetros para passar valores externos para pipelines, conjuntos de dados, serviços vinculados e fluxos de dados. Uma vez que o parâmetro tenha sido passado para o recurso, ele não pode ser alterado. Ao parametrizar recursos, você pode reutilizá-los com valores diferentes a cada vez. 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 em tempo de execução.
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 resultam em outro valor JSON. Aqui, 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 o at-sign (@). Se for necessária uma cadeia de caracteres literal que comece com @, ela deverá ser escapada usando @@. Os exemplos a seguir mostram como as expressões são avaliadas.
| Valor JSON | Result |
|---|---|
| "parâmetros" | Os caracteres 'parâmetros' são retornados. |
| "parâmetros[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, usando um recurso chamado interpolação de cadeia de caracteres, onde as expressões sã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 myNumber defini como e myString como 42foo:
| 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" | Devolve 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 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 da saída da atividade. Para fazer referência a um parâmetro de pipeline que é avaliado a um subcampo, use a sintaxe [] em vez do operador dot(.) (como no caso do 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 escapa automaticamente dos caracteres do seu conteúdo quando você termina a edição. 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 mostrada abaixo.
{
"type": "Table",
"name": "MYDATA"
}
Um conjunto de dados com parâmetros
No exemplo a seguir, o BlobDataset usa um parâmetro chamado path. Seu 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"
}
}
}
}
Um pipeline com parâmetros
No exemplo a seguir, o pipeline usa os parâmetros inputPath e outputPath. O caminho para o conjunto de dados de blob parametrizado é definido usando valores desses parâmetros. A sintaxe utilizada 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 usadas em uma expressão.
Funções de cadeia
Para trabalhar com cadeias de caracteres, você pode usar essas funções de cadeia de caracteres e também algumas funções de coleção. As funções de cadeia de caracteres funcionam apenas em cadeias de caracteres.
| Função da cadeia de carateres | Tarefa |
|---|---|
| concat | Combine duas ou mais cadeias de caracteres e retorne a cadeia combinada. |
| termina com | Verifique se uma cadeia de caracteres termina com a subcadeia especificada. |
| GUID | Gere um identificador global exclusivo (GUID) como uma cadeia de caracteres. |
| indexOf | Retornar a posição inicial de uma 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. |
| começaCom | Verifique se uma cadeia de caracteres começa com uma subcadeia de caracteres específica. |
| substring | Retorna caracteres de uma cadeia de caracteres, começando a partir da posição especificada. |
| paraMais baixo | Retornar uma cadeia de caracteres em formato minúsculo. |
| toUpper | Retornar uma cadeia de caracteres em formato maiúsculo. |
| guarnição | Remova o espaço em branco à esquerda e à direita de uma cadeia de caracteres e retorne a cadeia de caracteres atualizada. |
Funções de recolha
Para trabalhar com coleções, geralmente matrizes, cadeias de caracteres e, às vezes, dicionários, você pode usar essas funções de coleção.
| Função de recolha | Tarefa |
|---|---|
| contém: | Verifique se uma coleção tem um item específico. |
| empty | Verifique se uma coleção está vazia. |
| primeiro | Retornar o primeiro item de uma coleção. |
| intersecção | Retornar uma coleção que tenha apenas os itens comuns nas coleções especificadas. |
| aderir | Retorna uma cadeia de caracteres que tem todos os itens de uma matriz, separados pelo caractere especificado. |
| último | Retornar o último item de uma coleção. |
| length | Retornar o número de itens em uma cadeia de caracteres ou matriz. |
| pular | Remova itens da frente de uma coleção e devolva todos os outros itens. |
| tomar | Devolver itens da frente de uma coleção. |
| União | Retornar uma coleção que tenha todos os itens das coleções especificadas. |
Funções lógicas
Estas funções são úteis dentro das condições, elas podem ser usadas para avaliar qualquer tipo de lógica.
| Função de comparação lógica | Tarefa |
|---|---|
| and | Verifique se todas as expressões são verdadeiras. |
| igual a | 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. |
| se | 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. |
| lessOrEquals | Verifique se o primeiro valor é menor ou igual ao segundo valor. |
| não | Verifique se uma expressão é falsa. |
| or | Verifique 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 na linguagem:
- string
- integer
- flutuante
- boolean
- matrizes
- dicionários
| Função de conversão | Tarefa |
|---|---|
| matriz | Retornar uma matriz de uma única entrada especificada. Para várias entradas, consulte createArray. |
| base64 | Retorne a versão codificada em base64 para uma cadeia de caracteres. |
| base64ToBinary | Retorne a versão binária para uma cadeia de caracteres codificada em base64. |
| base64ToString | Retorne a versão da cadeia de caracteres para uma cadeia de caracteres codificada em base64. |
| binário | Retornar a versão binária para um valor de entrada. |
| Bool | Retorne a versão booleana para um valor de entrada. |
| coalesce | Retorne 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 versão binária para um URI de dados. |
| dataUriToString | Retornar a versão da cadeia de caracteres para um URI de dados. |
| decodeBase64 | Retorne a versão da cadeia de caracteres para uma cadeia de caracteres codificada em base64. |
| decodeDataUri | Retornar a versão binária para 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. |
| flutuar | Retorna um número de ponto flutuante para um valor de entrada. |
| Int | Retorne a versão inteira para uma cadeia de caracteres. |
| Json | Retorne o valor ou objeto do tipo JSON (JavaScript Object Notation) para uma cadeia de caracteres ou XML. |
| string | Retorne a versão da cadeia de caracteres para um valor de entrada. |
| uriComponent | Retorne a versão codificada por URI para um valor de entrada substituindo caracteres não seguros de URL por caracteres de escape. |
| uriComponentToBinary | Retornar a versão binária para 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 para uma cadeia de caracteres. |
| 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
Estas funções podem ser usadas para qualquer tipo de números: inteiros e flutuadores.
| Função matemática | Tarefa |
|---|---|
| adicionar | Retornar o resultado da adição de dois números. |
| div | Retorne o resultado da divisão de dois números. |
| máx. | Retornar o valor mais alto de um conjunto de números ou de uma matriz. |
| min | Retornar o menor valor de um conjunto de números ou de uma matriz. |
| Mod | Retorne o restante da divisão de dois números. |
| Mul | Devolva o produto multiplicando 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 | Retornar o resultado subtraindo o segundo número do primeiro número. |
Funções de data
| Função de data ou hora | Tarefa |
|---|---|
| addDias | Adicione um número de dias a um carimbo de data/hora. |
| addHours | Adicione um número de horas a um carimbo de data/hora. |
| adicionarMinutos | Adicione alguns minutos a um carimbo de data/hora. |
| addSeconds | Adicione alguns segundos a um carimbo de data/hora. |
| addToTime | Adicione várias unidades de tempo a um carimbo de data/hora. Consulte também getFutureTime. |
| convertFromUtc | Converta um carimbo de data/hora de Universal Time Coordinated (UTC) para o fuso horário de destino. |
| convertTimeZone | Converta um carimbo de data/hora do fuso horário de origem para o fuso horário de destino. |
| convertToUtc | Converta um carimbo de data/hora do fuso horário de origem em Universal Time Coordinated (UTC). |
| diadeMês | Retornar o componente dia do mês de um carimbo de data/hora. |
| diadesemana | Retornar o componente dia da semana de um carimbo de data/hora. |
| diadeano | Retornar o componente 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 | Retorne o carimbo de data/hora atual mais as unidades de tempo especificadas. Consulte também addToTime. |
| getPastTime | Retorne o carimbo de data/hora atual menos as unidades de tempo especificadas. Consulte também subtractFromTime. |
| inícioOfDay | Retorne o início do dia para um carimbo de data/hora. |
| iníciodehora | Retorne o início da hora para um carimbo de data/hora. |
| iníciodemês | Retorne o início do mês para um carimbo de data/hora. |
| subtrairFromTime | Subtraia várias unidades de tempo de um carimbo de data/hora. Consulte também getPastTime. |
| carrapatos | Retornar o valor da propriedade para um carimbo ticks de data/hora especificado. |
| utcAgora | Retorne o carimbo de data/hora atual como uma cadeia de caracteres. |
Exemplos pormenorizados de prática
Pipeline de cópia detalhado do Azure Data Factory com parâmetros
Este tutorial de passagem de parâmetros de pipeline de cópia do Azure Data Factory orienta você sobre como passar parâmetros entre um pipeline e uma atividade, bem como entre as atividades.
Pipeline de fluxo de dados de mapeamento detalhado com parâmetros
Siga Mapeando fluxo de dados com parâmetros para obter um exemplo abrangente sobre como usar parâmetros no fluxo de dados.
Pipeline detalhado orientado por metadados com parâmetros
Siga o pipeline controlado por metadados com parâmetros para saber mais sobre como usar parâmetros para projetar pipelines orientados por metadados. Este é um caso de uso popular para parâmetros.
Conteúdos relacionados
Para obter uma lista de variáveis de sistema que você pode usar em expressões, consulte Variáveis de sistema.