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.
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.