Crie mapas para transformar dados para fluxos de trabalho no Azure Logic Apps com Visual Studio Code

Aplica-se a: Aplicativos Lógicos do Azure (Padrão)

Ao trocar mensagens que usam diferentes formatos XML ou JSON em um fluxo de trabalho de aplicativo lógico, você precisa especificar como transformar ou converter os dados do formato de origem para o formato de destino, por exemplo, entre documentos XML ou entre documentos JSON. Essa tarefa é importante, especialmente quando você tem lacunas entre as estruturas de dados nos esquemas de origem e de destino. Um esquema descreve os elementos de dados, atributos e tipos de dados em um documento XML ou JSON.

Para definir transformações entre estruturas de dados e preencher lacunas, você pode criar um mapa (arquivo .xslt) que especifica as relações entre os elementos de dados nos esquemas de origem e destino. Você pode criar ou editar visualmente um mapa usando o Visual Studio Code com a extensão Azure Logic Apps (Standard) no contexto de um projeto de aplicativo lógico Standard. A ferramenta Mapeador de Dados fornece uma experiência unificada para mapeamento e transformação usando gestos de arrastar e soltar, funções pré-criadas para criar expressões e uma maneira de testar mapas manualmente antes de usá-los em seus fluxos de trabalho.

Depois de criar seu mapa, você pode chamar diretamente esse mapa de um fluxo de trabalho em seu projeto de aplicativo lógico ou de um fluxo de trabalho de aplicativo lógico padrão no portal do Azure. Para esta tarefa, pode usar a ação Operações do Data Mapper denominada Transformar utilizando XSLT do Data Mapper no seu fluxo de trabalho.

Este guia de instruções mostra como criar um mapa de dados vazio, escolher seus esquemas de origem e destino, criar vários tipos de mapeamentos entre elementos de esquema, salvar e testar seu mapa e, em seguida, chamar o mapa de um fluxo de trabalho em seu projeto de aplicativo lógico.

Limitações e problemas conhecidos

  • Atualmente, o Mapeador de Dados está disponível apenas no Visual Studio Code, não no portal do Azure, e somente em projetos de aplicativo lógico padrão, não em projetos de aplicativo lógico de consumo.

    A experiência de front-end do Mapeador de Dados está disponível como código aberto no repositório público do GitHub para a equipe de Aplicativos Lógicos do Azure. Para obter mais informações, consulte os seguintes recursos:

  • Atualmente, o Mapeador de Dados funciona apenas no Visual Studio Code em execução em sistemas operacionais Windows.

  • Atualmente, o Mapeador de Dados não oferece suporte a esquemas que usam o formato de arquivo de valores separados por vírgulas (.csv).

  • O painel Código no Mapeador de Dados é, de momento, apenas de leitura.

  • Na superfície do mapeador de dados, o layout e as posições das funções são móveis, mas os nós do esquema são estáticos.

  • A função Filtro processa corretamente as condições numéricas entre aspas duplas, por exemplo, ">=10". No entanto, essa função atualmente não se comporta consistentemente para comparações de cadeia de caracteres, como uma verificação se o nome de um item é "= 'Pen'".

  • Ao criar um mapeamento entre os elementos do array principal nos esquemas de origem e de destino, o mapeador adiciona automaticamente um ciclo para percorrer os elementos dos itens do array. No entanto, você ainda deve criar explicitamente mapeamentos entre os elementos de item da matriz de origem e de destino.

  • Para invocar mapas criados com o Mapeador de Dados, só pode utilizar a ação Operações do Mapeador de Dados com o nome Transformar com XSLT do Mapeador de Dados. Para mapas criados por qualquer outra ferramenta, use a ação Operações XML chamada Transformar XML.

  • Para usar os mapas que criar com o Data Mapper com fluxos de trabalho no portal do Azure, tem de adicioná-los diretamente ao recurso da aplicação lógica Standard.

Para bugs ou solicitações de recursos sem bloqueio, abra um item com o rótulo Mapeador de Dados no repositório GitHub para a equipe de Aplicativos Lógicos do Azure.

Pré-requisitos

  • Uma conta Azure e uma assinatura. Se não tiver uma subscrição, inscreva-se numa conta gratuita do Azure.

  • Visual Studio Code e a extensão Azure Logic Apps (Standard) para criar fluxos de trabalho de aplicações lógicas Standard.

    Nota

    A extensão do Mapeador de Dados anteriormente separada agora é mesclada com a extensão Aplicativos Lógicos do Azure (Padrão). Para evitar conflitos, qualquer versão existente da extensão do Mapeador de Dados é removida quando você instala ou atualiza a extensão Aplicativos Lógicos do Azure (Padrão). Após a instalação ou atualização da extensão, reinicie o Visual Studio Code.

  • Os arquivos de esquema de origem e destino que descrevem os tipos de dados a serem transformados. Esses arquivos podem ter os seguintes formatos:

    • Um arquivo de definição de esquema XML com a extensão de arquivo .xsd

    • Um arquivo JavaScript Object Notation com a extensão de arquivo .json

  • Um projeto de aplicação lógica Standard que inclui um fluxo de trabalho com ou sem estado e, no mínimo, um acionador. Se você não tiver um projeto, siga estas etapas no Visual Studio Code:

    1. Conecte-se à sua conta do Azure, se ainda não o fez.

    2. Crie uma pasta local, um espaço de trabalho e um projeto de aplicação lógica Standard e um fluxo de trabalho com estado ou sem estado. Durante a criação do fluxo de trabalho, selecione Abrir na janela atual.

  • Exemplo de dados de entrada se quiser testar o mapa e verificar se a transformação funciona como esperado.

Criar um mapa de dados

  1. No Visual Studio Code, abra a pasta para seu projeto de aplicativo lógico padrão.

  2. No menu esquerdo do Visual Studio Code, selecione o ícone do Azure .

  3. Na janela do Azure, em Mapeador de Dados, selecione Criar mapa de dados.

    A captura de tela mostra o Visual Studio Code com a janela do Azure e o botão selecionado para Criar mapa de dados.

    Na barra de título do Visual Studio Code, uma caixa de prompt é aberta para que você possa fornecer um nome para seu mapa.

  4. Na caixa de prompt, digite um nome para o mapa.

    Neste guia, estes passos utilizam o nome Example-data-map.

    A captura de tela mostra a caixa de prompt e o nome do mapa de dados de exemplo.

    O Mapeador de Dados cria e abre um mapa de dados em branco.

  5. Escolha seus esquemas de origem e destino seguindo estas etapas:

    1. No painel Origem, selecione Adicionar nova>Procurar para localizar e carregar o esquema de origem.

      A captura de tela mostra o Mapeador de Dados e o painel Origem com as opções selecionadas para Adicionar novo e Procurar.

      Depois de adicionar o esquema de origem, o painel Source passa a apresentar o elemento XML "nodes" dos tipos de dados no esquema de origem, por exemplo:

      A captura de tela mostra o painel Código-fonte preenchido com nós de elemento XML do esquema de origem.

    2. No painel Destino, selecione Adicionar novo>Procurar para procurar e carregar o esquema de destino.

      A captura de tela mostra o Mapeador de Dados e o painel Destino com as opções selecionadas para Adicionar novo e Procurar.

      Depois de adicionar o esquema de destino, o painel Destino passa a apresentar o elemento XML "nodes" para os tipos de dados do esquema de destino, por exemplo:

      A captura de tela mostra o painel de destino preenchido com nós de elemento XML do esquema de origem.

Gorjeta

Se tiver problemas ao carregar os seus esquemas, pode adicionar os seus ficheiros de esquema de origem e de destino à pasta local Artifacts/Schemas do projeto da sua aplicação lógica. Nesse cenário, para especificar seu esquema de origem e destino no Mapeador de Dados, nos painéis Origem e Destino, abra a lista Selecionar existente, em vez de usar Adicionar novo, e selecione seu esquema.

Tipos de dados de esquema

A tabela a seguir descreve os possíveis tipos de dados que podem aparecer em um esquema:

Símbolo Tipo Mais informações
Ícone que representa um tipo de dados de matriz. Complexo (vetor) Contém itens ou nós de itens repetidos.

Um elemento de matriz também exibe o seguinte ponto de conexão:

Ícone para o ponto de conexão do elemento de matriz.
Ícone que representa um tipo de dados Bool. Bool Verdadeiro ou falso apenas
Ícone que representa um tipo de dados complexo. Complexo Um objeto XML com propriedades filhas, semelhante ao tipo JSON Object
Ícone que representa um tipo de dados DateTime. Data e Hora
Ícone que representa um tipo de dados decimal. Decimal
Ícone que representa um tipo de dados Inteiro. Número inteiro Apenas números inteiros
Ícone que representa um tipo de dados String. Cordão

Criar um mapeamento direto entre elementos

Para especificar uma transformação direta entre elementos que têm o mesmo tipo nos esquemas de origem e destino, siga estas etapas:

  1. Para ver o que acontece no código enquanto você cria o mapeamento, no canto superior direito do mapeador, selecione Exibir código.

  2. Na superfície do mapeador, no painel Origem , localize o elemento de origem que você deseja mapear.

    • Por padrão, os elementos pai são expandidos automaticamente para mostrar seus filhos.

    • Este exemplo inicia o mapeamento a partir do elemento de origem, mas você pode optar por iniciar o mapeamento a partir do elemento de destino.

  3. Mova o ponteiro do rato sobre o círculo ao lado do nome do elemento de origem até que o ponteiro mude para um sinal de mais (+).

    Este exemplo cria um mapeamento a partir do elemento de origem Employee ID .

    A captura de tela mostra o Mapeador de Dados com o ponteiro sobre o elemento de origem.

  4. Arraste e desenhe uma linha para que o elemento de origem se conecte ao círculo do elemento de destino no painel Destino .

    Este exemplo conclui o mapeamento com o elemento ID target, que tem o mesmo tipo de dados que o elemento source.

    A captura de tela mostra o Mapeador de Dados, um ponteiro sobre o elemento de destino e uma linha entre os elementos de origem e de destino.

    Agora você criou um mapeamento direto entre os dois elementos que têm os mesmos tipos de dados.

    A captura de tela mostra um mapeamento completo entre o EmployeeID e o ID nos esquemas de origem e destino, respectivamente.

    O painel Código mostra a relação de mapeamento que você criou:

    A captura de ecrã mostra o painel de Código com mapeamento direto entre EmployeeID e ID nos esquemas de origem e destino, respetivamente.

    Gorjeta

    Para verificar se os mapeamentos têm problemas, selecione Exibir problemas. Por exemplo, aparece um aviso na lista Problemas, no separador Avisos, se criar um mapeamento entre elementos com tipos de dados incompatíveis:

    A captura de tela mostra o mapeamento entre tipos de dados incompatíveis.

Criar um mapeamento complexo entre elementos

Para especificar uma transformação mais complicada entre elementos nos esquemas de origem e de destino, por exemplo, elementos que você deseja combinar ou ter tipos de dados diferentes, você pode usar uma ou mais funções que executam a transformação desejada no mapeamento.

Na superfície do mapeador, o rótulo da função é codificado por cores com base no grupo de funções. Ao lado do nome da função, o símbolo da função aparece, por exemplo:

A captura de ecrã mostra o rótulo de uma função de exemplo.

A tabela a seguir lista os grupos de funções e algumas funções de exemplo que você pode usar. Para obter a lista completa, consulte a lista Funções no Mapeador de Dados.

Grupo Funções de exemplo
Coleção Média, Contagem, Acesso Direto, Valores distintos, Filtro, Índice, Junção, Máximo, Mínimo, Inverter, Ordenar, Subsequência, Soma
Conversão Para data, Para inteiro, Para número, Para cadeia de caracteres
Data e hora Adicionar dias, Data atual, Hora atual, Data igual a
Comparação lógica Igual, Existe, Maior, Maior ou igual, Se, Se não, É nil, É nulo, É um número, É texto, Menor, Menor ou igual, E lógico, NÃO lógico, OU lógico, Diferente
Matemática Absoluto, Adicionar, Arco Tangente, Teto, Cosseno, Divisão, Exponencial, Exponencial (base 10), Piso, Divisão Inteira, Log, Log (base 10), Módulo, Multiplicar, Potência, Redondo, Seno, Raiz Quadrada, Subtrair, Tangente
Cadeia de caracteres Por Pontos de Código para String, Concatenar, Contém, Termina com, Comprimento, Minúsculas, Nome, Combinações de Expressão Regular, Substituição de Expressão Regular, Substituir, Começa com, String para Pontos de Código, Substring, Substring depois, Substring antes, Aparar, Aparar à Esquerda, Aparar à Direita, Maiúsculas
Utilidade Copiar, Erro, Executar XPath, Formatar Data e Hora, Formatar Número, Executar XSLT

Adicionar uma função sem um mapeamento

O exemplo nesta secção transforma os dados no elemento de origem de String para DateTime, que é o tipo do elemento de destino. O exemplo começa sem primeiro criar um mapeamento e usa a função To Date , que aceita uma única entrada.

  1. Para ver o que acontece no código enquanto você cria o mapeamento, no canto superior direito do mapeador, selecione Exibir código.

  2. Na lista Funções, localize e selecione a função que você deseja usar, que adiciona a função à superfície do mapeador. Se a lista de Funções estiver recolhida, no canto superior esquerdo do mapeador, selecione o ícone da função (Ícone da lista de Funções.).

    Este exemplo seleciona a função To Date , que está no grupo de funções Conversion .

    A captura de ecrã mostra a função selecionada com o nome To Date.

    Nota

    Se não existir nenhum mapeamento no mapa ou se um mapeamento for selecionado quando você adicionar uma função ao mapa, a função aparecerá, mas não estará conectada a nenhum elemento ou outras funções, por exemplo:

    A captura de ecrã mostra a função desligada com o nome To Date.

  3. Conecte a função aos elementos de origem e destino.

    1. Arraste e desenhe uma linha entre o elemento de origem e o círculo na borda esquerda da função. Você pode começar a partir do elemento de origem ou da função.

      A captura de tela mostra o mapeamento entre um elemento de origem e uma função.

    2. Arraste e desenhe uma linha entre a borda direita da função e o elemento de destino. Você pode começar a partir do elemento de destino ou da função.

      A captura de tela mostra o mapeamento entre a função e o elemento de destino.

    O painel Código mostra a relação de mapeamento que você criou:

    A captura de tela mostra o painel Código com relação de mapeamento direto entre os elementos de origem e de destino.

  4. Na superfície do mapeador, selecione a forma da função para exibir os detalhes da função.

  5. Na guia Entrada, confirme ou edite a entrada a ser usada.

    A captura de ecrã mostra o separador Entrada da função denominada To Date.

    Alguns cenários exigem a definição de uma transformação além do par imediato de elementos de origem e destino. Por exemplo, para definir uma transformação entre um par de matrizes e seus itens, você precisa criar um loop entre as matrizes. Ou, para executar uma tarefa quando o valor de um elemento atende a uma condição, você precisa adicionar uma condição entre os elementos.

Adicionar uma função que usa várias entradas

O exemplo nesta seção concatena vários elementos de origem como entradas e mapeia uma única saída para o elemento de destino. O exemplo usa a função Concat , que aceita várias entradas.

  1. Para ver o que acontece no código enquanto você cria o mapeamento, no canto superior direito do mapeador, selecione Exibir código.

  2. Na lista Funções, localize e selecione a função que você deseja usar, que adiciona a função à superfície do mapeador.

    Se a lista de Funções estiver recolhida, no canto superior esquerdo do mapeador, selecione o ícone da função (Ícone da lista de Funções.).

    Este exemplo seleciona a função Concat , que está no grupo de funções String .

    A captura de tela mostra a função selecionada chamada Concat.

    Nota

    Se não existir nenhum mapeamento no mapa ou se um mapeamento for selecionado quando você adicionar uma função ao mapa, a função aparecerá, mas não estará conectada a nenhum elemento ou outras funções, por exemplo:

    A captura de tela mostra a função desconectada chamada Concat.

  3. Na superfície do mapeador, selecione a forma da função para exibir os detalhes da função.

  4. Na guia Entrada, selecione os elementos do esquema de origem a serem usados como entradas.

    Este exemplo seleciona os elementos do esquema de origem FirstName e LastName como entradas de função. O mapeador adiciona automaticamente os respetivos mapeamentos entre os elementos de origem e a função.

    A captura de tela mostra vários elementos de origem como entradas de função.

  5. Para concluir o mapeamento, arraste e desenhe uma linha entre a borda direita da função e o elemento de destino. Você pode começar a partir do elemento de destino ou da função.

    A captura de tela mostra mapeamentos concluídos entre várias entradas, função Concat e elemento de destino.

    O painel Código mostra as relações de mapeamento que você criou:

    A captura de tela mostra o painel Código com a função Concat, que tem várias entradas e uma única saída.

Percorrer matrizes

Se os esquemas de origem e destino contiverem matrizes, você poderá criar um loop para iterar pelos itens das matrizes. O exemplo nesta seção cria um loop através de uma matriz de origem Employee e uma matriz de destino Person juntamente com mapeamentos entre os itens das matrizes.

  1. Para ver o que acontece no código enquanto você cria o mapeamento, no canto superior direito do mapeador, selecione Exibir código.

  2. Na superfície do mapeador, nos painéis Origem e Destino , localize as matrizes que você deseja mapear.

  3. Arraste e desenhe uma linha entre o par de itens de matriz. Você pode começar a partir do painel Origem ou do painel Destino .

    O exemplo seguinte começa no painel Origem e mapeia os itens Nome no array de origem Employee e no array de destino Person:

    A captura de tela mostra a superfície do mapeador e o desenho de um mapeamento entre os itens Nome nas matrizes Funcionário de origem e Pessoa de destino.

    Depois de concluir o mapeamento do primeiro par de itens de matriz, o mapeador adiciona automaticamente um loop entre os elementos pai da matriz de origem e de destino, que têm o seguinte tipo de ponto de conexão: Ícone para o ponto de conexão concluído do elemento de matriz.

    O exemplo seguinte destaca o ciclo adicionado automaticamente entre os arrays principais de origem Employee e de destino Person:

    A captura de ecrã mostra o mapeamento em ciclo entre os arrays principais Employee de origem e Person de destino.

    O painel Código mostra o mapeamento e o loop que você criou:

    A captura de ecrã mostra o painel Código com mapeamento de ciclo entre os arrays principais de origem e de destino, bem como os elementos dos arrays.

  4. Continue mapeando os outros elementos da matriz, por exemplo:

    A captura de tela mostra mais mapeamentos entre outros itens de matriz em matrizes de origem e de destino.

Avaliar uma condição para executar uma tarefa

Suponha que você queira adicionar um mapeamento que avalia uma condição e executa uma tarefa quando a condição é atendida. Para esse cenário, você pode usar várias funções.

No exemplo a seguir, quando a quantidade de compra excede 20 itens, o mapeamento calcula um desconto a ser aplicado usando as seguintes funções:

Grupo de funções Função Finalidade neste exemplo
Comparação Maior Verifique se a quantidade de compra é superior a 20.
Comparação Se Verifique se a função Maior retorna true.
Matemática Multiplicar Se a condição for verdadeira, multiplique o preço do item por 10% para calcular o desconto.
  1. Nos painéis Origem e Destino, localize os elementos a serem mapeados em seu cenário.

    Este exemplo usa os seguintes elementos:

    • Painel de origem : ItemPrice e ItemQuantity

    • Painel de destino : ItemPrice, ItemQuantity e ItemDiscount

      A captura de ecrã mostra a área do mapeador e os elementos de dados para o cenário de condição de exemplo.

  2. Na lista Funções, localize e selecione as funções que você deseja usar, o que adiciona as funções à superfície do mapeador.

    • Se a lista Funções estiver recolhida, no canto superior esquerdo do mapeador, selecione o ícone de função (Ícone do painel Funções.).

    • Se necessário, mova as formas de função na superfície do mapeador para torná-las mais fáceis de selecionar.

    Este exemplo adiciona as seguintes funções à superfície do mapeador: Maior, Se e Multiplicar

    A captura de ecrã mostra a interface do mapeador, os elementos de dados e as funções para um cenário de condição de exemplo.

  3. Para visualizar o que acontece no código enquanto você cria os mapeamentos, no canto superior direito do mapeador, selecione Exibir código.

  4. Conecte os elementos de origem, funções e elementos de destino na ordem específica, conforme o cenário exigir.

    Este exemplo conecta os seguintes itens na ordem especificada para criar corretamente os mapeamentos:

    Iniciar Fim
    Elemento de origem ItemPrice ItemPrice elemento alvo
    Elemento de origem ItemQuantity entrada da função Greater na extremidade esquerda da forma. Esta entrada fornece os dados para o campo Valor 1 nos detalhes da função.
    Greater resultado da função no rebordo direito da forma Entrada da função If na borda esquerda da forma. Esta entrada fornece os dados para o campo Condição nos detalhes da função.
    Elemento de origem ItemPrice Entrada da função Multiply no lado esquerdo da forma. Esta entrada introduz os dados para o campo Multiplicando na secção de detalhes da função.
    saída da função Multiply no bordo direito da forma. Entrada da função If na borda esquerda da forma. Esta entrada fornece os dados para o campo Valor nos detalhes da função.
    O resultado da função If na extremidade direita da forma. ItemDiscount elemento de destino

    O exemplo a seguir mostra os mapeamentos neste momento:

    A captura de ecrã mostra a interface do mapeador, os elementos de dados e as funções com mapeamentos para um cenário de condição de exemplo.

  5. Nos detalhes da função seguinte, no separador Entrada, confirme ou indique os seguintes valores:

    Função Campo e valor de entrada
    Maior - Valor 1: Elemento de origem ItemQuantity
    - Valor 2: 20 como um valor personalizado
    Multiplicar - Multiplicand 1: Elemento de origem ItemPrice
    - Multiplicando 2: .10 como um valor personalizado
    Se - Condição: é-maior-que(ItemQuantity, 20)
    - Valor: multiplicar (ItemPrice, .10)

    O mapa a seguir mostra o exemplo concluído:

    A captura de tela mostra o exemplo de condição concluída.

    O painel Código mostra o mapeamento que você criou:

    A captura de ecrã mostra o painel de Código com mapeamento condicional entre os elementos de origem e de destino, utilizando as funções Greater, Multiply e If.

Guarde o seu mapa

Quando terminar, na barra de ferramentas do mapa, selecione Guardar.

O Visual Studio Code salva seu mapa de dados como os seguintes artefatos:

  • Um ficheiro de Mapeador de Dados (<your-map-name>.lml) na pasta de projeto Artifacts>MapDefinitions
  • Um arquivo de mapa de dados (<your-map-name.xslt>) na pasta do projeto Artifacts>Maps

Gorjeta

Para organizar seus artefatos em níveis mais profundos, você pode usar as seguintes pastas e subpastas:

  • Artefatos/Definições de Mapa
  • Artefatos/Esquemas
  • Artefatos/DataMapper/Extensões/Funções
  • Artefatos/DataMapper/Extensões/InlineXslt

Teste o seu mapa

Para confirmar se a transformação funciona como esperado, você precisará de dados de entrada de exemplo.

  1. Antes de testar o seu mapa, guarde o mapa para gerar um ficheiro <your-map-name>.xslt atual.

  2. Na barra de ferramentas do mapa, selecione Abrir painel de teste.

  3. No painel Mapa de teste, na caixa Dados de exemplo, cole a entrada de exemplo e selecione Testar.

    A caixa Resultado mostra os resultados do teste.

Chame seu mapa de um fluxo de trabalho em seu projeto

  1. Na barra de atividades de código do Visual Studio, selecione Explorer (ícone de arquivos) para exibir a estrutura do projeto do aplicativo lógico.

  2. Expanda a pasta que tem o nome do fluxo de trabalho. No menu de atalho do arquivo workflow.json , selecione Abrir Designer.

  3. No designer de fluxos de trabalho, siga estes passos gerais para adicionar a ação incorporada Operações do Mapeador de Dados denominada Transformar com o XSLT do Mapeador de Dados.

  4. No designer, selecione a ação Transformar usando XSLT do Mapeador de Dados.

  5. No painel de informações da ação apresentado, especifique o valor de Conteúdo e deixe Origem do Mapeamento definido como LogicApp.

  6. Abra a lista Nome do mapa e selecione o seu mapa (ficheiro .xslt).

    A captura de tela mostra o Visual Studio Code, designer de fluxo de trabalho padrão, com a ação selecionada chamada Transformar usando XSLT do Mapeador de Dados e propriedades de ação.

    Para usar a mesma ação Transformar usando XSLT do Mapeador de Dados no portal do Azure, você deve adicionar o mapa ao recurso do aplicativo lógico Padrão.

Executar XSLT a partir de um mapa de dados

Você pode executar trechos XSLT executáveis em um arquivo de mapa de dados (.xslt) usando a função Executar XSLT . Quando você usa essa função, você obtém um arquivo de mapa de dados que contém o XSLT executável real. O ficheiro do Mapeador de Dados (.lml) contém uma referência ao ficheiro XSLT executável (.xslt ou .xml).

Para concluir esta tarefa, siga estes passos:

  1. Crie um novo arquivo de mapa de dados (.xslt ou .xml) que contenha o trecho XSLT executável que você deseja executar.

  2. Coloque ou mova o arquivo de trecho XSLT para a seguinte pasta de projeto:

    Artefactos>DataMapper\Extensões>InlineXSLT

    A captura de tela mostra o Visual Studio Code, o projeto do aplicativo lógico padrão e a pasta do projeto InlineXslt com o arquivo InlineXslt.xsd.

    Nota

    Se você criar ou salvar esse arquivo XSLT executável no Visual Studio Code, o arquivo aparecerá automaticamente na pasta do projeto Artifacts>Maps . Certifique-se de mover arquivos de trecho XSLT para a pasta InlineXslt .

  3. Abra o mapa de dados de onde você deseja executar o XSLT.

  4. No painel Funções , em Utilitário, selecione Executar XSLT para adicionar a função à superfície do mapeador.

  5. Na superfície do mapeador, selecione Executar XSLT.

  6. Na lista suspensa Arquivo , selecione o arquivo .xslt executável que você adicionou à pasta InlineXSLT , por exemplo:

    A captura de tela mostra a superfície do mapeador de dados aberta e a função Executar XSLT com o arquivo InlineXslt.xsd selecionado.

  7. Conecte a função Executar XSLT ao nó de destino onde você deseja aplicar a lógica XSLT, por exemplo:

    A captura de tela mostra a superfície do mapeador de dados aberta e a função Executar XSLT conectada ao nó de destino.

    Como a lógica XSLT se aplica apenas ao nó de destino, não é necessário conectar a função Executar XSLT a um nó de origem.

  8. Teste seu mapa para confirmar se os resultados esperados aparecem no esquema de destino.

Para a implementação, precisa apenas do mapa de dados resultante com o XSLT executável em linha.

Acessar nós em XML aninhado

Suponha que você tenha um esquema com nós XML aninhados e queira trabalhar com esses nós das seguintes maneiras:

  • Atributos de acesso ou elementos aninhados.
  • Aplique a lógica com base na estrutura ou no conteúdo dos dados recebidos.

Para concluir essas tarefas, use a função Executar XPath :

  1. Abra o mapa de dados no qual você deseja trabalhar.

  2. No painel Funções , em Utilitário, selecione Executar XPath para adicionar a função à superfície do mapeador.

  3. Na superfície do mapeador, selecione Executar XPath.

  4. Na caixa de expressão XPATH , insira uma expressão que execute o trabalho desejado.

    Para obter informações sobre sintaxe de expressão, consulte Sintaxe XPath.

    Este exemplo usa a //Address expressão junto com uma carga útil de teste:

    A captura de tela mostra a superfície do mapeador de dados aberta e a função Executar XPath com expressão.

    Nota

    As barras oblíquas duplas (//) selecionam, a partir do nó atual, os nós que correspondam à seleção, independentemente de onde se encontrem.

  5. Conecte a função Executar XPath ao nó de destino onde você deseja executar a função.

    Este exemplo liga a função ao nó Endereço no esquema de destino:

    A captura de tela mostra a superfície do mapeador de dados aberta e a função Executar XPath conectada ao nó de destino.

    Nota

    Os nomes dos nós são automaticamente colocados entre aspas duplas (" ").

  6. Teste seu mapa para confirmar se os resultados esperados aparecem no esquema de destino.

    Este exemplo usa uma carga de teste e produz corretamente resultados com vários nós Address porque o nó Address de origem existe num array Employee, enquanto o nó Address de destino existe num array Person.

    A captura de tela mostra a superfície do mapeador de dados aberto, a função Executar XPath e os resultados do teste no esquema de destino.

    Nota

    Se você criar um mapeamento entre matrizes nos esquemas de origem e de destino, um loop aparecerá automaticamente na superfície do mapeador para iterar através dos elementos da matriz. No entanto, você ainda precisa criar mapeamentos entre os elementos da matriz de origem e de destino. Para obter informações sobre como percorrer matrizes, consulte Percorrer matrizes.

Criar funções XML personalizadas

Para definir a lógica reutilizável em seu mapa, você pode criar funções XML personalizadas, que fornecem os seguintes benefícios:

  • Reduza a duplicação e ofereça suporte a transformações específicas do esquema.
  • Envolva lógica complexa em componentes gerenciáveis.
  • Trate casos-limite específicos do esquema.

Para criar uma função XML personalizada, siga estes passos:

  1. Crie um arquivo XML (.xml) com um nome significativo que descreva a finalidade da sua função.

    Seu arquivo XML deve usar um esquema específico para definições de função. Se você tiver várias funções relacionadas, poderá usar um único arquivo para essas funções. Embora você possa usar qualquer nome de arquivo, um nome de arquivo ou categoria significativa torna suas funções mais fáceis de identificar, localizar e descobrir.

  2. Adicione este arquivo XML ao seu projeto de aplicativo lógico na seguinte pasta:

    Artefactos>DataMapper\Extensões>Funções

  3. Abra o mapa de dados onde pretende utilizar a sua função.

  4. No painel Funções , em Utilitário, selecione sua função personalizada, que agora aparece na superfície do mapeador.

  5. Na superfície do mapeador, selecione sua função. Forneça a entrada de que a função precisa para funcionar.

  6. Conecte a função aos pontos de extremidade necessários.

    O exemplo a seguir mostra uma função personalizada chamada Age que retorna a idade para a data de nascimento fornecida. A função se conecta ao nó de origem Dat_of_Birth e ao nó Outro de destino. Para rever a definição para esta função personalizada, consulte Rever a definição de função de exemplo.

    A captura de tela mostra a superfície do mapeador de dados aberta e a função personalizada chamada Idade.

  7. Teste seu mapa para confirmar se os resultados esperados aparecem no esquema de destino, por exemplo:

    A captura de tela mostra a superfície do mapeador de dados aberto, a função personalizada chamada Idade e os resultados da função.

Revisar esquema para uma definição de função

Seu arquivo XML deve usar o esquema a seguir para uma definição de função. Cada elemento XML que tem o "function" nome implementa uma função de estilo XSLT 3.0 com mais alguns atributos. A lista de funções do Mapeador de Dados inclui o nome da função, a descrição, os nomes dos parâmetros e os tipos de parâmetros.

<?xml version="1.0" encoding="utf-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="customfunctions">
      <xs:complexType>
         <xs:sequence>
            <xs:element maxOccurs="unbounded" name="function">
               <xs:complexType>
                  <xs:sequence>
                     <xs:element maxOccurs="unbounded" name="param">
                        <xs:complexType>
                           <xs:attribute name="name" type="xs:string" use="required" />
                           <xs:attribute name="as" type="xs:string" use="required" />
                        </xs:complexType>
                     </xs:element>
                     <xs:any minOccurs="0" />
                  </xs:sequence>
                  <xs:attribute name="name" type="xs:string" use="required" />
                  <xs:attribute name="as" type="xs:string" use="required" />
                  <xs:attribute name="description" type="xs:string" use="required" />
               </xs:complexType>
            </xs:element>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Revise as definições de função de exemplo

O seguinte arquivo deSampleFunctions.xml mostra a implementação para as seguintes funções:

  • "age"
  • "custom-if-then-else"
<?xml version="1.0" encoding="utf-8" ?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<customfunctions>
   <function name="age" as="xs:float" description="Returns the current age.">
      <param name="inputDate" as="xs:date"/> 
      <value-of select="round(days-from-duration(current-date() - xs:date($inputDate)) div 365.25, 1)"/>
   </function> 
   <function name="custom-if-then-else" as="xs:string" description="Evaluates the condition and returns corresponding value.">
      <param name="condition" as="xs:boolean"/>
      <param name="thenResult" as="xs:anyAtomicType"/>
      <param name="elseResult" as="xs:anyAtomicType"/>
      <choose>
         <when test="$condition">
            <value-of select="$thenResult"></value-of>
         </when>
         <otherwise>
            <value-of select="$elseResult"></value-of>
         </otherwise>
      </choose>
   </function>
</customfunctions>