1. Podsumowanie
Interfejsy API umożliwiają użytkownikom/programistom interakcję z usługami w chmurze i zarządzanie zasobami dostarczanymi przez dostawcę chmury (w naszym przypadku Shelly Cloud).
2. Funkcje
Za pomocą Shelly Cloud API na chwilę obecną (6/19/23) można wykonać następujące czynności:
- uzyskać aktualny status urządzenia
- dla przekaźników: przełączać każde wyjście indywidualnie
- dla pokryw: polecenia otwierania/zamykania/zatrzymywania i ustawianie pozycji
- dla kolorowych świateł: włącz/wyłącz, zaktualizuj kolor, zaktualizuj wzmocnienie dla każdego kanału
- dla białych świateł: włączanie/wyłączanie, aktualizacja jasności dla każdego kanału
- grupy (wiele przekaźników w tym samym czasie / z jednym żądaniem): tylko przekaźniki zgodnie z dokumentacją
Obsługiwane typy żądań:
- GET - podczas pobierania informacji z serwera (nie są wymagane żadne zmiany w bazie danych): w celu uzyskania statusu urządzenia
- POST - przy zmianie/wgrywaniu nowych danych do bazy danych: do zmiany stanu wyjścia urządzenia, koloru lub ustawień.
3. Jak używać
Żądania mogą być wysyłane za pomocą wielu metod, takich jak curl, postman, skrypt Pythona, skrypt uruchomiony na urządzeniu Shelly itp.
Jak uzyskać najnowszy status urządzenia za pomocą Shelly Cloud API i curl
- Ścieżka: https://<***server_uri>/device/status
- Obsługiwane metody: GET i POST
- Parametry są dostarczane za pośrednictwem *query lub **body żądania
- Wymagane informacje do wysłania żądania:
- Identyfikator urządzenia docelowego: key = 'id'
- Klucz uwierzytelniania konta ****: key = 'auth_key'
- Wynikiem jest obiekt JSON ze statusem urządzenia.
Jak kontrolować wyjście dla urządzenia przekaźnikowego:
- Ścieżka: https://<***server_uri>/device/relay/control
- Obsługiwane metody: POST
- Parametry są dostarczane TYLKO za pośrednictwem **body żądania
- Wymagane informacje do wysłania żądania:
- Identyfikator urządzenia docelowego: key = 'id'
- Konto ****-klucz_uwierzytelniający: key = 'auth_key'
- Kanał, który powinien zostać zaktualizowany: key = 'channel' (pierwszy kanał: 0 (urządzenia jednokanałowe), drugi kanał: 1)
- Zaktualizowany stan wyjścia: key = 'turn' (obsługiwane wartości: on i off)
- Wynikiem jest JSON z identyfikatorem urządzenia docelowego
Jak otworzyć/zamknąć urządzenie roletowe:
- Ścieżka: https://<***server_uri>/device/relay/roller/control
- Obsługiwane metody: POST
- Parametry są dostarczane TYLKO za pośrednictwem **body żądania
- Wymagane informacje do wysłania żądania:
- Identyfikator urządzenia docelowego: key = 'id'
- Konto ****klucz uwierzytelniania": key = ”auth_key
- Polecenie kierunku: key = 'direction' (obsługiwane wartości: open, close i stop)
- Wynikiem jest JSON z identyfikatorem urządzenia docelowego
Jak ustawić pozycję dla urządzenia roletowego:
- Ścieżka: https://<***server_uri>/device/relay/roller/control
- Obsługiwane metody: POST
- Parametry są dostarczane TYLKO za pośrednictwem **body żądania
- Wymagane informacje do wysłania żądania:
- Identyfikator urządzenia docelowego: key = 'id'
- Konto ****-klucz_uwierzytelniający: key = 'auth_key'
- Pozycja w procentach: key = 'pos' (obsługiwane wartości: każda pełna wartość od 0 do 100(włącznie))
- Wynikiem jest JSON z identyfikatorem urządzenia docelowego
Jak zaktualizować wyjście urządzenia sterującego kolorem :
- Ścieżka: https://<***server_uri>/device/light/control
- Obsługiwane metody: POST
- Parametry są dostarczane TYLKO za pośrednictwem **body żądania
- Wymagane informacje do wysłania żądania:
- Identyfikator urządzenia docelowego: key = 'id'
- Konto ****-klucz uwierzytelniający: key = 'auth_key'
- Zaktualizowany stan wyjścia: key = 'turn' (obsługiwane wartości: on i off)
- Wartość dla kanału białego: key= 'white' (obsługiwane wartości: każda pełna wartość od 0 do 255 (włącznie))
- Wartość dla kanału czerwonego: key= 'red' (obsługiwane wartości: każda pełna wartość od 0 do 255 (włącznie))
- Wartość dla kanału zielonego: key= 'green' (obsługiwane wartości: każda pełna wartość od 0 do 255 (włącznie))
- Wartość dla kanału niebieskiego: key= 'blue' (obsługiwane wartości: każda pełna wartość od 0 do 255 (włącznie))
- Wartość wzmocnienia: key=„gain” (obsługiwane wartości: każda pełna wartość od 0 do 100 (włącznie))
- Wynikiem jest JSON z identyfikatorem urządzenia docelowego
Jak zaktualizować wyjście urządzenia ściemniającego :
- Ścieżka: https://<***server_uri>/device/light/control
- Obsługiwane metody: POST
- Parametry są dostarczane TYLKO za pośrednictwem **body żądania
- Wymagane informacje do wysłania żądania:
- Identyfikator urządzenia docelowego: key = 'id'
- Konto ****-klucz uwierzytelniający: key = 'auth_key'
- Zaktualizowany stan wyjścia: key = 'turn' (obsługiwane wartości: on i off)
- Wartość jasności: key= 'brightness' (obsługiwane wartości: każda pełna wartość od 0 do 100 (włącznie))
- Wynikiem jest JSON z identyfikatorem urządzenia docelowego
*query: Parametry znajdujące się po punkcie końcowym rozpoczynającym się symbolem znaku zapytania (?) i kończącym się symbolem hashtagu lub do końca żądania. Dane są sformatowane jako pary klucz=wartość, gdzie klucz znajduje się przed symbolem równości (=) (np. ivan=petyr, klucz to „ivan”, a wartość to „petyr”), a wartość znajduje się po nim. Gdy potrzebnych jest wiele par, należy je oddzielić symbolem i (&)
**body: Jest to część żądania, w której mogą być wysyłane poufne informacje, ukryte przed adresem URL żądania (nie jako zapytanie). Jeśli do wysłania żądania używany jest curl, dane body są poprzedzone „-d”, a parametry są zapisywane tak samo jak zapytanie jako pary klucz=wartość i oddzielone symbolem and.
***server_uri: Adres URL serwera, na którym znajdują się wszystkie urządzenia i konta klienta. Można go uzyskać z aplikacji Shelly > Ustawienia użytkownika > Klucz chmury autoryzacji
****Klucz uwierzytelniający: Niejawny klucz, który jest generowany na podstawie hasła do konta klienta. Po zmianie hasła zmieniany jest również klucz autoryzacji