Was ist Shelly Cloud API?

Geändert am Fr, 15 Sep, 2023 um 10:01 VORMITTAGS





1. Zusammenfassung 

 

Die APIs ermöglichen es Personen/Entwicklern, mit Cloud-Diensten zu interagieren und Ressourcen zu verwalten, die von einem Cloud-Anbieter (in unserem Fall Shelly Cloud) bereitgestellt werden. 

 

DOKUMENTATION

 

2.  Funktionen

 

Mit der Shelly Cloud API können Sie zum jetzigen Zeitpunkt (19.6.23) die folgenden Dinge tun:  

  • den aktuellen Status des Geräts abfragen
  • bei Relais: jeden Ausgang einzeln schalten 
  • für Abdeckungen/Rollos: Befehle zum Öffnen/Schließen/Stoppen und Festlegen einer Position
  • für Farblichter: ein/aus, Farbe aktualisieren, Helligkeit/Verstärkung für jeden Kanal ändern
  • für weißes Licht: ein/aus, Helligkeit/Verstärkung für jeden Kanal ändern
  • Gruppen (mehrere Relais gleichzeitig/mit einer einzigen Anforderung): nur Relais gemäß der Dokumentation 

 Unterstützung von Anfragetypen:  

  • GET - beim Abrufen von Informationen vom Server (es sind keine Änderungen an der Datenbank erforderlich): zum Abrufen des Gerätestatus
  • POST - beim Ändern/Hochladen neuer Daten in die Datenbank: zum Ändern des Ausgangszustands, der Farbe oder der Einstellungen des Geräts

 

3.  Wie wird es verwendet?

 

Anfragen können über viele Methoden wie curl, postman, Python-Skript, Skript, das auf dem Shelly-Gerät läuft, usw. gesendet werden.

 

So erhalten Sie den aktuellen Status des Geräts über Shelly Cloud API und curl

 

  •     Pfad: https://<***server_uri>/device/status 
  •     Unterstützte Methoden: GET und POST
  •     Parameter werden über die *query oder mit dem **body der Anfrage übergeben
  •     Erforderliche Informationen zum Senden der Anfrage:

-Die ID des Zielgeräts: key = 'id'

-Der Konto ****Authentifizierungsschlüssel: key = 'auth_key'

  •     Das Ergebnis ist ein JSON-Objekt mit dem Status des Geräts

 

So steuern Sie die Ausgabe für ein Relaisgerät:

 

  •     Pfad: https://<***server_uri>/device/relay/control
  •     Unterstützte Methoden: POST
  •     Parameter werden NUR über den **Body der Anfrage übergeben
  •     Erforderliche Informationen zum Senden der Anfrage:

-Die ID des Zielgeräts: key = 'id'

-Das Konto ****authentication key': key = 'auth_key' 

-Der Kanal, der aktualisiert werden soll: key = 'channel' (erster Kanal: 0 (Einkanalgeräte), zweiter              Kanal: 1)

-Der aktualisierte Zustand für den Ausgang: key = 'turn' (unterstützte Werte: on und off)

  •     Das Ergebnis ist ein JSON mit der Zielgeräte-ID

 

So öffnen/schließen Sie einen Rollladen:

 

  •     Pfad: https://<***server_uri>/device/relay/roller/control
  •     Unterstützte Methoden: POST
  •     Parameter werden NUR über den **Body der Anfrage übergeben
  •     Erforderliche Informationen zum Senden der Anfrage:

-Die ID des Zielgeräts: key = 'id'

-Das Konto ****authentication key': key = 'auth_key'

-Der Richtungsbefehl: key = 'direction' (unterstützte Werte: open, close und stop)

  •     Das Ergebnis ist ein JSON mit der Zielgeräte-ID

 

So setzen Sie eine Position für ein Rollladen:

 

  •     Pfad: https://<***server_uri>/device/relay/roller/control
  •     Unterstützte Methoden: POST
  •     Parameter werden NUR über den **Body der Anfrage übergeben
  •     Erforderliche Informationen zum Senden der Anfrage:

-Die ID des Zielgeräts: key = 'id'

-Das Konto ****authentication key': key = 'auth_key'

-Position in Prozent: key = 'pos' (unterstützte Werte: jeder volle Wert von 0 bis 100(inklusive))

  •     Das Ergebnis ist ein JSON mit der Zielgeräte-ID

 

Wie aktualisiert man die Ausgabe eines Farbsteuerungsgeräts?

 

  •     Pfad: https://<***server_uri>/device/light/control
  •     Unterstützte Methoden: POST
  •     Parameter werden NUR über den **Body der Anfrage übergeben
  •     Erforderliche Informationen zum Senden der Anfrage:

-Die ID des Zielgeräts: key = 'id'

-Das Konto ****authentication key': key = 'auth_key'

-Der aktualisierte Status für den Ausgang: key = 'turn' (unterstützte Werte: on und off)

-Der Wert für den weißen Kanal: key= 'white' (unterstützte Werte: jeder volle Wert von 0 bis 255              (einschließlich))

-Der Wert für den roten Kanal: key= 'red' (unterstützte Werte: jeder volle Wert von 0 bis 255                         (einschließlich))

 -Der Wert für den Grün-Kanal: key= 'green' (unterstützte Werte: jeder volle Wert von 0 bis 255          (einschließlich))

-Der Wert für den Blau-Kanal: key= 'blue' (unterstützte Werte: jeder volle Wert von 0 bis 255                         (einschließlich))

-Der Wert für die Helligkeit/Verstärkung: key= 'gain' (unterstützte Werte: jeder volle Wert von 0 bis            100 (einschließlich))

  •     Das Ergebnis ist ein JSON mit der Zielgeräte-ID

 

So aktualisieren Sie den Ausgang eines Dimmgeräts:

 

  •     Pfad: https://<***server_uri>/device/light/control
  •     Unterstützte Methoden: POST
  •     Parameter werden NUR über den **Body der Anfrage übergeben
  •     Erforderliche Informationen zum Senden der Anfrage:

-Die ID des Zielgeräts: key = 'id'

-Das Konto ****authentication key': key = 'auth_key'

-Der aktualisierte Status für den Ausgang: key = 'turn' (unterstützte Werte: on und off)

-Der Helligkeitswert: key= 'brightness' (unterstützte Werte: jeder volle Wert von 0 bis 100                    (einschließlich))

  •     Das Ergebnis ist ein JSON mit der Zielgeräte-ID

 

*query: Die Parameter nach dem Endpunkt beginnen mit dem Fragezeichensymbol (?) und enden mit dem Hashtag-Symbol oder bis zum Ende der Anfrage. Die Daten werden als Schlüssel=Wert-Paare formatiert, wobei der Schlüssel vor dem Gleichheitszeichen (=) steht (z. B. ivan=petyr, der Schlüssel ist "ivan", und der Wert ist "petyr") und der Wert danach. Wenn mehrere Paare benötigt werden, müssen sie mit dem Und-Symbol (&) getrennt werden

**body: Dies ist der Teil der Anfrage, in dem sensible Informationen gesendet werden können, die in der Anfrage-URL verborgen sind (nicht in der Abfrage).  Wenn Sie curl zum Senden der Anfrage verwenden, wird den Body-Daten ein '-d' vorangestellt, und die Parameter werden wie die Abfrage als Schlüssel=Wert-Paare geschrieben und mit dem Symbol und getrennt

***server_uri: Die URL des Servers, auf dem sich alle Geräte und Konten des Kunden befinden. Diese kann in der Shelly App > Benutzereinstellungen > Autorisierungswolkenschlüssel abgefragt werden

**** authentication key: Einzigartiger Schlüssel, der auf der Grundlage des Passworts für das Kundenkonto generiert wird. Wenn das Passwort geändert wird, wird auch der Authentifizierungsschlüssel geändert.