Skip to content
GitLab
Projects Groups Topics Snippets
  • /
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in
  • Zarc-NM-docs Zarc-NM-docs
  • Project information
    • Project information
    • Activity
    • Members
  • Wiki
    • Wiki
  • Activity
Collapse sidebar
  • Zarc - Niveis de ManejoZarc - Niveis de Manejo
  • Zarc-NM-docsZarc-NM-docs
  • Wiki
  • Home

Home · Changes

Page history
Create Home authored Oct 04, 2024 by Daniel Rodrigo De F Apolinario's avatar Daniel Rodrigo De F Apolinario
Hide whitespace changes
Inline Side-by-side
Home.md 0 → 100644
View page @ 90db4ca9
<!-- Texto mais geral, explicando a API Zarc para níveis de manejo -->
A API do Zarc-NM foi desenvolvida com o propósito de receber dados relacionados à glebas (ou talhões) produtivas e a partir dos dados recebidos, classificar a gleba de acordo com o seu nível de manejo, seguindo a metodologia de classificação publicada em 2022 pela Embrapa com o título [**"Níveis de manejo do solo para avaliação de riscos climáticos na cultura da soja."**](https://ainfo.cnptia.embrapa.br/digital/bitstream/doc/1148652/1/DOCUMENTO-447-final.pdf) (DEBIASI, H.; MONTEIRO, J. E. B. de A.; FRANCHINI, J. C.; FARIAS, J. R. B.; CONTE, O.; CUNHA, G. R. da; MORAES, M. T. de; BALBINOT JUNIOR, A. A.; SILVA, F. A. M. da; EVANGELISTA, B. A.; MARAFON, A. C.).
## Requisitos
<!-- Elencar os requisitos da API em 2 principais seções: descrições e atores -->
Os principais requisitos que guiaram a construção da API são listados abaixo:
1. Aplicar todas as regras de cálculo da classificação de nível de manejo (níveis de 1 a 4) de forma flexível para que as regras possam ser alteradas de maneira simples, assim como novas regras possam ser incorporadas e/ou removidas.
2. As regras de cálculo precisam ser versionadas para que haja rastreabilidade entre classificações já realizadas e regras/parâmetros aplicados.
3. Os dados das glebas precisam ser geolocalizados, para que se possa criar mecanismos de verificação via monitoramento por imagens de satélite/drone.
4. Tanto os dados das glebas enviados para a API, quanto os dados de classif icação gerados pela aplicação das regras precisam ser armazenados em banco de dados para posterior consulta e auditoria.
5. Permitir que parceiros possam enviar dados automaticamente via sistemas/máquinas.
6. Os dados da gleba relacionados às características da gleba (propriedade, localização) ao histórico de cultivo (diversidade de culturas ao longo do tempo) e de operações de manejo realizadas serão enviados em um endpoint específico com permissão a um perfil de usuário (Operador de Contratos).
7. Os dados da gleba relacionados à análise de amostras de solo (variáveis químico, físico e orgânicas do solo) serão enviadas em um endpoint específico com permissão a um perfil de usuário (Operador de Análise de Solo).
8. Os dados da gleba relacionados ao sensoriamento remoto, tais como índices vegetativos, interpretação de culturas e datas de operações serão enviadas em um endpoint específico com permissão a um perfil de usuário (Operador de Sensoriamento Remoto).
9. A classificação de nível de manejo geral de uma gleba será a classificação de menor nível de todos os indicadores para aquela gleba.
10. As consultas ao resultado de uma classificação de nível de manejo para uma gleba retornarão apenas a classificação geral da gleba.
Principais atores interessados:
![atores-zarcnm](uploads/1b3d843fd4531b55bedaa5d5f9549d42/atores-zarcnm.png)
## Arquitetura
<!-- Descrever e mostra através de diagramas a visão arquitetural do sistema em níveis macro e em detalhes (não tão detalhado) -->
**Visão geral da API Zarc-NM:**
![overview-api-zarcnm](uploads/8db8a36fddbe950d4b46eac5d0f173aa/overview-api-zarcnm.png)
</br>
**Visão Arquitetural da API ZARC-NM:**
![architecture-overview](uploads/dd81cb5a2de9d0e9e177b0861586468c/architecture-overview.png)
## Funcionamento
Para a utilização da API ZarcNM, primeiramente é necessário autenticar-se com usuário com credencias válidas e assim obter um token de acesso. Em posse do token de acesso e dentro de seu período de validade, as APIs podem ser acessadas. Abaixo, vamos ilustrar como se dá a autenticação e posteriormente o uso das APIs. Depois, na seção "Como usar", temos um passo a passo com templates e imagens de uso das APIs por meio da ferramenta Postman.
### 1. Autenticação
Envio das credenciais de acesso
![Autenticacao-1.drawio](uploads/8e27df49ade03f0ac0960ba03e1a0b96/Autenticacao-1.drawio.png)
Obtendo o token de acesso após validação das credencias
![Autenticacao-2.drawio](uploads/b5c866489c5d3ff113d03d0ff0f00ff2/Autenticacao-2.drawio.png)
Enviando uma requisição a API do ZarcNM
![Autenticacao-3.drawio](uploads/15fabbfa3e8360622ad01f8e10d64442/Autenticacao-3.drawio.png)
Verificando a autenticidade e valdidade do token de acesso
![Autenticacao-4.drawio](uploads/8b415b0831edae792e65e7a273ccce42/Autenticacao-4.drawio.png)
Resposta da requisição enviada pela aplicação cliente
![Autenticacao-5.drawio](uploads/2d18270d01052f448d75dedce940f6c2/Autenticacao-5.drawio.png)
### 2. Envio de dados de identificação da gleba, histórico de cultivos e operaçõe de manejo
![Envio-historic-cultivos.drawio](uploads/41e788ae3c935e40e78fd9d85044bf5d/Envio-historic-cultivos.drawio.png)
</br>
### 3. Envio de dados de amostras de solo
![Envio-amostras-solo.drawio](uploads/d896ce0d86bd44c4bd189272ffed8cb6/Envio-amostras-solo.drawio.png)
</br>
### 4. Envio de dados de sensoriamento remoto
![Envio-sensoriamento-remoto.drawio](uploads/d3d33ecdf9aebde39ca50622c35a9143/Envio-sensoriamento-remoto.drawio.png)
</br>
### 5. Consulta à classificação final de nível de manejo
![Consulta-classificacao-final-NM.drawio](uploads/bacb55a9f20863e91928bbc4ae450f40/Consulta-classificacao-final-NM.drawio.png)
## Como usar?
<!-- Mostrar, em formato de tutorial passo a passo como utilizar a API do Zarc-NM -->
### 1. Autenticação de usuário
Para ter acesso a [`API Zarc-NM`](#api-zarc-nm) o usuário precisa estar autenticado. A autenticação é realizada via protocolo [*OpenId Connect*](https://auth0.com/pt/intro-to-iam/what-is-openid-connect-oidc) (OIDC) usando o fluxo *Password Credentials* da especificação [*OAuth2*](https://auth0.com/pt/intro-to-iam/what-is-oauth-2). Para demonstrar como é realizado o processo de auntenticação e acesso aos *endpoints* da [`API Zarc-NM`](#api-zarc-nm) , iremos utilizar a plataforma [*Postman*](https://www.postman.com/).
Foi criado um arquivo [*JSON*](https://www.json.org/json-pt.html) nomeado ***Endpoints API Zarc-NM.postman_collection.json***, nesse arquivo há uma *collection* com os *enpoints* presentes na [`API Zarc-NM`](#api-zarc-nm). Para enviar requisições a [`API Zarc-NM`](#api-zarc-nm), primeiramente baixe o arquivo ***Endpoints API Zarc-NM.postman_collection.json*** que encontra-se disponível para *download* em: [https://www.gitlab.cnptia.embrapa.br/zarc-nivel-manejo/zarc-nm-docs/-/blob/main/postman/Endpoints%20API%20Zarc-NM.postman_collection.json?ref_type=heads](https://www.gitlab.cnptia.embrapa.br/zarc-nivel-manejo/zarc-nm-docs/-/blob/main/postman/Endpoints%20API%20Zarc-NM.postman_collection.json?ref_type=heads), em seguida, faça a importação do arquivo no [*Postman*](https://www.postman.com/). Para importar o arquivo no [*Postman*](https://www.postman.com/), acesse a aba ***File*** (*Cf*. retângulo vermelho, Figura 1), em seguida, clique na opção ***Import...*** (*Cf*. retângulo amarelo, Figura 1).
<div align="center">
**Figura 1**. Postman
</div>
![postman-import](uploads/2ce5abc575f0fcff750f2f629d765737/postman-import.png)
Seguidamente escolha a alternativa ***files*** e selecione o arquivo (*Cf*. retângulo vermelho, Figura 2).
<div align="center">
**Figura 2**. Postman - Import files
![postamn-import-files](uploads/d76251e110077c512d7d74042c1e3eaf/postamn-import-files.png)
</div>
Ao finalizar o processo de importação do arquivo, o [*Postman*](https://www.postman.com/) irá exebir na aba ***Collections*** a *collection* ***Endpoints API Zarcn-NM***, informando que a importação ocorreu corretamente (*Cf*. retângulo vermelho, Figura 3). Após isso, clique na *collection* ***Endpoints API Zarcn-NM*** e acesse a aba ***Authorization*** (*Cf*. retângulo laranja, Figura 3), em seguida, na seção ***Configure New Token*** preencha com as suas credenciais de acesso os seguintes campos (*Cf*. retângulo amarelo, Figura 3):
* *Client ID*
* *Client Secret*
* *Username*
* *Password*
<div align="center">
**Figura 3**. Postman - Authorization
</div>
![postman-authorization](uploads/363a5ad1f22f807a9e6b73fa26b19535/postman-authorization.png)
Os outros campos não devem serem alterados, pois eles já estão preenchidos com as informações necessárioas para o processo de autenticação. Após preencher os campos solicitados, clique no botão ***Get New Accesss Token***, para autenticar e receber um token de acesso (*Cf*. retângulo amarelo, Figura 4).
<div align="center">
**Figuara 4**. Authorization - Get new access token
</div>
![postman-get-new-access-token](uploads/fdb6271a849510b348035672b63a919b/postman-get-new-access-token.png)
Logo após, clique no botão ***Proceed*** (*Cf*. retângulo amarelo, Figura 5)
<div align="center">
**Figuara 5**. Get new access token - Proceed
![postman-proceed](uploads/40ede296cc4417fa89d1a33aaee8529d/postman-proceed.png)
</div>
Por fim, clique no botão ***Use Token*** (*Cf*. retângulo amarelo, Figura 6). Depois de executar esses passos, o token recebido é habilitado possibiltando o usuário realizar requisições com acesso autenticado para a [`API Zarc-NM`](#api-zarc-nm). Esses passos devem serem realizados apenas na *collection* ***Endpoints API Zarcn-NM***, pois isso habilita o token em todos os endpoints presentes nessa *collection*. Adicionalmente, esse procedimento deve ser realizado todas as vezes que o token expirar.
<div align="center">
**Figuara 6**. Get new access token - Use token
![postman-use-token](uploads/ab8b25f6472450829d1a7286829c4e92/postman-use-token.png)
</div>
### 2. Envio de dados da gleba/talhão
Dados da gleba/talhão (propriedade, glebas, culturas e manejos). Essas informações são necessárias para dar início ao processo de classificção da gleba/talhão, para a qual se deseja obter o nível de manejo. Após realizar o processo de autenticação descrito na Subseção [`Autenticação de usuário`](#1-autenticação-de-usuário), use a plataforma [*Postman*](https://www.postman.com/) para enviar os dados da gleba/talhão.
Para isso, clique em ***Dados da Gleba/Talhão*** , seguidamente em ***POST Glebas - Adicionar*** (*Cf*. retângulo rosa, Figura 7) e faça uma requisição [HTTP](https://developer.mozilla.org/pt-BR/docs/Web/HTTP) utilizando o método [POST](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Methods/POST)
para a [`API Zarc-NM`](#api-zarc-nm), que está disponível em: [www.zarcnm.cnptia.embrapa.br/zarcnm/glebas](https://www.zarcnm.cnptia.embrapa.br/zarcnm/glebas) (*Cf*. retângulo laranja, Figura 7).
<div align="center">
**Figuara 7**. Postman - Envio de dados da gleba/talhão
</div>
![postman-post-glebas](uploads/6a667cfcf86e7e90fdc892fd07c64b9e/postman-post-glebas.png)
Após o envio da solicitação, se todas as informações enviadas no cabeçalho e no corpo da requisição foram informadas corretamente (*Cf*. retângulos laranja e amarelo, Figura 7), a [`API Zarc-NM`](#api-zarc-nm) retorna o código [201 Created - HTTP Status ](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201) informando que o recurso foi criado com sucesso. No corpo da resposta são retornados os dados que foram enviados na requisição e uma chave nomeada de chave da classificação de nível de manejo - ***chaveClassificacaoNM***
que deverá ser guardada (*Cf*. retângulo azul, Figura 7). Esta chave será a identificação usada para envio posterior dos dados de análise de solo, de geoprocessamento e de consulta ao nível de manejo calculado.
### 3. Envio de dados de análise de solo
Dados de análise de solo (do conjunto de amostras de solo). Essas informações são necessárias para dar continuidade no processo de classificação após cadastro da(s) gleba(s). Para enviar estes dados, o usuário deve estar autenticado (*Cf*. Subseção [`Autenticação de usuário`](#1-autenticação-de-usuário)) e precisa ter a chave ***chaveClassificacaoNM*** gerada com o cadastro da gleba na etapa anterior (*Cf*. retângulo azul, Figura 7).
Utilizando o [*Postman*](https://www.postman.com/), o usuário enviará uma solicitação para a [`API Zarc-NM`](#api-zarc-nm) passando a chave ***chaveClassificacaoNM***. Para isso, clique em ***Dados de Laboratório*** , seguidamente em ***POST Amostras - Adicionar*** (*Cf*. retângulo rosa, Figura 8) e faça uma requisição [HTTP](https://developer.mozilla.org/pt-BR/docs/Web/HTTP) utilizando o método [POST](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Methods/POST)
para a [`API Zarc-NM`](#api-zarc-nm), que que está disponível em: [www.zarcnm.cnptia.embrapa.br/zarcnm/amostras/***chaveClassificacaoNM***](https://www.zarcnm.cnptia.embrapa.br/zarcnm/amostras) (*Cf*. retângulo laranja, Figura 8).
<div align="center">
**Figuara 8**. Postman - Envio de dados de análise de solo
</div>
![postman-post-amostras](uploads/ee0d4115e6af0425f57b76b9173ff9ff/postman-post-amostras.png)
Após o envio da solicitação, se todas as informações enviadas no cabeçalho e no corpo da requisição foram informadas corretamente (*Cf*. retângulos laranja e amarelo, Figura 8), a [`API Zarc-NM`](#api-zarc-nm) retorna o código [201 Created - HTTP Status ](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201) informando que o recurso foi criado com sucesso. No corpo da resposta são retornados os dados que foram enviados na requisição (*Cf*. retângulo amarelo, Figura 8).
*Os dados de análise de solo enviados para uma chave de classificação de nível de manejo podem ser enviados apenas uma única vez (futuramente haverá recursos para retificação)*.
### 4. Envio de dados de sensoriamento remoto
Dados de sensoriamento remoto relacionados à gleba/talhão para a qual foi solicitada uma classificação de nível de manejo. Os dados de geoprocessamento serão necessários para validar as informações fornecidas pelo agente do contrato no processo de classificação das glebas/talhões. Para realizar o envio desses dados, o usuário deve estar autenticado (*Cf*. Subseção [`Autenticação de usuário`](#1-autenticação-de-usuário)) e precisa ter a chave ***chaveClassificacaoNM*** gerada com o cadastro da gleba na etapa anterior (*Cf*. retângulo azul, Figura 7).
Utilizando o [*Postman*](https://www.postman.com/), o usuário enviará uma solicitação para a [`API Zarc-NM`](#api-zarc-nm) passando a chave ***chaveClassificacaoNM***. Para isso, clique em ***Dados de Sensoriamento Remoto*** , seguidamente em ***POST Monitoramentos - Adicionar*** (*Cf*. retângulo rosa, Figura 9) e faça uma requisição [HTTP](https://developer.mozilla.org/pt-BR/docs/Web/HTTP) utilizando o método [POST](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Methods/POST)
para a [`API Zarc-NM`](#api-zarc-nm), que que está disponível em: [www.zarcnm.cnptia.embrapa.br/zarcnm/monitoramentos/***chaveClassificacaoNM***](https://www.zarcnm.cnptia.embrapa.br/zarcnm/amostras) (*Cf*. retângulo laranja, Figura 9).
<div align="center">
**Figuara 9**. Postman - Envio de dados da análise de sensoriamento remoto
</div>
![postman_post_monitoramento](uploads/dcb2293c9a9507e78149b233b2f3ae21/postman_post_monitoramento.png)
Após o envio da solicitação, se todas as informações enviadas no cabeçalho e no corpo da requisição foram informadas corretamente (*Cf*. retângulos laranja e amarelo, Figura 9), a [`API Zarc-NM`](#api-zarc-nm) retorna o código [201 Created - HTTP Status ](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201) informando que o recurso foi criado com sucesso. No corpo da resposta são retornados os dados que foram enviados na requisição (*Cf*. retângulo amarelo, Figura 9). Além disso, logo após o envio desses dados, é realizado o cálculo da classificação de nível de manejo para a gleba/talhão referente a chave informada. E o usuário pode consultar o resultado da classifição na [`API Zarc-NM`](#api-zarc-nm)(*Cf*. Subseção [`Classificação nível manejo`](#2-classificação-nível-manejo)).
*Os dados de sensoriamento remoto enviados para uma chave de classificação de nível de manejo podem ser enviados apenas uma única vez (futuramente haverá recursos para retificação).*
### 2. Classificação nível manejo
Uma vez que o registro dos dados obrigatórios tenha sido finalizado e o cálculo da classificação tenha sido realizado, é possível consultar a classificação do nível de manejo de uma determinada gleba/talhão na [`API Zarc-NM`](#api-zarc-nm). Para a consulta, o usuário deve estar autenticado (*Cf*. Subseção [`Autenticação de usuário`](#1-autenticação-de-usuário)) e precisa ter a chave ***chaveClassificacaoNM*** gerada com o cadastro de uma determinada gleba/talhão (*Cf*. retângulo azul, Figura 7).
Utilizando o [*Postman*](https://www.postman.com/), o usuário enviará uma solicitação para a [`API Zarc-NM`](#api-zarc-nm) passando a chave ***chaveClassificacaoNM***. Para isso, clique em ***Classificação Nível Manejo*** , seguidamente em ***GET Classificações - Buscar*** (*Cf*. retângulo vermelho, Figura 10) e faça uma requisição [HTTP](https://developer.mozilla.org/pt-BR/docs/Web/HTTP) utilizando o método [GET](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Methods/GET)
para a [`API Zarc-NM`](#api-zarc-nm), que que está disponível em: [www.zarcnm.cnptia.embrapa.br/zarcnm/classificacoes/***chaveClassificacaoNM***](https://www.zarcnm.cnptia.embrapa.br/zarcnm/classificacoes) (*Cf*. retângulo laranja, Figura 10).
<div align="center">
**Figuara 10**. Postman - Classificação nível manejo
</div>
![postman-get-classificacoes](uploads/0c95d0877a42be7a9b4b5b69ef4ef022/postman-get-classificacoes.png)
Após o envio da solicitação, se todas as informações enviadas no cabeçalho da requisição foram informadas corretamente (*Cf*. retângulo laranja, Figura 10) , a [`API Zarc-NM`](#api-zarc-nm) retorna o código [200 OK - HTTP Status ](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) informando que o recurso foi encontrado. No corpo da resposta é retornado o nível de manejo, a data e hora em que foi realizado o cálculo da classificação (*Cf*. retângulo amarelo, Figura 10). Se o usuário tentar consultar o resultado de uma classificação que ainda não foi finalizada, a [`API Zarc-NM`](#api-zarc-nm) retorna o código [404 Not Found - HTTP Status ](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404) indicando que o recurso foi encontrado
### 6. Lista de culturas
Para enviar os dados de uma determinada gleba/talhao (*Cf*. Subseção [`Envio de dados da gleba/talhão`](#2-envio-de-dados-da-glebatalhão)), é preciso informar as culturas cultivadas na gleba/talhão durante o período de três anos. Essa informação é adicionada no campo ***nome***, do objeto ***cultura*** presente na lista de ***producoes*** que compõe os dados da gleba/talhão (*Cf*. retângulo amarelo, Figura 7).
Para auxiliar o usuário na hora de adicionar essa informação, a [`API Zarc-NM`](#api-zarc-nm) disponibiliza uma lista com os nomes das culturas que ela aceita. Utilizando o [*Postman*](https://www.postman.com/), o usuário enviará uma requisição para a [`API Zarc-NM`](#api-zarc-nm) solicitando a lista de culturas. Para isso, clique em ***Culturas*** , seguidamente em ***GET Culturas - Listar*** (*Cf*. retângulo rosa, Figura 11) e faça uma requisição [HTTP](https://developer.mozilla.org/pt-BR/docs/Web/HTTP) utilizando o método [GET](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Methods/GET)
para a [`API Zarc-NM`](#api-zarc-nm), que que está disponível em: [www.zarcnm.cnptia.embrapa.br/zarcnm/culturas](https://www.zarcnm.cnptia.embrapa.br/zarcnm/culturas) (*Cf*. retângulo laranja, Figura 11).
<div align="center">
**Figuara 11**. Postman - Lista de culturas
</div>
![postman-get-culturas](uploads/fb4265b4166770d12075bec087d118c9/postman-get-culturas.png)
Após o envio da solicitação, se todas as informações enviadas no cabeçalho da requisição foram informadas corretamente (*Cf*. retângulo laranja, Figura 11), a [`API Zarc-NM`](#api-zarc-nm) retorna o código [200 OK - HTTP Status ](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) informando que o recurso foi encontrado. No corpo da resposta é retornada a lista contendo todos os nomes das culturas (*Cf*. retângulo amarelo, Figura 11).
## Dados contidos no *template* da *collection* disponibilazada
Para cada *endpoint* presente na *collection* [Endpoints API Zarcn-NM](https://www.gitlab.cnptia.embrapa.br/zarc-nivel-manejo/zarc-nm-docs/-/blob/main/postman/Endpoints%20API%20Zarc-NM.postman_collection.json?ref_type=heads), foi criado um *template* com informações irreais, com a finalidade apenas de testar o envio de dados e também exemplificar os dados e os tipos de dados que a [`API Zarc-NM`](#api-zarc-nm) recebe.
## Canais de comunicação
<!-- Disponibilizar os canais de comunicação com a equipe da Embrapa-->
Clone repository
  • Home