--- title: "Integração de dados de serviços web" date: "2020-05-11" categories: - "data-integration" - "json" - "tools" tags: - "data-integration" - "data-mapping" - "excel-data-mapping" - "json-mapping" - "mapforce" - "web-services" description: Explore como integrar dados de previsão meteorológica de um serviço web no Excel, utilizando o MapForce, com foco em técnicas de mapeamento JSON e conversão de dados. --- Status: #blog Tags: #data-integration #data-mapping #excel-data-mapping #json-mapping #mapforce #web-services Categories: [data-integration](/blog/pt/category/data-integration.md) | [json](/blog/pt/category/json.md) | [tools](/blog/pt/category/tools.md) # Integração de dados de serviços web Em [publicação anterior](https://www.altova.com/blog/analyze-json-data-in-xmlspy-grid-view/) 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](https://www.altova.com/pt/xmlspy-xml-editor), 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](https://www.altova.com/pt/mapforce), 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. ![](/blog/images/containership.jpg) 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: [![Uma lista dos principais portos de carga, apresentada numa grelha JSON, no programa XMLSpy](/blog/images/port-list-grid.png)](port-list-grid.png) 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. [![O mesmo ficheiro JSON, visualizado em formato de texto](/blog/images/port-list-text.png)](port-list-text.png) ### 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](http://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. [![Gerar um esquema JSON a partir de vários ficheiros de exemplo em XMLSpy](/blog/images/xmlspy-schema-gen.png)](xmlspy-schema-gen.png) 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. [![Examine o esquema na visualização de esquemas do XMLSpy](/blog/images/schema-view.png)](schema-view.png) 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. [![Adicionar a resposta REST ao mapeamento da integração de dados do serviço web](/blog/images/port-mapping-1.png)](port-mapping-1.png) Podemos clicar no corpo para abrir a caixa de diálogo "Estrutura da Resposta" e atribuir o esquema que criámos no XMLSpy: [![Adicionar o esquema JSON para mapear a estrutura de dados da resposta REST](/blog/images/response-structure-dialog.png)](response-structure-dialog.png) Assim que o esquema é definido, todos os elementos do corpo ficam disponíveis para serem mapeados [![Visualizar cada elemento da resposta REST no mapeamento da integração de dados do serviço web](/blog/images/port-mapping-2.png)](port-mapping-2.png) 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: [![Um modelo de folha de cálculo para o resultado final](/blog/images/sheet-1.png)](sheet-1.png) 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 [![Adicionar a folha de cálculo ao mapeamento de dados](/blog/images/port-mapping-3.png)](port-mapping-3.png) 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: [![Selecionar um intervalo de células para receber os dados](/blog/images/select-range-dialog.png)](select-range-dialog.png) 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: [![Criar nomes de ficheiro únicos para cada folha de cálculo](/blog/images/port-mapping-4.png)](port-mapping-4.png) O nome do ficheiro, localizado no topo da folha de cálculo do Excel, está definido como "", o que indica que a correspondência irá gerar nomes de ficheiros. Cada nome de ficheiro é construído através de uma função de concatenação que incorpora o nome da cidade da lista de origem, criando nomes como "forecast-Seattle.xlsx", etc. 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. [![Conectar os elementos da resposta REST às células da folha de cálculo](/blog/images/port-mapping-5.png)](port-mapping-5.png) 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): [![Substituir por zero caso o valor da precipitação esteja ausente.](/blog/images/port-mapping-6.png)](port-mapping-6.png) 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: [![](/blog/images/port-mapping-7-2.png)](port-mapping-7-2.png) 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: [![Adicionar a cidade e o país na primeira linha](/blog/images/port-mapping-8.png)](port-mapping-8.png) Aqui está uma visão completa do mapeamento final: [![Uma visão completa do mapeamento para a integração de dados de serviços web](/blog/images/port-mapping-complete.png)](port-mapping-complete.png) 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 janela de visualização do resultado mostra o primeiro ficheiro Excel gerado](/blog/images/port-forecast-output-1.png)](port-forecast-output-1.png) 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: [![O menu para visualizar outro ficheiro de saída](/blog/images/port-forecast-output-2.png)](port-forecast-output-2.png) 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: [![Deslizar para visualizar os dados de saída na janela de pré-visualização](/blog/images/port-forecast-output-3.png)](port-forecast-output-3.png) Se o resultado for satisfatório, podemos guardar um ou todos os ficheiros gerados: [![Guardar os ficheiros de saída da integração de dados do serviço web](/blog/images/port-forecast-output-4.png)](port-forecast-output-4.png) ### 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: [![Uma alternativa para a integração de dados de serviços web, utilizando dados intermediários](/blog/images/port-forecast-output-5.png)](port-forecast-output-5.png) ### 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](https://www.altova.com/pt/mapforce-server) 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](https://www.altova.com/pt/flowforceserver) que podem transmitir resultados e parâmetros para acionar outras tarefas. Veja um vídeo rápido [demonstração em vídeo](https://www.altova.com/pt/mapforce/demos) do MapForce, ou [Descarregue uma versão de avaliação gratuita](https://www.altova.com/pt/mapforce/download) 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!