Integração com DAMS
Acesso e envio de leituras automatizadas
Essa seção tem como objetivo instruir os clientes do DAMS sobre o envio de dados de leituras automatizadas de instrumentos para a API da Fractal.
O endereço da API de produção para envio dos dados é:
https://hydrology.fractaleng.com.br/dam-readings/O endereço da API de homologação para envio dos dados é:
https://hy-homolog.fractaleng.com.br/dam-readings/
Os métodos GET e POST estão disponíveis para obter e salvar os dados, respectivamente. No POST, os dados devem ser enviados em um JSON, cujos campos estarão detalhados a seguir.
Headers: nas requisições HTTP será necessário enviar os headers Authorization e User-Agent. Para maiores informações, veja abaixo os tópicos Authorization e User-Agent.
Campos do JSON
A tabela a seguir apresenta os campos que compõem o JSON para envio de dados ao servidor, bem como os tipos de dados esperados, a informação que o campo representa e se o campo é ou não obrigatório. Caso falte algum campo obrigatório ou o tipo de dado enviado seja diferente do esperado, provavelmente ocorrerá um erro e os dados não serão salvos.
| Campo | Informação | Tipo | Obrigatório? |
|---|---|---|---|
| id_var | ID da variável | int | Sim |
| id_dam | ID da barragem | int | Sim |
| id_ins¹ | ID do instrumento | int | Não |
| instrument_name¹ | ID do instrumento | int | Não |
| reading_datetime | Data e hora da leitura | string | Sim |
| value² | Valor da leitura | float | Sim |
| id_uni³ | Id da unidade de medida | int | Não |
| unit_name³ | Sigla da unidade de medida | string | Não |
¹ Deve-se informar o identificador único do instrumento (id_ins) ou o nome do instrumento (instrument_name). Não é necessário informar ambos. Caso ambos sejam informados, o valor de id_ins vai ser considerado em detrimento ao valor de instrument_name. Além disso, há casos de leituras não associadas a instrumentos, como por exemplo, “nível de reservatório” e “nível de jusante”, quando tanto id_ins quanto instrument_name não devem ser preenchidos.
² Deve-se informar um valor numérico. Em caso de ser um valor decimal, a sua fração deve ser separada por ponto.
³ Deve-se informar o identificador único da unidade de medida (id_uni) ou o nome / abreviação da unidade de medida (unit_name). Não é necessário informar ambos. Caso ambos sejam informados, o valor de id_uni vai ser considerado em detrimento ao valor de unit_name.
Authorization
A API utiliza o header HTTP “Authorization” para autenticar o usuário que está enviando dados, por isso chamadas que não contenham um token válido serão recusadas pelo servidor (ver seção “Códigos de Erro – Problemas com envio de dados (POST)”.
O valor enviado no header deve ser "Basic " + funcao_base64_para_codificar ('<login> :<token>').
As imagens abaixo exemplificam o processo através da geração de um header fictício via um script em Python.
User-Agent
Além do header “Authorization” é necessário enviar o header “User-Agent” para que os sistemas de segurança da Fractal não bloqueiem as chamadas feitas ao servidor. Uma sugestão de valor para o header é “Mozilla/5.0 (compatible;)”
Variáveis
Esta tabela apresenta as principais variáveis do sistema, que indicam qual leitura está sendo feita por cada instrumento. O valor da coluna Id equivale ao campo id_var do JSON de envio de dados (POST) e de retorno de dados (GET).
Caso seja necessário dispor de outras possibilidades de variáveis, entre em contato com o setor de desenvolvimento da Fractal para maiores esclarecimentos.
| Id | Nome |
|---|---|
| 1 | Leitura 1 do instrumento (L1) |
| 2 | Leitura 2 do instrumento (L2), caso o instrumento tenha ao menos 2 leituras |
| 3 | Leitura 3 do instrumento (L3), caso o instrumento tenha ao menos 3 leituras |
| 4 | Leitura 4 do instrumento (L4), caso o instrumento tenha ao menos 4 leituras |
| 6 | Nível Do Reservatório |
| 33 | Nível De Jusante |
| 76 | Temperatura |
Unidades de medida
Esta tabela apresenta as unidades de medida do sistema e seus respectivos identificadores únicos (IDs) e siglas, que são necessários no envio de dados. O valor da coluna Id equivale ao campo id_uni e o valor da coluna Sigla equivale ao valor de unit_name do JSON de envio de dados (POST) e de retorno de dados (GET).
| Id | Unidade | Sigla |
|---|---|---|
| 1 | Metros | m |
| 2 | Centímetros | cm |
| 3 | Milímetros | mm |
| 4 | Kgf/cm² | Kgf/cm² |
| 5 | Metros Acima do Nível do Mar | manm |
| 6 | Litros/segundos | L/s |
| 7 | Graus | °C |
| 8 | MCA | mca |
| 9 | Microsiemens | µS |
| 10 | Milisiemens | mS |
| 11 | Microstrein | µE |
| 12 | Hertz | Hz |
| 13 | Microsegundo | µS |
| 14 | Quilograma força/centímetro cúbico | kgf/cm3 |
| 15 | Metros cúbicos/segundo | m³/s |
| 16 | Segundos | seg |
| 17 | Litros | L |
| 18 | Digits | Hz²x10-³ |
| 19 | Bar | BAR |
Códigos de Erro – Problemas no envio de dados
A tabela a seguir apresenta alguns dos erros mais frequentes ao enviar dados via API, além de explicar a causa provável e sugerir uma solução.
| Código HTTP | Causa provável | Correção |
|---|---|---|
| 400 | Falta de algum campo obrigatório no JSON ou tipo de dado incorreto | Ler mensagem de erro do objeto response para descobrir o que está errado |
| 401 | Falta do header “Authorization” | Adicionar o header à request |
| 403 | Header “Authorization” inválido | Conferir as credenciais utilizadas na geração do token |
| 500 | Instabilidade no servidor ou problemas no código | Se o problema persistir, entre em contato com a equipe de desenvolvimento da Fractal, enviando o JSON utilizado no envio dos dados |
Se o problema persistir, entre em contato com a equipe de desenvolvimento da Fractal, enviando o JSON utilizado no envio dos dados
Exemplos
Nesta seção será apresentado um exemplo de envio de dados via API.
A ferramenta utilizada para realizar as chamadas é a extensão “Thunder Client” do editor de texto “Visual Studio Code”.
O JSON para envio de dados possui um único campo chamado “data”, que recebe um array de leituras. Por isso, não é necessário fazer um POST para cada leitura, basta agrupá-las em um array e realizar uma única chamada. Cada POST pode receber até 300 leituras, retornando uma mensagem de erro caso esse limite seja ultrapassado.
Outro aspecto que merece destaque é que dois registros foram enviados nessa chamada, sendo que o primeiro utilizou os campos “id_ins” e “id_uni” para informar instrumento e unidade de medida, enquanto no segundo foram utilizados os campos “instrument_name” e “unit_name” para o mesmo propósito.
Acesso as campanhas do DAMS App
Este documento contém as especificações técnicas de acesso aos dados das campanhas feitas através do DAMS App e enviadas ao SIGA.
Utilização da API da Fractal
URL do endpoint da API da Fractal:
https://api.fractaleng.com.br/campaign-dataMétodo: GET
Headers: veja os tópicos Authorization e User-Agent para maiores informações.
Authorization
A API da Fractal utiliza o header HTTP Authorization para autenticar o usuário que está realizando as chamadas. Por isso chamadas que não contenham um header válido serão recusadas pelo servidor.
O valor enviado no header Authorization segue os padrões de HTTP Basic Authorization. Por isso, este cabeçalho deve ser conter “Basic <authorization>”, sendo <authorization> o resultado da codificação de <login>:<token>, conforme exemplo em Python a seguir.
User-Agent
Além do header “Authorization” é necessário enviar o header “User-Agent” para que os sistemas de segurança da Fractal não bloqueiem as chamadas feitas ao servidor. Uma sugestão de valor para o header é “ Mozilla/5.0 (compatible;)”
Resultados Esperados
A tabela a seguir apresenta os campos que compõem o JSON de resposta do GET descrito acima.
| Campo | Informação |
|---|---|
| owner | Cliente do DAMS |
| barragem | Apelido da barragem |
| data_nivel_reservatorio | Data de leitura do nível do reservatório, em formato timestamp |
| data_vazao_defluente | Data de leitura da vazão defluente, em formato timestamp |
| app_version | Versão do DAMS App utilizada na campanha |
| dados id | Identificador único do dado |
| nome_serviço | Nome completo da campanha (serviço + campanha) |
| type_equipo | Nome do tipo do instrumento lido |
| nome | Nome do instrumento |
| descricao | Descrição do instrumento |
| data | Data de envio da leitura do instrumento em formato timestamp |
| data_inicio_leitura | Data de leitura do nível do reservatório, em formato timestamp |
| nome_leiturista | Nome do leiturista |
| leitura_valor | Valor da leitura do primeiro campo do instrumento |
| leitura_p2_valor | Valor da leitura do segundo campo do instrumento, se houver |
| leitura_p3_valor | Valor da leitura do terceiro campo do instrumento, se houver |
| leitura_p4_valor | Valor da leitura do quarto campo do instrumento, se houver |
| observacoes | Observações feitas pelo leiturista |
| ocorrencias | Ocorrências indicadas pelo leiturista |
| manutencao | Manutenções indicadas pelo leiturista |
| manu_descricao | Descrição complementar das manutenções indicadas pelo leiturista |
| path_fotos | Campo interno do SIGA. Desconsidere este campo. |
| status_qr_code | Status do QR code indicado pelo leiturista |
| status_leitura | Status da leitura |
| posicao_x | Posição X (longitude) do instrumento |
| posicao_y | Posição Y (latitude) do instrumento |
| unidade_leitura_realizada | Unidade de medida da leitura realizada |
| forma_leitura_realizada | Forma da leitura realizada |
| n_fotos | Número de fotos enviadas com a campanha |
| data_nivel_jusante | Data de leitura do nível de jusante, em formato timestamp |
| nivel_reservatorio | Valor do nível do reservatório, em metros |
| vazao_afluente | Valor da vazão afluente, em m³/s |
| campanha | Nome da campanha |
| leiturista | Nome do leiturista |
| nivel_jusante | Valor do nível de jusante, em metros. |
| service | Nome completo da campanha (serviço + campanha) |
| supervisor_email | Email do supervisor do serviço |
| vazao_defluente | Valor da vazão defluente, em m³/s |
| data_vazao_afluente | Data de leitura da vazão afluente, em formato timestamp |
| data_campanha | Data de agendamento para a campanha, em formato timestamp |
| supervisor | Nome do supervisor |
Resultados Inesperados
A tabela a seguir apresenta o código de erro mais frequente ao buscar dados via API, além de explicar a causa provável e sugerir uma solução.
| Código HTTP | Causa provável | Correção |
|---|---|---|
| 401 | Usuário e/ou Token inválidos | Corrija as credenciais, conforme instruções da seção “Authorization” |
| 403 | Sem permissão para acessar e/ou executar chamada | Corrija as credenciais, conforme instruções da seção “Authorization” |
| 500 | Instabilidade no servidor ou problemas na montagem da chamada GET | Entre em contato com a equipe da Fractal para maiores informações |