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.

   

   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.

   

   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.

      

      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:

      

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

      

      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:

      

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
	Complexo (matriz)	Contém itens ou nós de itens repetidos. Um elemento de matriz também exibe o seguinte ponto de conexão:
	Bool	Apenas verdadeiro ou falso
	Complex	Um objeto XML com propriedades filho, semelhante ao tipo JSON Object
	Datetime
	Decimal
	Inteiro	Somente números inteiros
	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.

   

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.

   

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

   

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

   

   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:

   

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:

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 ().

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

   

   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:

   

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.

      

   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.

      

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

   

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.

   

   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 ().

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

   

   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:

   

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.

   

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.

   

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

   

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:

   

   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:

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

   

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

   

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

   

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)

     

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 ().

   • 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

   

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:

   

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:

   

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

   

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

   

   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.

Conteúdo relacionado

• Para transformações de dados usando operações B2B nos Aplicativos Lógicos do Azure, confira Adicionar mapas para transformações em fluxos de trabalho com os Aplicativos Lógicos do Azure