# 🌟⚡ Prospec API - Exemplo em Python ⚡🌟

![Imagem](https://lirp.cdn-website.com/4c0887cb/import/clib/norus_com_br/dms3rep/multi/opt/logotipo1g-250x80-1920w.png)

- Este projeto disponibiliza uma interface em python da API do Prospec, facilitando a implementação de rotinas. 
- O código possui integração com os endpoints existentes, aos quais podem ser chamados de maneira simples e direta.
- Há pelo menos um exemplo de cada endpoint, mostrando ao usuário como realizar a requisição e utilizar funções auxiliares que facilitam ainda mais sua implementação.
- O arquivo *Exemplo 0 - Como fazer requisicao para API.py* apresenta um tutorial básico de uso.
- O arquivo *Exemplo 7 - Fluxo completo estudo NEWAVE-DECOMP.py* apresenta um modelo de fluxo completo.
- Os outros arquivos "*Exemplo*" apresentam casos de utilização de cada endpoint.

## Introdução

Através da biblioteca `prospecapi`, você pode realizar requisições para a API do PROSPEC.

### ✅ Funcionalidades

- Integração com os endpoints da API do Prospec;
- Geração, execução, downloads de estudos prospectivos;
- Login utilizando proxy;
- Listagem de todos os endpoints existentes, juntamente com os parâmetros de entrada;
- Possibilidade de carregar um JSON existente;
- Impressão de log das requisições feitas, exibindo a requisição, o status da requisição e o retorno completo.

### ⚙️ Pré-requisitos

Verifique se os seguintes programas estão instalados:

- **Python** 3.8 ou superior → [Download do Python](https://www.python.org/downloads/)
- **Editor de código** (sugestão: [Site Visual Studio Code](https://code.visualstudio.com/))

### 📦 Instalação

Faça o download da subpasta /Exemplos de consumo da API programática/Python ou então clone este repositório:

```bash
# Clone o repositório
cd seu-repositorio
git clone https://norus@dev.azure.com/norus/Public/_git/prospec-arquivos-uteis
```
Além disso, são necessárias as seguintes bibliotecas: os, re, json, requests, datetime, types, dateutil, urllib.
## 💡 Exemplo de uso

### Autenticação

**Configurando a URL de acesso**

A indicação da URL de acesso é feita através do arquivo *prospecapi.cfg*.  Para isso, é necessário possuir a URL de acesso ao ambiente. A URL padrão de todos os ambientes é empresa.api.prospec.suite.energy. 

Dessa forma, no arquivo *prospecapi.cfg* o cliente deve preencher apenas a informação com o nome da empresa, podendo ser uma abreviação ou qualquer outra combinação acordada no momento da criação do ambiente. 

Dependendo do tipo de autentificação, é necessário informar a utilização da `url_token`:

1) Caso a contratante estiver utilizando autentificação do tipo `basic access`, a flag autenticar_com_token deve ser configurada como `off`;
2) Caso a contratante estiver utilizando autentificação do tipo `access token`, a flag `autenticar_com_token` deve ser configurada como `on`

![image.png](https://dev.azure.com/norus/991000f6-1142-4aa4-920f-1e90e7023cb1/_apis/git/repositories/cd8a7bef-aefa-4c88-a2af-9ac7c8084387/Items?path=/.attachments/image-4b61743d-f26e-4f94-a04f-7d9b8810d6b1.png&download=false&resolveLfs=true&%24format=octetStream&api-version=5.0-preview.1&sanitize=true&versionDescriptor.version=wikiMaster)


**Inserindo as credenciais de acesso**

O login pode ser feito de duas formas:
1) Inserir o usuário e senha no arquivo *credentials* (o código faz a leitura do arquivo) - recomendado
2) Inserir o usuário e senha diretamente dentro do código


Para mais informações de como criar um usuário para utilizar na API, acesse: [Autenticação e Autorização](https://dev.azure.com/norus/Public/_wiki/wikis/Public.wiki/1875/Autentica%C3%A7%C3%A3o-e-Autoriza%C3%A7%C3%A3o ).


### Importação da biblioteca

```python
# Importar a biblioteca prospecapi
import prospecapi

# Logar com credentials + credentials_proxy
api = prospecapi.ProspecAPI()

# Login da Login da API manualmente 
#api = prospecapi.ProspecAPI(username='', password='')
```
Também é possível se autenticar utilizando proxy. Para isso, basta configurar ambos arquivos *credentials* e *credentials_proxy* ou inserir os dados diretamente no código.
```python
# Login da Login da API + proxy manualmente 
#api = prospecapi.ProspecAPI(username='', password='', proxy_url='', proxy_user='', proxy_pass = '')
```


### Sintaxe para fazer requisição
Uma vez definido o conjunto de endpoints necessários à determinada ação, o usuário pode realizar a requisição de duas formas:

- Sintaxe formato de endpoint;
retorno = api.metodo(endereço do endpoint)
retorno = api.metodo(endpoint = endereço do endpoint)*
retorno = api.metodo(endereço do endpoint, params={})
retorno = api.metodo(endereço do endpoint, json={})

*A escrita 'endpoint =' dentro do parênteses é opcional.
- Sintaxe formato de função.
retorno = api.endpoints.metodo.Endereco_Endpoint()
retorno = api.endpoints.metodo.Endereco_Endpoint(param1 = valor1, param2 = valor2)

```python
#Listar endpoints
endpoints = api.list_endpoints()

#Formato endpoint
retorno = api.get('/api/Estudos')

retorno = api.get(endpoint='/api/Estudos')

retorno = api.get('/api/Decks/Download/Resultado/Completo/47787')

retorno = api.get('/api/Estudos', params={'IdEstudo': 13373})

retorno = api.put('/api/Estudos',json={"idDeck":44554,
                                       "arquivos": ["confhd.dat"]})
#Formato função
retorno = api.endpoints.get.Estudos()

retorno = api.endpoints.get.Estudos(IdEstudo=13373)

retorno = api.endpoints.get.Decks_Download_Resultado_Completo_idDeck(idDeck=47787)
```
### Retorno da requisição
O formato do retorno é um dicionário dado por 3 parâmetros: endpoint, status_code e response. 

endpoint: retorna o endpoint realizado,
status_code: status da requisição,
response: resposta da requisição
```python
idEstudo = 13373
retorno = api.get(endpoint='/api/Estudos', params={'IdEstudo': idEstudo})

endpoint = retorno['endpoint']
status_code = retorno['status_code']
response = retorno['response']

estudo = response[0]
id = estudo['id']
dataCriacao = estudo['dataCriacao']
```

## 🔑 Observações Importantes
- O cliente pode dar um help() nas funções geradas dinamicamente pra receber direto no console os detalhes do endpoint sem precisar ir na especificação da API pra pegar os argumentos que precisa passar. 
Exemplo: help(api.endpoints.get.Estudos)

![Imagem](https://dev.azure.com/norus/1584997b-e134-429c-b53d-f7e00260270d/_apis/wit/attachments/22ec9b32-3358-45d9-8be8-500e2f9bef6f?fileName=image.png)

- Nesse projeto existem algumas funções auxiliares que facilitam processos:
  - `prepare_file_list`: prepara os arquivos a serem enviados através do `/Repositorio/UploadArquivos`
  -  `save_file`: download do arquivo para quando o retorno do endpoint é em bytes;
  - `download_url`: download do arquivo para quando o retorno do endpoint é URL pré-assinada;
  - `prepare_month_list`: prepara um dicionário com a configuração "única revisão" e "estágio mensal" na geração NW-DC;
  - `read_json`: lê um arquivo .json.
  

- Para ligar/desligar a impressão do Log, acesse o arquivo prospecapi.cfg e altere o parâmetro "logs"
- Para ligar/desligar a impressão do Verboso, acesse o arquivo prospecapi.cfg e altere o parâmetro "verbose"

## Links úteis

- **Documentação da API** → [Acessar página](http://prospec-api-dev.norus.interno/scalar/)

- **Wiki** → [Acessar página](https://dev.azure.com/norus/Public/_wiki/wikis/Public.wiki/363/Wiki-Norus-Prospec)
