Criar mapas para transformar dados em Aplicativos Lógicos do Azure com o Visual Studio Code

Artigo
11/21/2023

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

Para trocar mensagens com diferentes formatos XML ou JSON em um fluxo de trabalho dos Aplicativos Lógicos do Azure, você precisa transformar os dados de um formato para outro, especialmente se tiver lacunas entre as estruturas do esquema de origem e de destino. A transformação dos dados ajuda a preencher essas lacunas. Para essa tarefa, você precisa criar um mapa que defina a transformação entre os elementos dos dados nos esquemas de origem e de destino.

Para criar e editar visualmente um mapa, você pode usar o Visual Studio Code com a extensão Aplicativos Lógicos do Azure (Padrão) no contexto de um projeto de aplicativo lógico Padrão. A ferramenta Mapeador de Dados fornece uma experiência unificada para mapeamento e transformação da XSLT usando gestos de arrastar e soltar, uma biblioteca de funções predefinida para criar expressões e uma maneira de testar manualmente os mapas que você cria e usa nos seus 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 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.

Este guia de instruções mostra como criar um mapa de dados em branco, escolher seus esquemas de origem e destino, selecione elementos de esquema para iniciar o mapeamento, criar vários mapeamentos, 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 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 arquivos de valores separados por vírgulas (.csv).
O painel Visualização de código do Mapeador de Dados é atualmente somente leitura.
O layout do mapa e a posição do item são atualmente automáticos e somente leitura.
Para chamar os mapas criados com a ferramenta 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 a ferramenta Mapeador de Dados, mas no portal do Azure, você deve adicioná-los diretamente ao recurso de aplicativo lógico Padrã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 anteriormente separada agora é mesclada com a extensão de 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 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

No menu esquerdo do Visual Studio Code, selecione o ícone Azure.
No painel Azure, na seção Mapeador de Dados, selecione Criar novo mapa de dado .
Forneça um nome para seu mapa de dados.
Especifique seus esquemas de origem e destino seguindo estas etapas:
1. Na superfície do mapa, selecione Adicionar um esquema de origem.
2. No painel Configurar aberto, selecione Adicionar novo>Procurar.
3. Encontre e selecione seu arquivo do esquema de origem e, em seguida, selecione Adicionar.
  
  Se o esquema de origem não aparecer na janela Abrir, na lista de tipos de arquivo, altere o Arquivo XSD (*.xsd) para Todos os Arquivos (*.*).
  
  A superfície do mapa agora mostra os tipos de dados do esquema de origem. Para ver os exemplos deste guia,
4. Na superfície do mapa, selecione Adicionar um esquema de destino.
5. No painel Configurar aberto, selecione Adicionar novo>Procurar.
6. Encontre e selecione seu arquivo do esquema de destino e, em seguida, selecione Adicionar.
  
  Se o esquema de destino não aparecer na janela Abrir, na lista de tipos de arquivo, altere o Arquivo XSD (*.xsd) para Todos os Arquivos (*.*).
  
  A superfície do mapa agora mostra os tipos de dados do esquema de destino.
Como alternativa, você também pode adicionar seus arquivos do esquema de origem e de destino localmente ao seu projeto de aplicativo lógico na pasta Artefatos/Esquemas, para que eles apareçam no Visual Studio Code. Nesse caso, você pode especificar seu esquema de origem e destino na ferramenta Mapeador de Dados no painel Configurar selecionando Selecionar existente, em vez de Adicionar novo.

Quando você terminar, seu mapa terá uma aparência semelhante ao exemplo a seguir:

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

Símbolo	Type	Mais informações
	Array	Contém itens ou nós de itens repetidos
	Binário
	Bool	Apenas verdadeiro ou falso
	Complex	Um objeto XML com propriedades filho, semelhante ao tipo JSON Object
	DateTime
	Decimal
	Inteiro	Somente números inteiros
	Nulo	Não é um tipo de dados, mas aparece quando existe um erro ou um tipo inválido
	Número	Um número inteiro ou decimal JSON
	Objeto	Um objeto JSON com propriedades filho, semelhante ao tipo XML Complex
	String

Navegar pelo mapa

Para percorrer o mapa, você tem as seguintes opções:

Para fazer uma panorâmica, arraste o ponteiro pela superfície do mapa. Ou, pressione e segure a roda do mouse, enquanto você move o mouse ou trackball.

Depois de mover um nível para baixo no mapa, no canto inferior esquerdo do mapa, uma barra de navegação aparece na qual você pode selecionar entre as seguintes opções:

Screenshot showing map navigation bar.

Opção	Gesto alternativo
Reduzir	Na superfície do mapa, pressione SHIFT + selecionar duas vezes. -ou- Role para baixo com a roda do mouse.
Ampliar	Na superfície do mapa, selecione duas vezes. -ou- Role para cima com a roda do mouse.
Aplicar zoom para ajustar	Nenhum
Mostrar (Ocultar) o mini-mapa	Nenhum

Para subir um nível no mapa, no caminho da trilha de navegação na parte superior do mapa, selecione um nível anterior.

Selecionar os elementos de destino e origem a serem mapeados

Na superfície do mapa, começando do lado direito, na área do esquema de destino, selecione o elemento de destino que você deseja mapear. Se o elemento desejado for filho de um elemento pai, localize e expanda o pai primeiro.
Agora, no lado esquerdo, na área do esquema de origem, selecione Selecionar elemento.
Na janela Esquema de origem que aparece, selecione um ou mais elementos de origem para mostrar no mapa.
- Para incluir um pai e filhos diretos, abra o menu de atalho do pai e selecione Adicionar filhos.
- Para incluir um pai e todos os filhos desse pai, incluindo quaisquer subpais, abra o menu de atalho do pai no nível superior e selecione Adicionar filhos (recursivo).
Quando você terminar, poderá fechar a janela do esquema de origem. Você sempre poderá adicionar mais elementos de origem posteriormente. No mapa, no canto superior esquerdo, selecione Mostrar esquema de origem ().

Criar um mapeamento direto entre elementos

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

Para revisar o que acontece no código enquanto você cria o mapeamento, no canto superior direito do mapa, selecione Mostrar código.
Se você ainda não tiver, no mapa, selecione os elementos de destino e, em seguida, os elementos de origem que você deseja mapear.
Mova o ponteiro sobre o elemento de origem para que um círculo e um sinal de mais (+) apareçam.
Arraste uma linha para o elemento de destino para que a linha se conecte ao círculo que aparece.

Agora você criou um mapeamento direto entre os dois elementos.

A janela de exibição do código reflete a relação de mapeamento que você criou:

Observação

Se você criar um mapeamento entre elementos nos quais seus tipos de dados não correspondem, um aviso aparecerá no elemento de destino, por exemplo:

Screenshot showing direct mapping between mismatching data types.

Criar um mapeamento complexo entre elementos

Para uma transformação mais complexa entre elementos nos esquemas de origem e de destino, como os elementos que você deseja combinar ou que têm tipos de dados diferentes, você pode usar uma ou mais funções para executar as tarefas para essa transformação.

A tabela a seguir lista os grupos de funções disponíveis e as funções de exemplo que você pode utilizar:

Grupo	Funções de exemplo
Cobrança	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	Adicionar dias
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
String	Code points to string, Concat, Contains, Ends with, Length, Lowercase, Name, Regular expression matches, Regular expression replace, Replace, Starts with, String to code-points, Substring, Substring after, Substring before, Trim, Trim left, Trim right, Uppercase
Utilitário	Copy, Error, Execute XPath, Format date-time, Format number, Run XSLT

No mapa, o rótulo da função se parece com o exemplo a seguir e é codificado por cores com base no grupo de funções. No lado esquerdo do nome da função, aparece um símbolo para a função. No lado direito do nome da função, aparece um símbolo para o tipo de dados da saída da função.

Screenshot showing example function label.

Adicionar uma função sem uma relação de mapeamento

O exemplo nesta seção transforma o tipo de elemento de origem do tipo String para o tipo DateTime, que corresponde ao tipo de elemento de destino. O exemplo usa a função To date, que usa uma única entrada.

Para revisar o que acontece no código enquanto você cria o mapeamento, no canto superior direito do mapa, selecione Mostrar código.
Se você ainda não tiver, no mapa, selecione os elementos de destino e, em seguida, os elementos de origem que você deseja mapear.
No canto superior esquerdo do mapa, selecione Mostrar funções ().
Na lista de funções que se abre, localize e selecione a função que você deseja usar, que adiciona a função ao mapa. Se a função não aparecer visível no mapa, tente diminuir o zoom na superfície do mapa.

Este exemplo seleciona a função To date. Você também pode encontrar e selecionar quaisquer funções personalizadas da mesma maneira. Para obter mais informações, consulte Criar uma função personalizada.

Observação

Se nenhuma linha de mapeamento existir ou estiver selecionada ao adicionar uma função ao mapa, a função aparecerá no mapa, mas desconectada de quaisquer elementos ou outras funções, por exemplo:
Expanda a forma da função para exibir os detalhes da função e os pontos de conexão. Para expandir a forma da função, selecione dentro da forma.
Conectar a função aos elementos de origem e de destino.
1. Arraste e desenhe uma linha entre os elementos de origem e a borda esquerda da função. Você pode começar a partir dos elementos de origem ou da 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.
Na guia Propriedades da função, confirme ou edite a entrada a ser utilizada.

Para alguns tipos de dados, como matrizes, o escopo da transformação também pode aparecer disponível. Esse escopo geralmente é o elemento imediato, como uma matriz, mas em alguns cenários, o escopo pode existir além do elemento imediato.

A janela de exibição do código reflete a relação de mapeamento que você criou:

Por exemplo, para iterar através de itens de matriz, confira Criar um loop entre matrizes. Para executar uma tarefa quando o valor de um elemento atender a uma condição, confira Adicionar uma condição entre elementos.

Adicionar uma função a uma relação de mapeamento existente

Quando já existe uma relação de mapeamento entre os elementos de origem e de destino, você pode adicionar a função seguindo estas etapas:

No mapa, selecione a linha para o mapeamento que você criou.
Mova o ponteiro sobre a linha selecionada e selecione o sinal de adição (+) Inserir função que aparece, por exemplo:
Na lista de funções que se abre, localize e selecione a função que você deseja usar.

A função aparece no mapa e é automaticamente conectada entre os elementos de origem e de destino.

Adicionar uma função com várias entradas

O exemplo nesta seção concatena vários tipos de elementos de origem para que você possa mapear os resultados para o tipo de elemento de destino. O exemplo usa a função Concat, que usa várias entradas.

Para revisar o que acontece no código enquanto você cria o mapeamento, no canto superior direito do mapa, selecione Mostrar código.
Se você ainda não tiver, no mapa, selecione os elementos de destino e, em seguida, os elementos de origem que você deseja mapear.
No canto superior esquerdo do mapa, selecione Mostrar funções ().
Na lista de funções que se abre, localize e selecione a função que você deseja usar, que adiciona a função ao mapa. Se a função não aparecer visível no mapa, tente diminuir o zoom na superfície do mapa.

Este exemplo seleciona a função Concat:

Observação

Se nenhuma linha de mapeamento existir ou for selecionada quando você adicionar uma função ao mapa, a função aparecerá no mapa, mas desconectada de quaisquer elementos ou outras funções. Se a função requer configuração, um ponto vermelho aparece no canto superior direito da função, por exemplo:
Expanda a forma da função para exibir os detalhes da função e os pontos de conexão. Para expandir a forma da função, selecione dentro da forma.
No painel de informações da função, na guia Propriedades, em Entradas, selecione os elementos de dados de origem a serem usados como entradas.

Este exemplo seleciona os elementos de origem Nome e Sobrenome como entradas de função, que adicionam automaticamente as respectivas conexões no mapa.
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 janela de exibição do código reflete a relação de mapeamento que você criou:

Criar um loop entre matrizes

Se os esquemas de origem e de destino incluírem matrizes, você poderá criar uma relação de mapeamento de loop que itera através dos itens dessas matrizes. O exemplo nessa seção faz um loop através de uma matriz de origem do Funcionário e uma matriz de destino da Pessoa.

Para revisar o que acontece no código enquanto você cria o mapeamento, no canto superior direito do mapa, selecione Mostrar código.
No mapa, na área do esquema de destino, selecione o elemento da matriz de destino e os elementos do item da matriz de destino que você deseja mapear.
No mapa, na área do esquema de destino, expanda o elemento da matriz de destino e os itens da matriz.
Na área do esquema de origem, adicione o elemento da matriz de origem e os elementos do item da matriz ao mapa.
Criar um mapeamento direto entre os elementos de origem e de destino .

Quando você cria pela primeira vez uma relação de mapeamento entre um par correspondente de itens da matriz, uma relação de mapeamento é criada automaticamente no nível da matriz pai.

A janela de exibição do código reflete a relação de mapeamento que você criou:
Continue mapeando os outros elementos da matriz.

Configurar uma condição e tarefa para executar entre os elementos

Para adicionar uma relação de mapeamento que avalia uma condição e executa uma tarefa quando a condição é atendida, você pode usar várias funções, como a função If, uma função de comparação como Greater e a tarefa a ser executada como Multiply.

O exemplo nesta seção calcula um desconto a ser aplicado quando a quantidade de compra exceder 20 itens usando as funções a seguir:

Greater: verifica se a quantidade do item é maior que 20.
If: Verifica se a função Greater retorna verdadeiro.
Multiply: calcula o desconto multiplicando o preço do item por 10% e a quantidade do item.

Para revisar o que acontece no código enquanto você cria o mapeamento, no canto superior direito do mapa, selecione Mostrar código.
Se você ainda não tiver, no mapa, selecione os elementos de destino e, em seguida, os elementos de origem que você deseja mapear.

Este exemplo seleciona os seguintes elementos:
No canto superior esquerdo do mapa, selecione Mostrar funções ().
Adicione as seguintes funções ao mapa: Greater, If e Multiply
Expanda todas as formas da função para mostrar os detalhes da função e os pontos de conexão.
Conecte os elementos de origem, as funções e os elementos de destino da seguinte forma:
- O elemento ItemPrice do esquema de origem para o elemento ItemPrice do esquema de destino
- O elemento ItemQuantity do esquema de origem para o campo Valor da função Greater
- A saída da função Greater para o campo Condição da função If
- O elemento ItemPrice do esquema de origem para o campo Multiply da função Multiplicando 0*
- A saída da função Multiply para o campo Valor da função If
- A saída da função If para o elemento ItemDiscount do esquema de destino
Observação

Na função If, a palavra ANY aparece à direita do nome da função, indicando que você pode atribuir o valor de saída a qualquer coisa.

Nas funções a seguir, na guia Propriedades, especifique os seguintes valores:

Função	Parâmetro e valor de entrada
Maior	- Valor #1: o elemento de origem chamado Quantidade de itens - Valor #2: 20
Multiply	- Multiplicando #1: O elemento de origem chamado ItemPrice - Multiplicando #2: .10
If	- Condição: is-greater-than(ItemQuantity,20) - Valor: multiply(ItemPrice, .10)

O mapa a seguir mostra o exemplo concluído:

Screenshot showing finished condition example.

A janela de exibição do código reflete a relação de mapeamento que você criou:

Screenshot showing code view with conditional mapping between source and target elements using the functions, Greater, If, and Multiply.

Salvar seu mapa

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

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

Um arquivo <your-map-name >.yml na pasta do projeto Artefatos>MapDefinitions
Um arquivo <your-map-name >.xslt na pasta do projeto Artefatos>Mapas

Gere o arquivo XSLT a qualquer momento

Para gerar o arquivo <seu-nome-do-mapa>.xslt a qualquer momento, na barra de ferramentas do mapa, selecione Gerar XSLT.

Testar seu mapa

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

Antes de testar seu mapa, certifique-se de gerar o arquivo <seu-nome-do-mapa>.xslt mais recente.
Na barra de ferramentas do mapa, selecione Teste.
No painel Mapa de teste, na janela Entrada, cole seus dados de entrada de amostra e selecione Teste.

O painel de teste alterna para a guia Saída e mostra o código de status do teste e o corpo da resposta.

Chama seu mapa de um fluxo de trabalho no seu projeto

No menu esquerdo do Visual Studio Code, selecione Explorer (ícone de arquivos) para exibir a estrutura do projeto do aplicativo lógico.
Expanda a pasta que tem o nome do fluxo de trabalho. No menu de atalho do arquivo workflow.json , selecione Abrir Designer.
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.
No designer, selecione a ação Transformar usando XSLT do Mapeador de Dados.
No painel de informações de ação exibido, especifique o valor Conteúdo e deixe Origem do Mapa definido como Aplicativo Lógico. Na lista Nome do mapa, selecione o arquivo de mapa (.xslt) que você deseja utilizar.

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.

Criar uma função personalizada

Para criar sua própria função que você pode usar com a ferramenta Mapeador de dados, execute estas etapas:

Crie um arquivo XML (.xml) que tenha um nome significativo que descreva a finalidade da sua 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 significativo torna suas funções mais fáceis de identificar, localizar e descobrir.

No arquivo XML, você deve usar o seguinte esquema para a definição de função:

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

Cada elemento XML chamado "function" implementa uma função de estilo XSLT3.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.

O exemplo a seguir mostra a implementação de um arquivo SampleFunctions.xml:

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

No computador local, abra a pasta do projeto de aplicativo lógico padrão.
Abra a pasta Artifacts e crie a seguinte estrutura de pastas, se nenhuma existir: DataMapper>Extensions>Functions.
Na pasta Functions salve o arquivo XML da função.
Para localizar sua função personalizada na lista de funções da ferramenta Mapeador de Dados, pesquise a função ou expanda a coleção Funções personalizadas.

Próximas etapas

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

Compartilhar via