Che cos'è Shelly Cloud API?

Modificato il Ven, 15 Mar alle 12:30 PM

1. Sintesi 


Le API consentono alle persone/sviluppatori di interagire con i servizi cloud e di gestire le risorse fornite da un provider cloud (nel nostro caso Shelly Cloud). 


DOCUMENTAZIONE


2.  Caratteristiche


Con l'API di Shelly Cloud, per il momento (6/19/23), può fare le seguenti cose: 


ottenere lo stato attuale del dispositivo

per i relè: commutare ogni uscita individualmente 

per le coperture: comandi di apertura/chiusura/arresto e impostazione di una posizione

per le luci a colori: accensione/spegnimento, aggiornamento del colore, aggiornamento del guadagno per ogni canale

per le luci bianche: accensione/spegnimento, aggiornamento della luminosità per ogni canale

gruppi (più relè contemporaneamente/con un'unica richiesta): solo relè come da documentazione 

Supporta i tipi di richiesta: 


GET - quando recupera informazioni dal server (non sono necessarie modifiche al database): per ottenere lo stato del dispositivo

POST - quando modifica/carica nuovi dati nel database: per modificare lo stato di uscita, il colore o le impostazioni del dispositivo. 

3.  Come utilizzare


Le richieste possono essere inviate tramite molti metodi come curl, postman, script python, script in esecuzione sul dispositivo Shelly e così via.


Come ottenere l'ultimo stato del dispositivo tramite Shelly Cloud API e curl


Percorso: https://<***server_uri>/dispositivo/stato 

Metodi supportati: GET e POST

I parametri sono forniti tramite la *query o con il **corpo della richiesta

Informazioni necessarie per inviare la richiesta:

L'ID del dispositivo di destinazione: chiave = 'id'

L'account **** chiave di autenticazione: key = 'auth_key'

Il risultato è un oggetto JSON con lo stato del dispositivo.

Come controllare l'uscita di un dispositivo relè:


Percorso: https://<***server_uri>/dispositivo/relay/controllo

Metodi supportati: POST

I parametri sono forniti SOLO attraverso il **corpo della richiesta

Informazioni necessarie per inviare la richiesta:

L'ID del dispositivo di destinazione: chiave = 'id'

L'account **** chiave di autenticazione': key = 'auth_key'

Il canale che deve essere aggiornato: key = 'channel' (primo canale: 0 (dispositivi a canale singolo), secondo canale: 1)

Lo stato aggiornato per l'uscita: key = 'turn' (valori supportati: on e off)

Il risultato è un JSON con l'ID del dispositivo di destinazione.

Come aprire/chiudere un dispositivo per tapparelle:


Percorso: https://<***server_uri>/device/relay/rullo/controllo

Metodi supportati: POST

I parametri sono forniti SOLO attraverso il **corpo della richiesta

Informazioni necessarie per inviare la richiesta:

L'ID del dispositivo di destinazione: chiave = 'id'

L'account ****authentication key': key = 'auth_key'

Il comando di direzione: key = 'direction' (valori supportati: open, close e stop)

Il risultato è un JSON con l'ID del dispositivo di destinazione.

Come impostare una posizione per un dispositivo per tapparelle:


Percorso: https://<***server_uri>/device/relay/rullo/controllo

Metodi supportati: POST

I parametri sono forniti SOLO attraverso il **corpo della richiesta

Informazioni necessarie per inviare la richiesta:

L'ID del dispositivo di destinazione: chiave = 'id'

L'account **** chiave di autenticazione': key = 'auth_key'

Posizione in percentuale: key = 'pos' (valori supportati: ogni valore completo da 0 a 100(incluso))

Il risultato è un JSON con l'ID del dispositivo di destinazione.

Come aggiornare l'uscita del dispositivo di controllo del colore:


Percorso: https://<***server_uri>/dispositivo/luce/controllo

Metodi supportati: POST

I parametri sono forniti SOLO attraverso il **corpo della richiesta

Informazioni necessarie per inviare la richiesta:

L'ID del dispositivo di destinazione: chiave = 'id'

L'account **** chiave di autenticazione': key = 'auth_key'

Lo stato aggiornato per l'uscita: key = 'turn' (valori supportati: on e off)

Il valore per il canale bianco: key= 'white' (valori supportati: ogni valore completo da 0 a 255 (incluso))

Il valore per il canale rosso: chiave= 'red' (valori supportati: ogni valore completo da 0 a 255 (incluso))

Il valore per il canale verde: chiave= 'verde' (valori supportati: ogni valore completo da 0 a 255 (incluso))

Il valore per il canale blu: chiave= 'blu' (valori supportati: ogni valore completo da 0 a 255 (incluso))

Il valore per il guadagno: chiave= 'gain' (valori supportati: ogni valore completo da 0 a 100 (incluso))

Il risultato è un JSON con l'ID del dispositivo di destinazione.

Come aggiornare l'uscita di un dispositivo di oscuramento:


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

Metodi supportati: POST

I parametri sono forniti SOLO attraverso il **corpo della richiesta

Informazioni necessarie per inviare la richiesta:

L'ID del dispositivo di destinazione: chiave = 'id'

L'account **** chiave di autenticazione': key = 'auth_key'

Lo stato aggiornato per l'uscita: key = 'turn' (valori supportati: on e off)

Il valore di luminosità: key= 'brightness' (valori supportati: ogni valore completo da 0 a 100 (incluso))

Il risultato è un JSON con l'ID del dispositivo target

 


*query: I parametri situati dopo l'endpoint iniziano con il simbolo del punto interrogativo (?) e terminano con il simbolo hashtag o fino alla fine della richiesta. I dati sono formattati come coppie chiave=valore, dove la chiave è prima del simbolo di uguale (=) (es. ivan=petyr, la chiave è "ivan" e il valore è "petyr") e il valore è dopo. Quando sono necessarie più coppie, devono essere separate con il simbolo e (&).


**Corpo: Questa è la parte della richiesta in cui possono essere inviate informazioni sensibili, nascoste dall'URL della richiesta (non come query).  Se utilizza curl per inviare la richiesta, i dati del corpo sono preceduti da '-d' e i parametri sono scritti come la query come coppie chiave=valore e separati con il simbolo e


***server_uri: l'URL del server in cui si trovano tutti i dispositivi e gli account del cliente. Questo può essere ottenuto dall'App Shelly > Impostazioni utente > Chiave cloud di autorizzazione


**** Chiave di autenticazione: Chiave di autenticazione che viene generata in base alla password dell'account del cliente. Quando la password viene modificata, anche la chiave di autenticazione viene modificata.