Compartilhar via


Criar mapas para transformar dados em fluxos de trabalho de aplicativos lógicos com o Visual Studio Code

Aplica-se a: Aplicativos Lógicos do Azure (Standard)

Quando você troca mensagens que usam diferentes formatos XML ou JSON em um fluxo de trabalho de aplicativo lógico, é necessário especificar como transformar ou converter os dados do formato de origem para o formato de destino, por exemplo, entre documentos XML ou documentos JSON. Essa tarefa é importante quando há discrepâncias entre as estruturas de dados nos esquemas de origem e destino. Um esquema descreve os elementos de dados, atributos e tipos de dados em um documento XML ou JSON.

Para definir transformações entre as estruturas de dados e preencher lacunas entre elas, você pode criar um mapa (.xslt) que define os relacionamentos entre os elementos de dados nos esquemas de origem e destino. Você criar e editar visualmente um mapa usando o Visual Studio Code com a extensão Aplicativos Lógicos do Azure (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 de dados por meio de gestos de arrastar e soltar, funções predefinidas para construir expressões e uma maneira de testar mapas manualmente antes de usá-los nos fluxos de trabalho.

Depois de criar seu mapa, você poderá chamá-lo diretamente de um fluxo de trabalho no seu projeto de aplicativo lógico ou de um fluxo de trabalho de aplicativo lógico Standard no portal do Azure. Para essa tarefa, você pode usar a ação Operações do Mapeador de Dados denominada Transformar usando o Mapeador de Dados XSLT no seu fluxo de trabalho.

Essa 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 a partir de um fluxo de trabalho no seu projeto de aplicativo lógico.

Limitações e problemas conhecidos

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

  • No momento, 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.

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

  • No momento, o painel Código no Mapeador de Dados é somente leitura.

  • No momento, o layout e as posições dos itens no Mapeador de Dados são automáticos e somente leitura.

  • A função Filtrar processa corretamente condições numéricas que estão entre aspas duplas, por exemplo, ">=10". Entretanto, essa função atualmente não se comporta de forma padronizada para comparações de cadeia de caracteres, como uma verificação sobre se um nome do item é "= 'Pen'".

  • Quando você cria um mapeamento entre os elementos da matriz pai nos esquemas de origem e destino, o mapeador adiciona automaticamente um loop para iterar pelos elementos da matriz. No entanto, você ainda tem que criar explicitamente os mapeamentos entre os elementos individuais da matriz nos esquemas de origem e destino.

  • Para chamar os mapas criados com o Mapeador de Dados, você só pode usar a ação Operações do Mapeador de Dados chamada Transformar usando o Mapeador de Dados XSLT. Para os mapas criados por qualquer outra ferramenta, utilize a ação Operações XML chamada Transformar XML.

  • Para usar os mapas criados com o Mapeador de Dados em fluxos de trabalho no portal do Azure, você deve adicioná-los diretamente ao recurso de aplicativo lógico Standard.

  • No momento, não há suporte para funções personalizadas nesta versão.

Pré-requisitos

  • Visual Studio Code e a extensão Aplicativos Lógicos do Azure (Standard) para criar fluxos de trabalho de aplicativo lógico padrão.

    Observação

    A extensão do Mapeador de Dados, que anteriormente era separada, agora está mesclada com a extensão de Aplicativos Lógicos do Azure (Standard). Para evitar conflitos, qualquer versão existente da extensão do Mapeador de Dados é removida quando você instala ou atualiza a extensão dos 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 do 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 do esquema XML com a extensão de arquivo.xsd
    • Um arquivo JavaScript Object Notation com a extensão .json
  • Um projeto de aplicativo lógico Standard que inclui um fluxo de trabalho com ou sem estado com pelo menos um gatilho. Se você não tiver um projeto, siga estas etapas no Visual Studio Code:

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

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

  • Faça uma amostra de dados de entrada se quiser testar o mapa e verificar se a transformação funciona conforme o esperado.

  • Para usar a função Executar XSLT , seus trechos XSLT devem existir em arquivos que usam a extensão de nome de arquivo .xml ou .xslt. Você deve colocar os trechos XSLT na pasta InlineXslt na estrutura de pastas do projeto local: Artifacts>DataMapper>Extensions>InlineXslt. Se essa estrutura de pastas não existir, crie as pastas ausentes.

Criar um mapa de dados

  1. No Visual Studio Code, abra a pasta do seu projeto de aplicativo lógico Standard.

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

  3. Na janela 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

    Na barra de título do Visual Studio Code, uma caixa de solicitação será aberta para que você forneça um nome para o seu mapa.

  4. Na caixa de solicitação, insira um nome para o mapa de dados.

    Para este guia, essas etapas usam o nome Example-data-map.

    A captura de tela mostra a caixa de solicitação e um nome de exemplo para o mapa de dados.

    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>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

      Depois que você adiciona o esquema de origem, o painel Origem será preenchido com os nós de elementos XML para os tipos de dados no esquema de origem, por exemplo:

      A captura de tela mostra o painel Origem preenchido com os nós de elementos do esquema XML de origem.

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

      A captura de tela mostra o Mapeador de Dados e o painel Destino com as opções

      Depois que você adiciona o esquema de destino, o painel Destino será preenchido com os nós de elementos XML para os tipos de dados no esquema de destino, por exemplo:

      A captura de tela mostra o painel Destino preenchido com os nós de elementos do esquema XML de origem.

Dica

Se você tiver problemas ao carregar seus esquemas, pode adicionar localmente os arquivos de esquema de origem e destino à pasta Artefatos/Esquemas do seu projeto de aplicativo lógico. Nesse cenário, para especificar os esquemas 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 tipos de dados possíveis que podem aparecer em um esquema:

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

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

Ícone do ponto de conexão do elemento da matriz.
Ícone representando um tipo de dados Bool. Bool Apenas verdadeiro ou falso
Ícone representando um tipo de dados Complex. Complex Um objeto XML com propriedades filho, semelhante ao tipo JSON Object
Ícone representando um tipo de dados DateTime. Datetime
Ícone representando um tipo de dados Decimal. Decimal
Ícone representando um tipo de dados Integer. Inteiro Somente números inteiros
Ícone representando um tipo de dados String. String

Criar um mapeamento direto entre elementos

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

  1. Para visualizar o que acontece no código enquanto 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 deseja mapear.

    • Por padrão, os elementos pai são automaticamente expandidos para exibir os elementos filho.

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

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

    Neste exemplo, o mapeamento começa a partir do elemento de origem ID de Funcionário.

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

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

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

    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 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 EmployeeID e ID nos esquemas de origem e destino.

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

    A captura de tela mostra o painel de código com o mapeamento direto entre EmployeeID e ID nos esquemas de origem e destino, respectivamente.

    Dica

    Para verificar se existem problemas no mapeamento, selecione Exibir problemas. Por exemplo, se você criar um mapeamento entre elementos nos quais os tipos de dados não correspondem, um aviso aparecerá na lista Problemas, na guia Avisos:

    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 complexa entre elementos nos esquemas de origem e destino, como combinar elementos ou lidar com tipos de dados diferentes, você pode usar uma ou mais funções para realizar a transformação desejada no mapeamento.

Na superfície do mapeador, o rótulo da função tem uma cor específica de acordo com o grupo da função. Ao lado do nome da função, aparece o símbolo correspondente, por exemplo:

Captura de tela mostrando o rótulo da função de exemplo.

A tabela a seguir lista alguns grupos de funções e exemplos de funções que você pode usar. Para ver a lista completa, acesse a lista Funções no Mapeador de Dados.

Grupo Funções de exemplo
Coleção Average, Count, Direct Access, Distinct values, Filter, Index, Join, Maximum, Minimum, Reverse, Sort, Subsequence, Sum
Conversão To Date, To Integer, To Number, To String
Data e Hora Add Days, Current Date, Current Time, Equals Date
Comparação lógica Equal, Exists, Greater, Greater or equal, If, If Else, Is Nil, Is Null, Is Number, Is String, Less, Less or Equal, Logical AND, Logical NOT, Logical OR, Not Equal
Matemática Absolute, Add, Arctangent, Ceiling, Cosine, Divide, Exponential, Exponential (base 10), Floor, Integer Divide, Log, Log (base 10), Module, Multiply, Power, Round, Sine, Square Root, Subtract, Tangent
Cadeia de caracteres Codepoints to String, Concat, Contains, Ends with, Length, Lowercase, Name, Regular Expression Matches, Regular Expression Replace, Replace, Starts with, String to Codepoints, Substring, Substring after, Substring before, Trim, Trim Left, Trim Right, Uppercase
Utility Copy, Error, Execute XPath, Format DateTime, Format Number, Run XSLT

Adicionar uma função sem mapeamento

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

  1. Para visualizar o que acontece no código enquanto 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 deseja usar. Isso adiciona a função à superfície do mapeador. Se a lista Funções estiver recolhida, no canto superior esquerdo do mapeador, clique no ícone da função (Ícone da lista de funções.).

    Neste exemplo, selecione a função To Date, que pertence ao grupo de funções de Conversão.

    A captura de tela mostra a função To Date selecionada.

    Observação

    Se não existir nenhum mapeamento ou se um mapeamento estiver selecionado ao adicionar uma função, ela aparecerá, mas não ficará conectada a outros elementos ou funções, por exemplo:

    A captura de tela mostra a função To Date desconectada.

  3. Conectar a função aos elementos de origem e de 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 pelo elemento de origem ou pela 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 pelo elemento de destino ou pela função.

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

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

    A captura de tela mostra o painel de código com o relacionamento de mapeamento direto entre os elementos de origem e destino.

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

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

    A captura de tela mostra a guia Entrada para a função chamada To Date.

    Alguns cenários exigem a definição de uma transformação além do par direto de elementos de origem e destino. Por exemplo, para definir uma transformação entre duas matrizes e seus itens, você precisa criar um loop entre as matrizes. Ou, para executar uma ação quando o valor de um elemento atender 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 visualizar o que acontece no código enquanto 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 deseja usar. Isso adiciona a função à superfície do mapeador.

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

    Neste exemplo, selecione a função Concat, que pertence ao grupo de funções String (Cadeia de caracteres).

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

    Observação

    Se não existir nenhum mapeamento ou se um mapeamento estiver selecionado ao adicionar uma função, ela aparecerá, mas não ficará conectada a outros elementos ou funções, por exemplo:

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

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

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

    Neste exemplo, selecione os elementos do esquema de origem FirstName (nome) e LastName (sobrenome) como entradas da função. O mapeador adiciona automaticamente os respectivos mapeamentos entre os elementos de origem e a função.

    A captura de tela mostra vários elementos de origem como entradas da 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 pelo elemento de destino ou pela função.

    A captura de tela mostra o mapeamento finalizado entre várias entradas, a função Concat e o elemento de destino.

    O painel Código exibe os relacionamentos de mapeamento que você criou:

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

Iterar por meio de matrizes

Se os esquemas de origem e destino contiverem matrizes, você pode criar um loop para iterar pelos itens dessas matrizes. O exemplo a seguir cria um loop através da matriz de origem Funcionário (Employee) e da matriz de destino Pessoa (Person), além de mapear os itens entre essas matrizes.

  1. Para visualizar o que acontece no código enquanto 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 deseja mapear.

  3. Arraste e desenhe uma linha entre os itens do par de matrizes. Você pode começar pelo painel Origem ou pelo painel Destino.

    O exemplo a seguir começa no painel Origem e mapeia os itens Nome na matriz de origem Funcionário e na matriz de destino Pessoa:

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

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

    O exemplo a seguir destaca o loop adicionado automaticamente entre as matrizes pai Funcionário (origem) e Pessoa (destino):

    A captura de tela mostra o mapeamento do loop entre as matrizes pai Funcionário e Pessoa.

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

    A captura de tela mostra o painel de código com o mapeamento do loop entre as matrizes pai de origem e destino, além dos itens das matrizes.

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

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

Avaliar uma condição para executar uma tarefa

Imagine que você quer adicionar um mapeamento que avalia uma condição e executa uma tarefa quando essa condição for atendida. Para este cenário, é possível usar várias funções.

No exemplo a seguir, quando a quantidade de compra ultrapassa 20 itens, o mapeamento calcula um desconto aplicável usando as seguintes funções:

Grupo de funções Função Finalidade deste exemplo
Comparação Maior Verificar se a quantidade de compra é maior que 20.
Comparação If Verificar se a função Greater retorna verdadeiro.
Matemática Multiply Se a condição for verdadeira, multiplicar o preço do item por 10% para calcular o desconto.
  1. Nos painéis Origem e Destino, localize os elementos necessários para mapear neste cenário.

    Este exemplo usa os seguintes elementos:

    • Painel Origem: ItemPrice (preço do item) e ItemQuantity (quantidade de itens)

    • Painel Destino: ItemPrice (preço do item), ItemQuantity (quantidade de itens) e ItemDiscount (desconto do item)

      A captura de tela mostra a superfície do mapeador e os elementos de dados para o cenário da condição do exemplo.

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

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

    • Se necessário, mova as formas das funções na superfície do mapeador para facilitar a seleção.

    Este exemplo adiciona as seguintes funções à superfície do mapeador: Greater, If e Multiply

    A captura de tela mostra a superfície do mapeador, os elementos de dados e as funções para o cenário da condição do exemplo.

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

  4. Conecte os elementos de origem, as funções e os elementos de destino na ordem específica exigida pelo seu cenário.

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

    Iniciar Término
    Elemento de origem ItemPrice Elemento de destino ItemPrice
    Elemento de origem ItemQuantity Entrada da função Greater na borda esquerda da forma. Esta entrada fornece os dados para o campo Value 1 nos detalhes da função.
    Saída da função Greater na borda direita da forma Entrada da função If na borda esquerda da forma. Essa entrada fornece os dados para o campo Condition nos detalhes da função.
    Elemento de origem ItemPrice Entrada da função Multiply na borda esquerda da forma. Essa entrada fornece os dados para o campo Multiplicand nos detalhes da função.
    Saída da função Multiply na borda direita da forma. Entrada da função If na borda esquerda da forma. Essa entrada fornece os dados para o campo Value nos detalhes da função.
    Saída da função If na borda direita da forma. Elemento de destino ItemDiscount

    O exemplo a seguir mostra os mapeamentos neste momento:

    A captura de tela mostra a superfície do mapeador, os elementos de dados e as funções com os mapeamentos para o cenário da condição do exemplo.

  5. Nos detalhes da função a seguir, na guia Entrada, confirme ou forneça os seguintes valores:

    Função Campo de entrada e valor
    Maior - Valor 1: elemento de origem ItemQuantity
    - Valor 2: 20 como um valor personalizado
    Multiply - Multiplicando 1: elemento de origem ItemPrice
    - Multiplicando 2: ,10 como um valor personalizado
    If - Condição: is-greater-than(ItemQuantity, 20)
    - Valor: multiply(ItemPrice, .10)

    O mapa a seguir mostra o exemplo concluído:

    A captura de tela mostra o exemplo de condição finalizada.

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

    A captura de tela mostra o painel de código com o mapeamento condicional entre os elementos de origem e destino usando as funções Greater, Multiply e If.

Salvar seu mapa

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

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

  • O arquivo <your-map-name>.lml será salvo no diretório do projeto: Artifacts>MapDefinitions
  • Um arquivo <your-map-name >.xslt na pasta do projeto Artefatos>Mapas

Testar seu mapa

Para confirmar que a transformação funciona como você espera, você precisará dos dados de entrada de amostra.

  1. Antes de testar o mapeamento, salve o mapa para gerar a versão mais recente do arquivo <your-map-name>.xslt.

  2. Na barra de ferramentas do mapeamento, clique em Abrir painel de teste.

  3. No painel Testar mapeamento, na caixa Dados de amostra, cole os dados de entrada de amostra e clique em Testar.

    A caixa Resultado exibirá os resultados do teste.

Chama seu mapa de um fluxo de trabalho no seu projeto

  1. Na barra de atividades do Visual Studio Code, 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 fluxo de trabalho, siga estas etapas gerais para adicionar a ação interna Operações do Mapeador de Dados chamada Transformar usando o Mapeador de Dados XSLT.

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

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

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

    A captura de tela mostra o Visual Studio Code, designer de fluxo de trabalho Standard, com a ação selecionada chamada Transformar usando o XSLT do Mapeador de Dados e as 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 de aplicativo lógico padrão.