|
|
<!-- 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:
|
|
|
|
|
|

|
|
|
|
|
|
|
|
|
## 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:**
|
|
|
|
|
|

|
|
|
|
|
|
</br>
|
|
|
|
|
|
**Visão Arquitetural da API ZARC-NM:**
|
|
|
|
|
|

|
|
|
|
|
|
## 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
|
|
|
|
|
|

|
|
|
|
|
|
Obtendo o token de acesso após validação das credencias
|
|
|
|
|
|

|
|
|
|
|
|
Enviando uma requisição a API do ZarcNM
|
|
|
|
|
|

|
|
|
|
|
|
Verificando a autenticidade e valdidade do token de acesso
|
|
|
|
|
|

|
|
|
|
|
|
Resposta da requisição enviada pela aplicação cliente
|
|
|
|
|
|

|
|
|
|
|
|
### 2. Envio de dados de identificação da gleba, histórico de cultivos e operaçõe de manejo
|
|
|
|
|
|

|
|
|
|
|
|
</br>
|
|
|
|
|
|
### 3. Envio de dados de amostras de solo
|
|
|
|
|
|

|
|
|
|
|
|
</br>
|
|
|
|
|
|
### 4. Envio de dados de sensoriamento remoto
|
|
|
|
|
|

|
|
|
|
|
|
</br>
|
|
|
|
|
|
### 5. Consulta à classificação final de nível de manejo
|
|
|
|
|
|

|
|
|
|
|
|
## 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>
|
|
|
|
|
|

|
|
|
|
|
|
Seguidamente escolha a alternativa ***files*** e selecione o arquivo (*Cf*. retângulo vermelho, Figura 2).
|
|
|
|
|
|
|
|
|
<div align="center">
|
|
|
|
|
|
**Figura 2**. Postman - Import files
|
|
|
|
|
|

|
|
|
|
|
|
</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>
|
|
|
|
|
|

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

|
|
|
|
|
|
Logo após, clique no botão ***Proceed*** (*Cf*. retângulo amarelo, Figura 5)
|
|
|
|
|
|
<div align="center">
|
|
|
|
|
|
**Figuara 5**. Get new access token - Proceed
|
|
|
|
|
|

|
|
|
|
|
|
</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
|
|
|
|
|
|

|
|
|
|
|
|
</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>
|
|
|
|
|
|

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

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

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

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

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