Pular para conteúdo

Criando um Consumidor

Introdução

Como apresentado em Início, o GeoProcess é uma plataforma de ciência de dados baseada no conceito de perguntas e respostas. Por meio de perguntas, é possível acessar diversas bases de dados e, a partir das respostas, construir dashboards interativos compostos por mapas, gráficos e tabelas.

Nesse contexto, o consumidor atua como a porta de entrada para o GeoProcess, conectando as perguntas formuladas pelo usuário às bases de dados disponíveis. Ele retorna as informações necessárias para a construção dos dashboards. Sempre que um usuário deseja desenvolver um dashboard, é necessário criar um consumidor, que será responsável por fazer as perguntas apropriadas e organizar os dados das respostas para gerar as visualizações desejadas.

O GeoProcess permite que desenvolvedores criem consumidores personalizados para atender às necessidades de cada projeto. Esse processo pode ser realizado de diferentes formas, como utilizando o Visual Builder para projetar a interface de resposta antes de escrever o código, ou clonando e adaptando o Consumer Basic, um modelo básico fornecido para esse fim.

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

Instalação

Antes de iniciar a construção de um consumidor, é 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 Basic funcione corretamente, é necessário atender aos seguintes pré-requisitos:

  • Python
  • Pip
  • Git

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

Clonando a Aplicação

O primeiro passo é clonar o projeto Consumer-Basic, acesse o link abaixo:

  • pgst-consumer-basic
git clone https://github.com/ZETTA-ORG/pgst-consumer-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-basic, que contém o projeto do consumidor básico.

Acesse a pasta do projeto:

cd pgst-consumer-basic

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

cp env_sample.conf env.conf

copy env_sample.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\bin\Activate.bat

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

Visualize o resultado do teste de contrato no navegador utilizando o link http://127.0.0.1:8000/. Uma tela semelhante à tela a seguir deverá ser exibida.

Resposta Consumer Basic 1

Resposta Consumer Basic 2

Primeiras Alterações

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

Etapas da Personalização

  1. Criar uma Cópia do Projeto

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

    cp -r pgst-consumer-basic consumer-harpia

  2. Remover Arquivos Desnecessários

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

    rm -rf .git .vscode .pytest_cache

  3. Abrir o Projeto no Editor de Código

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

  4. Renomear Classe e Módulos

    • No arquivo main.py, renomeie a classe BasicWorker para HarpiaWorker.
    • Substitua todas as referências ao módulo basicworker pelo nome harpiaworker.
    • No diretório consumer, renomeie o arquivo basicworker.py para harpiaworker.py:
    mv consumer/basicworker.py consumer/harpiaworker.py

  5. Atualizar Conteúdo do Arquivo harpiaworker.py

    • Renomeie a classe BasicWorker para HarpiaWorker.
    • Atualize os métodos:
    • No método getVersion, mantenha a versão como "1.0".
    • No método getName, altere para "Consumer Harpia".
    • Atualize o atributo messages para refletir as novas informações:
    Message("001", "Consumer Harpia", "Aplicação Consumidor Harpia")
    • Ajuste o método process1 (e outros métodos caso necessário) para modelar as perguntas específicas do sistema.

    Dica

    Você pode aproveitar este momento para colar o código exportado pelo Visual Builder, caso deseje utilizar o mesmo resultado construído na ferramenta.

  6. Atualizar Arquivos de Teste

    • No arquivo test_001.py em tests/contract/001, altere:
    from consumer.basicworker import BasicWorker
# Para:
from consumer.harpiaworker import HarpiaWorker

worker = BasicWorker()
# Para:
worker = HarpiaWorker()
    • No arquivo test_001.py em tests/unit, faça as mesmas alterações acima.

  7. Configurar o Arquivo env.conf

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

    CONSUMER_CODE=harpia

  8. 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 estará disponível em http://127.0.0.1:8000/.

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.

Atualizando o Arquivo questions.json

O próximo passo é realizar a atualização do arquivo questions.json. Para mais detalhes sobre o funcionamento geral desse arquivo, leia a seção Configurando o arquivo questions.json.

Escreva os Testes de Software

À medida que for desenvolvendo os códigos em Python desse novo consumidor crie testes de unidade, testes de contrato e testes de integração de forma a avaliar melhor o código antes de colocar a aplicação em produção. É recomendado que os testes de software sejam criados nessa ordem, pois assim fazemos a validação das partes menores do sistema para as partes maiores.

Com relação aos testes de contrato, o arquivo test_00X.py não precisa de alterações significativas, exceto uma possível atualização da mensagem de log informando o arquivo correto que está sendo executado. Já o arquivo answerRequest.json precisa ser alterado conforme os parâmetros da pergunta que o consumidor é capaz de responder. Nesse arquivo os atributos que devem ser alterado são: consumer_question_id, answer_request_id e data.

Fazendo a Implantação do Consumidor

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