Este documento, também chamado guia, busca reunir informações sobre o uso da API, que está disponível nos equipamentos, exclusivos da Treetech, da linha SD com suporte ao download de oscilografias.
Importante:
⚠ Este guia serve para clientes que possuem equipamentos da linha SD com a funcionalidade de download de oscilografias, via API RESTfull, habilitada e autorizada; e buscam automatizar o seu sistema.
Tabela de erros:
Código de erro | Descrição | Solução |
401 | Erro na autenticação para geração de TOKEN. | Verifique se o usuário e senha estão devidamente autorizados. |
404 | Erro ao atender requisição: a funcionalidade da API está desabilitada ou os dados estão inválidos. | Certifique-se que a funcionalidade de API está habilitada e verifique se os dados passados na URL estão corretamente digitados. |
405 | Método utilizado para requisição não é permitido. | Verifique o método utilizado na requisição. |
500 | Ocorreu erro no servidor durante processo para gerar a resposta. | Reinicie o SD. Caso o erro persista, entre em contato com o suporte técnico da Treetech. |
Abreviações:
Abreviação | Descrição |
SD | Equipamentos Treetech com interface WEB(SD+, SDM, SDS, SDX) |
Download de oscilografia (v1)
A API de download de oscilografia provê interfaces para o usuário detectar quais oscilografias estarão disponíveis e quais poderão ser baixadas.
Será adotado, a fim de facilitar o entendimento, um padrão de documentação em tabelas (contendo informações do tipo do dado e descrição). Em alguns casos específicos serão apresentados testes realizados no software Postman para exemplificar o resultado esperado, em caso de sucesso.
Autenticação
Para ter acesso às funções de download o acesso deve ser autenticado por um TOKEN. Para gerar o TOKEN, o usuário deve realizar o login, passando, por meio do método POST (sintaxe a seguir), os valores das chaves descritas na tabela:
Chave | Descrição |
usr | Usuário |
pwd | Senha |
Sintaxe:
|
Resposta - Sucesso (código 200) | ||
Campo | Tipo | Descrição |
token | String | Chave de acesso |
Exemplo de BODY do POST de login:
1 { 2 "usr": "api", 3 "pwd": "api#2019" } |
Exemplo de retorno da request de login:
192.168.10.87/api/auth
1 { 2 "usr": "api", 3 "pwd": "api#2019" 4 } |
O TOKEN adquirido é do tipo Bearer e deve ser passado no HEADER de todas as próximas requisições abordadas neste guia, como no exemplo a seguir:
{ "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1NzIwMzI4MDgsImV4cCI6MTU3MjAzMzQwOH0 .9oul8H6ib-t_j9pnwdG_4ct62kwB5_hzowortrGPetU" } |
⚠ O TOKEN possui um tempo de expiração e deve ser renovado de tempos em tempos. O tempo de expiração do TOKEN é configurável via pagina web no menu Sistema > Acesso e possui uma faixa de 30 a 7200 segundos.
A lista de itens disponíveis no SD para download será gerada a partir desta funcionalidade.
Imagine que existam vários IEDs com oscilografias conectados à um SD+, deve-se primeiramente listar e identificar cada um deles para então exibir cada oscilografia por meio de seu UUID e finalmente realizar o download da escolhida.
Outro cenário seria no SDX, no qual existem dois tipos de oscilografia para download (Motor e Disjuntor), nesse caso deve-se fazer dois processos de download separados. Para exemplificar os comandos, na documentação considerou-se o cenário do SD+ com 2 IDMs.
⚠ O SD+ utilizado nos exemplos estava configurado com o endereço IP 192.168.10.87. No lugar deste IP deve ser utilizado o endereço IP do SD em questão.
Sintaxe:
|
Resposta - Sucesso (código 200) | ||
Campo | Tipo | Descrição |
id | String | Identificador da funcionalidade/IED para download |
- 192.168.10.87/api/v1/oscillographs/sensor
1 { 2 [ 3 { 4 "id": "IDM_T1" 5 }, 6 { 7 "id": "IDM_T2" 8 } 9 ] 10 } |
Status de download
Esta interface provê todas as informações para a tomada de decisão sobre qual oscilografia se deseja baixar, nela virão dados que informam a última oscilografia baixada (currentOscilography), número de voltas (currentLoop) que ocorreram na página, seguido da lista de oscilografias (list), identificadas pelo seu uuid.
⚠ Caso não conheça o funcionamento do processo de download de oscilografia, é importante saber que o IED possui uma quantidade finita de informações que podem ser salvas na memória. Quando ela atinge seu limite, é realizada uma reciclagem de dados armazenados, ou seja, a oscilografia mais antiga é substituída pela mais nova.
Sintaxe:
|
Parâmetros | ||
Campo | Tipo | Descrição |
sensor | String | Identificador da funcionalidade/IED para download. |
Resposta - Sucesso (código 200) | ||
Campo | Tipo | Descrição |
currentOscilography | Integer | Número da oscilografia atual |
currentLoop | Integer | Número atual de voltas no buffer. |
oscilographs | Array | Lista de oscilografia prostas para download. |
uuid | String | Identificador do item para download. |
dateTime | DateTime | Data e hora da gravação da oscilografia. |
class | Integer | Classe da Oscilografia. (Ver próxima tabela) |
type | Integer | Tipo da oscilografia. (Ver próxima tabela) |
number | Integer | Número da oscilografia. |
loop | Integer | Contador de voltas no buffer. |
Variável | Equipamento | Valor | Descrição |
class | IDS/SDS, IDX/SDX, IDM/SDM | 0 | Oscilografia Ordinária: possui uma oscilografia de referência. |
1 | Oscilografia Órfã: perdeu a oscilografia de referência. | ||
2 | Oscilografia em aprendizado: nunca possuiu uma oscilografia de referência. | ||
type | IDS/SDS | 0 | Abertura |
1 | Fechamento | ||
2 | Indeterminado | ||
IDX/SDX - Motor | - | Não se aplica | |
IDX/SDX - Disjuntor | 1 | Fechamento | |
2 | Abertura | ||
3 | Fechamento/Abertura | ||
IDM/SDM | 0 | TAP simples | |
1 | TAP com 1 passo intermediário | ||
2 | TAP com 2 passos intermediários | ||
3 | TAP com 3 passos intermediários | ||
4 | TAP com 4 passos intermediários |
Exemplo de retorno da request de status do IDM_T2 no SD+:
- 192.168.10.87/api/v1/oscillographs/IDM_T2
1 { 2 "currentOscilography": "10", 3 "currentLoop": "1", 4 "oscillographs": [ 5 { 6 "uuid": "55141_46551_12761_11776_123_456", 7 "dateTime": "2019-10-03 07:17:01", 8 "class": "0", 9 "type": "4", 10 "number": "6", 11 "loop": "1" 12 }, 13 { 14 "uuid": "29346_46960_35470_26232_123_456", 15 "dateTime": "2019-10-03 07:17:01", 16 "class": "0", 17 "type": "4", 18 "number": "7", 19 "loop": "1" 20 }, 21 { 22 "uuid": "3552_47381_58180_40688_123_456", 23 "dateTime": "2019-10-03 07:14:01", 24 "class": "0", 25 "type"4", 26 "number": "8", 27 "loop": "1" 28 }, 29 { 30 "uuid": "43291_47772_15352_55144_123_456", 31 "dateTime": "2019-10-03 07:14:01", 32 "class": "0", 33 "type": "4", 34 "number": "9", 35 "loop": "1" 36 }, 37 { 38 "uuid": "17500_48215_38063_4064_123_456", 39 "dateTime": "2019-10-03 07:10:01", 40 "class": "0", 41 "type": "4", 42 "number": "10", 43 "loop": "1" 44 } 45 ] 46 } |
Baixar uma oscilografia
Nesta etapa deve-se incluir na URL (além do id já utilizado na função de Status) o uuid da oscilografia desejada para download.
Sintaxe:
|
Parâmetros | ||
Campo | Tipo | Descrição |
sensor | String | Identificador da funcionalidade/IED para download. |
uuid | String | UUID da oscilografia para download. |
Resposta - Sucesso (código 200) | ||
Campo | Tipo | Descrição |
uuidRef | String | UUID da oscilografia de referência. |
aditionalVariables | Array | Variáveis adicionais relacionadas à manobra. |
name | String | Nome da variável auxiliar. |
data | String | Valor do dado. |
variables | Array | Variáveis relacionadas à manobra. |
name | String | Nome do dado de medição. |
crc | Integer | CRC dos dados de medição. |
data | Array | Lista de leituras dos dados de medição. |
Exemplo de retorno da request de download por meio do UUID de uma oscilografia do IDM_T2 no SD+:
- 192.168.10.87/api/v1/oscillographs/IDM_T2/dowload/55141_46551_12761_11776_123_456
1 { 2 "uuidRef": "13393_44987_7630_49416_123_456", 3 "aditionalVariables": { 4 "info": [ 5 { 6 "name": "STATUS", 7 "data": "0" 8 }, 9 { 10 "name": "OSMTTI", 11 "data": "0" 12 } 13 ], 14 "configAlarm": [ 15 { 16 "name": "MTIPA", 17 "data": "0.0" 18 } 19 ], 20 "alarm": [ 21 { 22 "name": "VMTMBAL", 23 "data": "0" 24 } 25 ], 26 "other": [ 27 { 28 "name": "ERROS", 29 "data": "0" 30 } 31 ] 32 }, 33 "variables": [ 34 { 35 "name": "MTAS", 36 "crc": "61628", 37 "data": [ 38 "0.0", 39 "503.9", 40 "503.9", 41 "503.9", 42 "503.9", 43 "503.9", 44 "503.9", 45 "503.9", 46 "503.9", 47 "503.9", 48 "503.9", 49 "503.9", 50 "503.9", 51 "503.9", 52 "503.9", 53 "503.9", 54 "503.9", 55 "503.9", 56 "503.9", 57 "503.9", 58 "503.9", 59 "503.9", 60 "503.9", 61 "503.9", 62 "503.9", 63 "503.9", 64 "503.9", 65 "503.9", 66 "503.9", 67 "503.9", 68 ] 69 }, 70 { 71 "name": "PFMT", 72 "crc": "44262", 73 "data": [ 74 "0.000", 75 "0.999", 76 "0.999", 77 "0.999", 78 "0.999", 79 "0.999", 80 "0.999", 81 "0.999", 82 "0.999", 83 "0.999", 84 "0.999", 85 "0.999", 86 "0.999", 87 "0.999", 88 "0.999", 89 "0.999", 90 "0.999", 91 "0.999", 92 "0.999", 93 "0.999", 94 "0.999", 95 "0.999", 96 "0.999", 97 "0.999", 98 "0.999", 99 "0.999", 100 "0.999", 101 "0.999", 102 "0.999", 103 "0.999", 104 "0.999", 105 "0.999", 106 "0.999", 107 "0.999", 108 "0.999", 109 "0.999", 110 ] 111 } 112 ] 113 } |
Baixar uma oscilografia de referência
Nesta etapa deve-se identificar o tipo de oscilografia - conforme seu identificador (ID) - e também o ID da oscilografia de referência.
Sintaxe:
|
Parâmetros | ||
Campo | Tipo | Descrição |
sensor | String | Identificador da funcionalidade/IED para download. |
uuid | String | UUID da oscilografia para download. |
Resposta - Sucesso (código 200) | ||
Campo | Tipo | Descrição |
variables | Array | Variáveis relacionadas à referência. |
name | String | Nome do dado de medição. |
crc | Integer | CRC dos dados de medição. |
data | Array | Lista de leituras dos dados de medição. |
Exemplo de retorno da request de download por meio do UUID de uma oscilografia de Referência do IDM_T2 no SD+:
- 192.168.10.87/api/v1/oscillographs/IDM_T2/reference/46344_50127_15185_16879_123_456
1 { 2 "variables": [ 3 { 4 "name": "MTASMED", 5 "crc": "9184", 6 "data": [ 7 "0.0", 8 "509.0", 9 "509.0", 10 "508.6", 11 "508.6", 12 "508.6", 13 "508.6", 14 "508.6", 15 "508.6", 16 "504.3", 17 "504.3", 18 "504.3", 19 "504.3", 20 "504.3", 21 "504.3", 22 "504.3", 23 "508.6", 24 "508.6", 25 "508.6", 26 "504.7", 27 "504,3", 28 "504.3", 29 "504.3", 30 "504.3", 31 "504.7", 32 "508.6", 33 "508.6", 34 "508.6", 35 "509.0", 36 "0.0", 37 "509.0", 38 "0.0", 39 "509.0", 40 "0.0", 41 "508.6", 42 "0.0", 43 "508.6", 44 "502.3", 45 "509.0", 46 "208.9", 47 "509.0", 48 "158.4", 49 "508.6", 50 "508.6", 51 "504.7", 52 "478.6", 53 "478.6", 54 "479.0", 55 "504.7", 56 "477.6", 57 "101.9", 58 "503.9", 59 "503.9", 60 "99.9", 61 "504.3", 62 "0.0", 63 "468.7", 64 "363.0", 65 "259.8", 66 "181.0", 67 "122.2", 68 "79.0", 69 "0.0" 70 ] 71 }, 72 { 73 "name": "MTASMIN", 74 "crc": "9184", 75 "data": [ 76 "0.0", 77 "0.0", 78 "0.0", 79 "509.0", 80 "508.6", 81 "508.6", 82 "508.6", 83 "508.6", 84 "508.6", 85 "508.6", 86 "504.3", 87 "504.3", 88 "504.3", 89 "504.3", 90 "504.3", 91 "504.3", 92 "504.3", 93 "508.6", 94 "508.6", 95 "508.6", 96 "504.7", 97 "504.3", 98 "504.3", 99 "504.3", 100 "504.3", 101 "504.7", 102 "508.6", 103 "508.6", 104 "508.6", 105 "509.0", 106 "0.0" 107 ] 108 }, 109 { 110 "name": "MTASA", 111 "crc": "59835", 112 "data": [ 113 "0.0", 114 "0.0", 115 "0.0", 116 "0.0", 117 "0.0", 118 "0.0", 119 "0.0", 120 "0.0", 121 "0.0", 122 "0.0", 123 "605.6", 124 "605.6", 125 "605.6", 126 "605.1", 127 "605.1", 128 "605.1", 129 "605.1", 130 "605.1", 131 "605.1", 132 "562.4", 133 "562.4", 134 "435.6", 135 "311.7", 136 "217.2", 137 "146.6", 138 "605.6", 139 "605.6", 140 "605.6", 141 "605.1", 142 "605.1", 143 "605.1", 144 "605.1", 145 "605.1", 146 "605.1", 147 "562.4", 148 "562.4", 149 "435.6", 150 "311.7", 151 "217.2", 152 "146.6", 153 "94.8", 154 "61.0", 155 "36.6", 156 "0.0" 157 ] 158 } 159 ] 160 } |
Caso haja algum problema ou tenha alguma dificuldade com o procedimento, não hesite em entrar em contato!
Contatos:
Telefone: +55 (11) 2410 – 1190 — Ramal: 425
Celular: +55 (11) 97225 – 8683 - WhatsApp
Email: sac@treetech.com.br
Portal de Atendimento
Este artigo foi útil?
Que bom!
Obrigado pelo seu feedback
Desculpe! Não conseguimos ajudar você
Obrigado pelo seu feedback
Feedback enviado
Agradecemos seu esforço e tentaremos corrigir o artigo