Pular para conteúdo

Criando um Consumidor de Dash

Introdução

Como apresentado em Início, o GeoProcess é uma plataforma de ciência de dados baseada no conceito de perguntas e respostas e também na construção de dashboards interativos. Por meio dos dashboards interativos, é possível filtrar diversas informações provindas do banco de dados e, a partir desses filtros, visualizar as informações de forma adequada através de mapas, gráficos e tabelas.

Nesse contexto, o consumidor de dash atua também como a porta de entrada para o GeoProcess juntamente com os consumidores de perguntas, conectando os filtros selecionados pelo usuário às bases de dados disponíveis. Ele retorna as informações necessárias para a construção dos dashboards interativos. Sempre que um usuário deseja desenvolver um dashboard interativo, é necessário criar um consumidor de dash, que será responsável disponibilizar os filtros apropriados e organizar os dados das respostas para gerar as visualizações desejadas.

O GeoProcess permite que desenvolvedores criem consumidores de dash personalizados para atender às necessidades de cada projeto. Esse processo pode ser realizado clonando e adaptando o Consumer Dash Basic, um modelo básico fornecido para esse fim.

A seguir, será demonstrado como usar o Consumer Dash Basic para construir um consumidor de dash personalizado. Neste exemplo, será desenvolvido um consumidor para uma empresa fictícia chamada HARPIA, nomeando o projeto de Consumer-Dash-Harpia.

Instalação

Antes de iniciar a construção de um consumidor de dashboard, é necessário preparar o ambiente com as ferramentas adequadas. Abaixo, apresentamos um passo a passo sucinto para instalação e configuração.

Pré-Requisitos

Para que o Consumer-Dash-Basic funcione corretamente, é necessário atender aos seguintes pré-requisitos:

  • Linguagem Python
  • Pip3
  • Git
  • Visual Studio Code

Além disso, alguns subprojetos do GeoProcess também são necessários. Para isso, clone os seguintes repositórios:

  • pgst-portal
git clone https://github.com/ZETTA-ORG/pgst-portal.git
  • pgst-lib
git clone https://github.com/ZETTA-ORG/pgst-lib.git

Após a instalação dos pré-requisitos, você poderá utilizar o Consumer Dash Basic.

Preparando a Aplicação

O primeiro passo é clonar o projeto Consumer-Dash-Basic. Utilize o comando abaixo:

git clone https://github.com/ZETTA-ORG/pgst-consumer-dash-basic.git

Observação

Esse projeto deve ser clonado dentro de uma pasta geoprocess, conforme a organização do projeto.

Configurando a Aplicação

Após clonar o repositório, será criada uma pasta chamada pgst-consumer-dash-basic, que contém o projeto do consumidor de dashboard básico.

Acesse a pasta do projeto:

cd pgst-consumer-dash-basic

Copie o arquivo de configuração do ambiente para preparar o ambiente de trabalho:

cp conf_samples/env.conf env.conf

copy conf_samples/env.conf env.conf

Edite o arquivo env.conf para configurar os parâmetros de acordo com o seu ambiente de trabalho.

Configure um ambiente virtual venv para isolar as dependências do Python:

python3 -m venv venv

py -m venv venv

Ative o ambiente virtual:

source venv/bin/activate

venv\Scripts\activate

Instale as dependências do projeto:

pip3 install -r requirements.txt

Instale o projeto pgst-lib como uma dependência do consumidor:

pip3 install -e ../pgst-lib/

Executando a Aplicação

Execute a aplicação no modo teste de contrato (CONTRACT_TEST):

python3 main.py CONTRACT_TEST 001

Após isso, a saída será gerada no diretório graph_output. Abra os exemplos html dessa pasta utilizando algum servidor web, como o Live Server http://127.0.0.1:5500/graph_output/graph_graph_1.html.

Uma tela semelhante a mostrada a seguir deverá ser exibida.

Resposta Visual

Primeiras Alterações

Depois de clonar e executar o projeto pgst-consumer-dash-basic para verificar seu funcionamento, podemos começar a adaptá-lo conforme as necessidades do nosso consumidor de dashboard. No exemplo a seguir, criaremos uma versão personalizada chamada pgst-consumer-dash-harpia para a empresa fictícia HARPIA.

Etapas de Personalização

  1. Criar uma Cópia do Projeto

Copie o diretório pgst-consumer-dash-basic e renomeie-o para pgst-consumer-dash-harpia:

cp -r pgst-consumer-dash-basic pgst-consumer-dash-harpia
  1. Remover Arquivos Desnecessários

No diretório pgst-consumer-dash-harpia, exclua os seguintes arquivos e pastas da raiz, pois eles não são necessários para o novo projeto:

rm -rf .git
  1. Abrir o Projeto no Editor de Código

Abra o diretório pgst-consumer-dash-harpia em um editor de código Python. Recomendamos o uso do Visual Studio Code para facilitar as edições.

  1. Configurar o Arquivo env.conf

Abra o arquivo env.conf na raiz do projeto e atualize as configurações de ambiente, incluindo:

CONSUMER_CODE=dash_harpia
  1. Testar a Aplicação Refatorada

Após realizar as alterações, execute a aplicação no modo Contrato para verificar se a refatoração foi bem-sucedida:

python3 main.py CONTRACT_TEST 001

O resultado da execução pode ser visualizado com o Live Server em http://127.0.0.1:5500/graph_output/graph_graph_1.html.

  1. Atualize o Arquivo dashboards.json do Projeto

Após executar a aplicação e verificar que tudo deu certo, podemos agora personalizar as informações do arquivo dashboards.json na raiz do projeto conforme abaixo:

{
    "projects": [
        {
            "consumer_project_id": "HARPIA_DASH",
            "version": "1.1.0",
            "title": "Projeto Dashboard Harpia",
            "role_tag": "HARPIADASH"
        }
    ],
    "dashboards": [
        {
            "id": "dash01",
            "version": 1.1,
            "consumer_project_id": "HARPIA_DASH",
            "role_tag": "DASH01",
            "title": "DashBoard - Harpia",
            ...
        }
    ]
}

Atenção: as role_tag não podem ter o caractere underline (_) nos nomes, pois o underline é usado internamente no Gateway.

Esse arquivo será utilizado quando o sistema estiver em produção.

Para mais detalhes sobre o funcionamento geral desse arquivo, leia a seção Diretório dashboards.

  1. Atualize o Arquivo dashboards.json do Portal

Agora, devemos agora personalizar as informações do arquivo dashboards.json do projeto Portal em pgst-portal/portal/json_samples/ conforme abaixo:

{
    "data":
    [
        ...
        {
            "id": "harpia_dash01",
            "consumer_name": "harpia_dash01",
            "project_id": 1,
            "data" :
            {
                "id": "harpia_dash01",
                "version": 1.1,
                "project_title": "Projeto 1",
                "role_tag": "DASH01",
                "title": "DashBoard - Harpia",
                "description": "Este painel mostra dados de dois gráficos e uma tabela.",
                "consumer_id":"dash_harpia",
                "components": ...,
                "callbacks": ...
            }
        }
    ]
}

Esse arquivo é utilizado quando fazemos testes locais do consumidor de dashboard junto com o Portal, conforme passo a seguir.

  1. Testar a Aplicação Completa com Portal

Após realizar as alterações, é necessário abrir o Docker Desktop e executar o container do Postgis, pgAdmin e o Redis.

Em outro terminal, execute o Consumer-Dash-Harpia.

cd pgst-consumer-dash-harpia/
source venv/bin/activate
cd consumer_dash/
python3 manage.py dash_service

Em seguida, acesse a URL http://0.0.0.0:8000/. Vá em Projeto 1 e em Painéis vá em DashBoard - Basic - Hello World.

  1. Atualizar Conteúdo do Arquivo Service.py

  2. Ajuste o método process1 (e outros métodos caso necessário) para modelar os gráficos específicas do sistema.

  3. Atualizar Arquivos de Teste

    À medida que for desenvolvendo os códigos em Python desse novo consumidor de dashboard crie testes unitários de forma a avaliar melhor o código antes de colocar a aplicação em produção.

    • No arquivo tests/test_001.py, faça os testes de software específicos para o seu sistema.

Próximos Passos

Os próximos passos a serem seguidos dependem muito da aplicação que desejamos desenvolver. Assim, iremos dar apenas uma visão geral do que pode-se fazer e onde devemos alterar.

Integração com BD

No exemplo pgst-consumer-dash-harpia, todos os dados das tabelas e gráficos estão injetados diretamente no código, o que torna a nossa aplicação bastante limitada. Assim, o próximo passo é integrar o consumidor com o BD Postgres de forma que o consumidor leia os dados desse BD.

Para fazer essa integração é necessário ter instalado em seu computador o Docker Desktop, o PostgreSQL, o pgAdmin4 instalado no Docker Desktop. Os softwares PostGIS e PostGIS instalado no Docker Desktop são opcionais e dependem do propósito da aplicação. Para mais informações sobre a instalação, leia a seção Instalações.

Após a criação do banco de dados que será utilizado pelo nosso consumidor é necessário fazer algumas configurações. Edite o arquivo env.conf e atualize os campos: DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, DB_PORT. Esses campos devem ser definidos conforme especificado na criação do BD. Lembre-se de remover o # que indica um comentário na linha.

Após isso, a nossa aplicação está pronta para acessar as informações disponíveis no Banco de Dados configurado. Agora, devemos fazer a programação em Python da nossa aplicação para acessar esses dados. Para mais informações sobre como construir dashboards interativos, leia a seção Consumer-Dash-Sample. Lá tem vários exemplos práticos de dashboards que podem ser construídos.

Fazendo a Implantação do Consumidor

Após o código ter sido desenvolvido e avaliado, precisamos fazer a implantação do nosso consumidor de dashboard na plataforma do GeoProcess.