Instruções para Download de Oscilografias via API RestFull, do SD+

Criada por Stephanye Martins, Modificado em Qua, 4 Out, 2023 na (o) 3:11 PM por Patrícia Siqueira


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:

1POST: {IP}/api/auth

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. 

Listagem de itens

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:

1 GET: {IP}/api/v1/oscillographs/sensors 

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:

1 GET: {IP}/api/v1/oscillographs/{sensors}

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 
0Oscilografia Ordinária: possui uma oscilografia de referência.
1Oscilografia Órfã: perdeu a oscilografia de referência.
2Oscilografia em aprendizado: nunca possuiu uma oscilografia de referência.
type
IDS/SDS
0Abertura
1Fechamento
2Indeterminado
IDX/SDX - Motor
-Não se aplica
IDX/SDX - Disjuntor
1Fechamento
2Abertura
3Fechamento/Abertura
IDM/SDM
0TAP simples
1TAP com 1 passo intermediário
2TAP com 2 passos intermediários
3TAP com 3 passos intermediários
4TAP 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:

1 GET: {IP}/api/v1/oscillographs/{sensors}/download/{uuid}

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:

1 GET: {IP}/api/v1/oscillographs/{sensors}/reference/{uuid}


Parâmetros
CampoTipoDescrição
sensorStringIdentificador da funcionalidade/IED para download.
uuidStringUUID da oscilografia para download.


Resposta - Sucesso (código 200)
CampoTipoDescrição
variablesArrayVariáveis relacionadas à referência.
nameStringNome do dado de medição.
crcIntegerCRC dos dados de medição.
dataArrayLista 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

Deixe-nos saber como podemos melhorar este artigo!

Selecione pelo menos um dos motivos
A verificação do CAPTCHA é obrigatória.

Feedback enviado

Agradecemos seu esforço e tentaremos corrigir o artigo