Integração de dados de serviços web
Em publicação anterior Escrevemos que cada tarefa de integração de dados e de geração de relatórios deve começar com uma compreensão clara dos dados de origem. Utilizando a visualização em grade no XMLSpy, a ferramenta líder do setor, Editor de XML e JSON, Analisámos dados JSON referentes a previsões meteorológicas para os próximos 5 dias, obtidos a partir de um serviço web.
Continuando com o cenário que mencionámos anteriormente, utilizaremos o MapForce, uma ferramenta gráfica premiada ferramenta de mapeamento de dados para conversão e integração de qualquer formato para qualquer outro, Para organizar as previsões meteorológicas de uma série de portos importantes de transporte de carga em documentos Excel bem formatados. Queremos destacar quaisquer previsões de ventos fortes ou chuvas intensas que possam causar atrasos, interferindo no carregamento e descarregamento de contentores pelas gruas, ou retardando a entrada e saída de navios nos portos.
A requisição REST para previsões meteorológicas aceita coordenadas de latitude e longitude para fornecer uma previsão de 5 dias para qualquer localidade no mundo. Uma única configuração no MapForce pode mapear múltiplas entradas e saídas, por isso, iniciaremos o projeto de integração de dados do serviço web criando uma lista de portos de carga e as suas coordenadas.
É muito rápido criar a lista como um novo documento JSON na vista de grade no XMLSpy. Basta inserir os dados sem se preocupar com os caracteres de sintaxe do JSON. Na imagem abaixo, clicámos no ícone no canto superior esquerdo para exibir a lista num formato tabular:
A visualização em grade facilita muito a análise e revisão do conteúdo dos ficheiros, ao contrário da visualização de texto, que exibe todos os caracteres de sintaxe necessários num ficheiro JSON válido.
Visão geral do mapeamento de dados
O projeto de integração de dados do serviço web MapForce utilizará a lista de portos como ficheiro de entrada, enviará uma requisição REST para cada conjunto de coordenadas e irá mapear os dados JSON resultantes para cada porto num ficheiro do Excel.
O MapForce utiliza ficheiros de esquema JSON, seguindo as especificações de json-schema.org, para modelar estruturas de dados JSON para mapeamento. O MapForce pode gerar automaticamente um esquema JSON a partir de uma instância JSON. Isso funcionará bem para o único documento port-list.json.
Também precisamos de um esquema JSON para mapear os dados retornados pelo serviço web, o que é um pouco mais complexo. Não temos um único ficheiro .json de previsão que inclua todas as possíveis variações de dados obrigatórios e opcionais na resposta.
Felizmente, o XMLSpy consegue gerar um esquema JSON com base em vários documentos de exemplo recolhidos numa pasta de projeto do XMLSpy.
Ao abrir o esquema resultante na visualização JSON Schema, vemos que o objeto "chuva" é opcional. Isso acontece porque pelo menos um dos ficheiros de previsão não indicou chuva durante os 5 dias, e, portanto, nenhum objeto "chuva" foi incluído na resposta.
Podemos usar este esquema para descrever os dados da resposta REST no mapeamento.
Na imagem abaixo, começámos a criar o mapeamento de dados, importando o ficheiro "post-list.json" e um novo serviço web. Adicionámos a URL REST e mapeámos as coordenadas de latitude e longitude como parâmetros de entrada para construir a requisição. Até agora, o corpo da resposta não tem uma estrutura definida.
Podemos clicar no corpo para abrir a caixa de diálogo "Estrutura da Resposta" e atribuir o esquema que criámos no XMLSpy:
Assim que o esquema é definido, todos os elementos do corpo ficam disponíveis para serem mapeados
Agora podemos adicionar o ficheiro Excel de destino. Foi-nos fornecida uma folha de cálculo de exemplo para usar como modelo, com alguns estilos de células e gráficos, e dados de exemplo:
Podemos adicionar esta folha de cálculo ao mapeamento de integração de dados do serviço web como destino, mas ainda precisamos identificar as células que receberão os dados
Clicar no botão à direita da entrada "Linhas 1, n=dyn" abre a caixa de diálogo "Selecionar intervalo". A linha 10 contém os cabeçalhos das colunas para os dados, por isso, queremos mapear a tabela principal a partir da linha 11 para as colunas de A a K. As colunas têm diferentes tipos de dados, que correspondem principalmente a tipos de texto ou numéricos na fonte JSON e a formatos no Excel. A caixa de diálogo "Selecionar intervalo" permite-nos definir os alvos exatos e os tipos de dados:
Identificar os nomes das colunas na caixa de diálogo "Selecionar intervalo" adiciona-os como rótulos no mapeamento de saída. Em seguida, podemos criar a lógica para mapear cada previsão para um ficheiro Excel separado, como se pode ver abaixo:
O nome do ficheiro, localizado no topo da folha de cálculo do Excel, está definido como "
Também é necessário garantir que a tabela de dados principal em cada ficheiro comece na linha 11. Para isso, associámos o objeto de nível superior do array de listas ao alvo nas linhas 10, com n definido dinamicamente, e utilizamos uma função de numeração automática para reiniciar a linha de início sempre que o nome do ficheiro muda.
Cada objeto de lista na resposta será mapeado para uma nova linha na folha de cálculo do Excel. Agora, podemos associar os elementos individuais da resposta a colunas nessa linha. Na imagem abaixo, associámos todos os elementos que não necessitam de nenhuma transformação adicional.
Para os elementos diretamente associados, os tipos de dados na resposta JSON correspondem diretamente aos tipos que especificámos para as colunas na folha de cálculo. O campo "Temp" nos dados JSON de origem é numérico, e a coluna E no destino também é numérica. O tipo de dado para "description" na origem é texto, e a coluna B no destino também é texto, e assim por diante.
No esquema JSON da resposta, verificámos que o objeto "chuva" era opcional. Se este não existir, queremos substituí-lo pelo valor zero. Isso pode ser feito facilmente através da criação de uma expressão que combine as funções "exists" (existe) e "if-else" (se-então):
Uma limitação do formato de dados JSON é que ele inclui apenas dois tipos de dados: texto e numérico. Tipos de dados como inteiros e datas, ou formatos especiais do Excel, como percentagens e formatos contabilísticos, não são definidos em JSON. O MapForce inclui, de forma conveniente, funções integradas para transformar os dados de origem nos tipos de dados de destino desejados, durante o processo de mapeamento. É assim que podemos criar o formato de data que queremos na coluna A da tabela do Excel.
O elemento "main.dt_text" nos dados JSON representa a data e a hora, formatados como uma cadeia de caracteres, por exemplo: 2020-05-09 06:00:00. O MapForce possui uma função "parse-dateTime" que recebe a cadeia de caracteres e um modelo de formatação como entrada, e fornece um resultado de data e hora. No entanto, existe mais uma complicação: a cadeia de caracteres "dt-txt" está no fuso horário GMT, e não na hora local da cidade para a qual é feita a previsão. O ajuste de fuso horário local é fornecido no elemento "city.timezone" como segundos positivos ou negativos.
Para manter a visualização principal do mapeamento o mais simples possível, criámos uma função de utilizador chamada "calc-local-time". Esta função recebe uma cadeia de caracteres e um valor de deslocamento, e calcula a hora local. A função de utilizador é mapeada da mesma forma que uma função integrada:
A última etapa para concluir o mapeamento da integração de dados do serviço web é combinar os nomes da cidade e do país e adicioná-los à linha 1, coluna C:
Aqui está uma visão completa do mapeamento final:
Para obter os documentos Excel com o formato correto para cada cidade, precisamos de um ficheiro Excel já formatado que corresponda a cada nome de ficheiro de destino. Um ficheiro em lote é uma forma rápida de criar os ficheiros originais, copiando repetidamente o ficheiro Excel de exemplo original, juntamente com os seus estilos e fórmulas.
Resultados da integração de dados através de serviços web
Clicar no botão "Saída" (Output), localizado no canto inferior esquerdo da janela de mapeamento, executa o processo de mapeamento e gera os ficheiros de saída. Se o Excel estiver instalado no computador, a visualização do ficheiro Excel resultante será exibida na janela de "Saída":
A data e hora, bem como as condições meteorológicas atuais, aparecem no topo, e os resumos de texto que estão ao lado do gráfico de precipitação são gerados por fórmulas na folha de cálculo do Excel. Todos os nove ficheiros de saída foram criados e podemos selecionar e visualizar qualquer um deles individualmente. Abaixo, está apresentada a lista de seleção de ficheiros e o sétimo ficheiro, que contém a previsão meteorológica para Seattle:
A funcionalidade do Excel está disponível na janela de visualização. Por exemplo, esta folha de cálculo utiliza a função de rolagem dividida em ecrã, com uma visualização fixa da parte superior. Podemos rolar até o final da tabela de dados principal para ver exatamente a quantidade de precipitação prevista na última previsão. Note os números das linhas no lado esquerdo:
Se o resultado for satisfatório, podemos guardar um ou todos os ficheiros gerados:
Dados intermediários
O MapForce foi concebido para otimizar a conversão de dados. Nunca tivemos de guardar, gerir ou manipular explicitamente os dados JSON intermediários provenientes da resposta REST. A execução desta mapeação de integração de dados de um serviço web não guarda os dados intermediários.
Se desejarmos ou precisarmos guardar os dados da resposta JSON juntamente com as folhas de cálculo Excel finais, o MapForce oferece várias opções. Uma delas é criar um mapeamento encadeado que guarda os dados da resposta como um ficheiro JSON intermédio, com base no mesmo esquema da resposta. Em seguida, poderíamos mapear o ficheiro JSON para criar a saída Excel. Um mapeamento encadeado permite visualizar e guardar ficheiros intermédios, bem como o resultado final. A imagem mostra a lista de ficheiros de saída gerada por um mapeamento encadeado, com um dos ficheiros JSON exibido em modo de texto em segundo plano:
Integração automatizada de dados de serviços web
O nosso cenário de fluxo de trabalho exigiria a atualização das previsões diariamente. Podemos guardar o mapeamento como um ficheiro de execução do MapForce Server para um processamento automatizado pelo MapForce Server, ou implementá-lo diretamente no FlowForce Server para gerar novas previsões de acordo com um cronograma automatizado. Uma tarefa do FlowForce Server pode combinar tarefas de integração de dados com várias ações, incluindo ações do sistema, como mover ficheiros ou enviar e-mails, ou uma tarefa do FlowForce Server pode executar fluxos de trabalho complexos que podem transmitir resultados e parâmetros para acionar outras tarefas.
Veja um vídeo rápido demonstração em vídeo do MapForce, ou Descarregue uma versão de avaliação gratuita incluindo tutoriais, ajuda e muitos exemplos para começar o seu próprio projeto de integração de dados JSON e de serviços web, ou para outras necessidades de mapeamento, conversão e transformação de dados!