Parâmetros para o Data Factory no Microsoft Fabric
Este documento descreve como usar parâmetros em seus pipelines para o Data Factory na malha.
Como usar parâmetros, expressões e funções em pipelines para o Data Factory na malha
Neste documento, nos concentramos em aprender conceitos fundamentais com vários exemplos para explorar a capacidade de criar pipelines de dados parametrizados no Data Factory in Fabric. A parametrização e as expressões dinâmicas 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.
Conceitos de parâmetros e expressões
Você pode usar parâmetros para passar valores externos para pipelines. 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 de parâmetros na definição podem ser literais ou expressões que são avaliadas em tempo de execução.
As expressões podem aparecer em qualquer lugar em um valor de cadeia de caracteres e sempre gerar outro valor de cadeia de caracteres. Aqui, senha é um parâmetro de pipeline na expressão. Se um valor de parâmetro for uma expressão, o corpo da expressão será extraído removendo o sinal de 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 do parâmetro | 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, a cadeia de caracteres a seguir inclui valores de parâmetro e valores de cadeia de caracteres literal:
"Nome: @{pipeline().parameters.firstName} Sobrenome: @{pipeline().parameters.lastName}"
Usando interpolação de cadeia de caracteres, o resultado é sempre uma cadeia de caracteres. Por exemplo, se você definiu myNumber como e myString comofoo42:
| 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" | 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
Criação e utilização de parâmetros
Para criar parâmetros, selecione o plano de fundo da tela do editor de pipeline e, em seguida, a guia Parâmetros da janela de propriedades na parte inferior. Selecione o botão + Novo para adicionar um novo parâmetro ao pipeline, 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 do pipeline em que o conteúdo dinâmico seja suportado. Neste exemplo, o parâmetro é usado para fornecer dinamicamente o nome de um armazenamento de dados Lakehouse na guia Source das páginas de propriedades de uma atividade de cópia.
A janela Adicionar conteúdo dinâmico é exibida, permitindo especificar qualquer tipo de conteúdo dinâmico, incluindo parâmetros, variáveis do sistema, funções ou variáveis de pipeline. Neste exemplo, o parâmetro definido anteriormente é selecionado e a janela de conteúdo dinâmico é preenchida automaticamente com a expressão correta para fazer referência ao parâmetro.
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 para 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 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 acima para a seguinte expressão:
MYDATA
Usando 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 usadas em uma expressão.
Variáveis de escopo do pipeline
Essas variáveis de sistema podem ser referenciadas em qualquer lugar no pipeline JSON.
| Nome da variável | Description |
|---|---|
| @pipeline().DataFactory | Nome dos dados ou espaço de trabalho Synapse em que o pipeline executado está sendo executado |
| @pipeline().Pipeline | Nome do gasoduto |
| @pipeline().RunId | ID da execução do pipeline específico |
| @pipeline().TriggerId | ID do gatilho que invocou o pipeline |
| @pipeline().TriggerName | Nome do gatilho que invocou o pipeline |
| @pipeline().TriggerTime | Hora da execução do gatilho que invocou o pipeline. Este é o momento em que o gatilho realmente disparou para invocar a execução do pipeline, e pode diferir ligeiramente do tempo agendado do gatilho. |
| @pipeline().GroupId | ID do grupo ao qual o pipeline é executado. |
| @pipeline()?. TriggeredByPipelineName | Nome do pipeline que aciona a execução do pipeline. Aplicável quando a execução do pipeline é acionada por uma atividade ExecutePipeline. Avalie como Nulo quando usado em outras circunstâncias. Observe o ponto de interrogação após @pipeline() |
| @pipeline()?. TriggeredByPipelineRunId | ID de execução do pipeline que dispara a execução do pipeline. Aplicável quando a execução do pipeline é acionada por uma atividade ExecutePipeline. Avalie como Nulo quando usado em outras circunstâncias. Observe o ponto de interrogação após @pipeline() |
Nota
As variáveis do sistema de data/hora relacionadas ao gatilho (nos escopos de pipeline e gatilho) retornam datas UTC no formato ISO 8601, por exemplo, 2017-06-01T22:20:00.4061448Z.
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. |
| ou | 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 | 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 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 | Retorne 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 flutuantes.
| 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. |
| 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. |