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.