O que é a API do Shelly Cloud?

Modificado em Fri, 15 Mar em 12:28 PM

1. Resumo 


As APIs permitem que as pessoas/desenvolvedores interajam com serviços em nuvem e gerenciem recursos fornecidos por um provedor de nuvem (no nosso caso Shelly Cloud). 


DOCUMENTAÇÃO


2.  Características


Com a API do Shelly Cloud, por enquanto (19/06/23), pode fazer as seguintes coisas 


obter o estado atual do dispositivo

para relés: comutar cada saída individualmente 

para tampas: comandos de abrir/fechar/parar e definir uma posição

para luzes coloridas: ligar/desligar, atualizar a cor, atualizar o ganho para cada canal

para luzes brancas: ligar/desligar, atualizar a luminosidade para cada canal

grupos (vários relés ao mesmo tempo/com um único pedido): apenas relés de acordo com a documentação 

Suporta tipos de pedidos: 


GET - quando vai buscar informações ao servidor (não são necessárias alterações na base de dados): para obter o estado do dispositivo

POST - quando altera/carrega novos dados para a base de dados: para alterar o estado, a cor ou as definições de saída do dispositivo 

3.  Como utilizar


Os pedidos podem ser enviados através de muitos métodos como curl, postman, script python, script a correr no dispositivo Shelly e etc.


Como obter o estado mais recente do dispositivo via Shelly Cloud API e curl


Caminho: https://<***server_uri>/device/status 

Métodos suportados: GET e POST

Os parâmetros são fornecidos através da *query ou com o **body do pedido

Informações necessárias para enviar o pedido:

O ID do dispositivo de destino: key = 'id'

A conta ****authentication key: key = 'auth_key'

O resultado é um objeto JSON com o estado do dispositivo

Como controlar a saída de um dispositivo de relé:


Caminho: https://<***server_uri>/device/relay/control

Métodos suportados: POST

Os parâmetros são fornecidos APENAS através do **corpo do pedido

Informações necessárias para enviar o pedido:

O ID do dispositivo de destino: key = 'id'

A conta ****authentication key': key = 'auth_key'

O canal que deve ser atualizado: key = 'channel' (primeiro canal: 0 (dispositivos de canal único), segundo canal: 1)

O estado atualizado para a saída: key = 'turn' (valores suportados: ligado e desligado)

O resultado é um JSON com o ID do dispositivo de destino

Como abrir/fechar um dispositivo de persiana:


Caminho: https://<***server_uri>/device/relay/roller/control

Métodos suportados: POST

Os parâmetros são fornecidos APENAS através do **corpo do pedido

Informações necessárias para enviar o pedido:

O ID do dispositivo de destino: key = 'id'

A conta ****authentication key': key = 'auth_key'

O comando de direção: key = 'direction' (valores suportados: open, close e stop)

O resultado é um JSON com o ID do dispositivo de destino

Como definir uma posição para um dispositivo de persiana:


Caminho: https://<***server_uri>/device/relay/roller/control

Métodos suportados: POST

Os parâmetros são fornecidos APENAS através do **corpo do pedido

Informações necessárias para enviar o pedido:

O ID do dispositivo de destino: key = 'id'

A conta ****authentication key': key = 'auth_key'

Posição numa percentagem: key = 'pos' (valores suportados: todos os valores completos de 0 a 100 (inclusive))

O resultado é um JSON com o ID do dispositivo de destino

Como atualizar a saída do dispositivo de controlo de cores:


Caminho: https://<***server_uri>/device/light/control

Métodos suportados: POST

Os parâmetros são fornecidos APENAS através do **corpo do pedido

Informações necessárias para enviar o pedido:

O ID do dispositivo de destino: key = 'id'

A conta ****authentication key': key = 'auth_key'

O estado atualizado para a saída: key = 'turn' (valores suportados: on e off)

O valor para o canal branco: key= 'white' (valores suportados: todos os valores completos de 0 a 255 (inclusive))

O valor para o canal vermelho: key= 'red' (valores suportados: todos os valores completos de 0 a 255 (inclusive))

O valor para o canal verde: key= 'green' (valores suportados: todos os valores completos de 0 a 255 (inclusive))

O valor para o canal azul: key= 'blue' (valores suportados: todos os valores completos de 0 a 255 (inclusive))

O valor para o ganho: key= 'gain' (valores suportados: todos os valores completos de 0 a 100 (inclusive))

O resultado é um JSON com o ID do dispositivo de destino

Como atualizar a saída de um dispositivo de regulação da intensidade da luz:


Caminho: https://<***server_uri>/device/light/control

Métodos suportados: POST

Os parâmetros são fornecidos APENAS através do **corpo do pedido

Informações necessárias para enviar o pedido:

O ID do dispositivo de destino: key = 'id'

A conta ****authentication key': key = 'auth_key'

O estado atualizado para a saída: key = 'turn' (valores suportados: on e off)

O valor do brilho: key= 'brightness' (valores suportados: todos os valores completos de 0 a 100 (inclusive))

O resultado é um JSON com o ID do dispositivo de destino

 


*Consulta: Parâmetros localizados após o ponto final, começando com o símbolo de ponto de interrogação (?) e terminando com o símbolo de hashtag ou até ao fim do pedido. Os dados são formatados como pares chave=valor, em que a chave está antes do símbolo de igual (=) (ex. ivan=petyr, a chave é "ivan" e o valor é "petyr") e o valor está depois. Quando são necessários vários pares, deve separá-los com o símbolo and (&)


**corpo: Esta é a parte do pedido onde as informações sensíveis podem ser enviadas, ocultas do URL do pedido (não como a consulta).  Se utilizar curl para enviar o pedido, os dados do corpo são prefixados com '-d' e os parâmetros são escritos da mesma forma que a consulta como pares chave=valor e separados com o símbolo and


***server_uri: O URL do servidor onde estão localizados todos os dispositivos e contas do cliente. Pode ser obtido na aplicação Shelly > Definições do utilizador > Chave da nuvem de autorização


**** Chave de autenticação: A chave única que é gerada é baseada na palavra-passe da conta do cliente. Quando a palavra-passe é alterada, a chave de autenticação também é alterada