Skip to content

REST API — sceny

Sceny uruchamiają zapisane w instalacji zestawy poleceń. REST API pozwala uruchomić albo zatrzymać istniejącą scenę. Numer sceny odczytaj w aplikacji mobilnej: id musi być liczbą całkowitą w zakresie 0–1999. Sam poprawny zakres nie potwierdza istnienia sceny. API nie udostępnia listy, konfiguracji ani bieżącego statusu scen.

Najpierw skonfiguruj dostęp według Rozpoczęcia pracy. W przykładach zastąp ADRES_SERWERA, PORT i KLUCZ_API adresem instalacji, portem HTTPS i kluczem z panelu. Numer 12 jest fikcyjny; zastąp go numerem istniejącej sceny. Ścieżki metod są względne wobec /integrations/api.

Obie opisane metody GET zmieniają stan instalacji. Wywołuj je świadomie jako polecenia. Nie używaj ich adresów do odpytywania stanu ani automatycznego odświeżania. Skutki ponawiania i utraty odpowiedzi opisano poniżej.

Uruchomienie: GET /scene/start

Uruchamia polecenia zapisane w scenie. Parametry query to wartości dopisywane do adresu po ?; kolejne oddziela się znakiem &. Metoda nie wymaga body, czyli treści żądania.

Parametr Wymaganie Znaczenie
id Wymagany, liczba całkowita 0–1999 Numer istniejącej sceny z aplikacji mobilnej.
time Opcjonalny, nieujemna liczba całkowita Czas podtrzymania w sekundach.

Wybór czasu

Wariant Działanie
Pominięte time Używa czasu domyślnego zapisanego w scenie.
time=0 Wykonuje polecenia bez ustanawiania nowego podtrzymania.
Dodatnie time, np. time=3600 Podtrzymuje nastawy temperatury przez wskazany czas, w przykładzie przez godzinę. Maksymalny czas to 5 356 800 s, czyli 62 dni.

Podtrzymanie oznacza utrzymywanie nastaw przez scenę; obecnie dotyczy nastaw temperatury. Nie jest czasem, po którym wszystkie działania sceny zostaną automatycznie cofnięte. Upływ czasu kończy podtrzymanie, bez wysyłania poleceń przeciwnych do wszystkich wcześniej wykonanych działań. Polecenia opóźnione są wykonywane według opóźnień zapisanych w scenie; time nie zastępuje tych opóźnień.

time=0 nie usuwa wcześniejszego podtrzymania aktywnej sceny. Do usunięcia podtrzymań i oczekujących poleceń opóźnionych służy GET /scene/stop opisane poniżej.

W integracji stosuj czas najwyżej 5 356 800 s. Większa liczba jest zwykle ograniczana do tego maksimum, więc nie oczekuj gwarantowanego błędu HTTP ani statusu invalid_time po samym przekroczeniu limitu.

Przykład z czasem domyślnym

Żądanie HTTP bez parametru time:

GET /integrations/api/scene/start?id=12 HTTP/1.1
Host: ADRES_SERWERA:PORT
Authorization: Bearer KLUCZ_API

To samo żądanie w curl; --include pokazuje również nagłówki odpowiedzi:

curl --include --request GET \
  'https://ADRES_SERWERA:PORT/integrations/api/scene/start?id=12' \
  --header 'Authorization: Bearer KLUCZ_API'

Przykładowa odpowiedź z pełnym body w formacie JSON, czyli tekstowym formacie danych:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"logic_action":"on_scene","status":"ok"}

logic_action: "on_scene" identyfikuje wynik uruchomienia. status: "ok" oznacza przyjęcie polecenia uruchomienia sceny; nie potwierdza wykonania wszystkich działań przez fizyczne urządzenia ani zakończenia poleceń opóźnionych. Sprawdzaj body odpowiedzi razem z kodem HTTP.

Pozostałe warianty czasu

Każdy poniższy przykład jest osobnym poleceniem. Wybierz wariant odpowiadający zamierzonemu działaniu; nie wykonuj wszystkich kolejno w celu sprawdzenia dostępu.

Uruchomienie bez nowego podtrzymania:

curl --include --request GET \
  'https://ADRES_SERWERA:PORT/integrations/api/scene/start?id=12&time=0' \
  --header 'Authorization: Bearer KLUCZ_API'

Uruchomienie z godzinnym podtrzymaniem nastaw temperatury:

curl --include --request GET \
  'https://ADRES_SERWERA:PORT/integrations/api/scene/start?id=12&time=3600' \
  --header 'Authorization: Bearer KLUCZ_API'

Przy przyjęciu polecenia oba warianty zwracają taki sam wynik on_scene ze statusem ok, jak przykład z czasem domyślnym.

Błędy uruchomienia

Brak id, wartość niecałkowita lub numer poza zakresem 0–1999 daje HTTP 400 z pełnym body JSON:

{"error":"Scene ID must be a number between 0 and 1999"}

Niepoprawne time, na przykład -1 albo 1.5, daje HTTP 400 z pełnym body JSON:

{"error":"Time must be a non-negative integer"}

Jeżeli numer jest poprawny, ale scena nie istnieje, odpowiedź może mieć HTTP 200 z pełnym body JSON:

{"logic_action":"on_scene","status":"invalid_scene_num"}

To odrzucenie polecenia, nie sukces. Sprawdź numer i istnienie sceny w aplikacji mobilnej. Błędy dostępu (401, 403), przekierowanie do HTTPS (308) i błędy obsługi (500) opisano na stronie Odpowiedzi i błędy.

Zatrzymanie: GET /scene/stop

Usuwa podtrzymania należące do wskazanej sceny oraz jej oczekujące polecenia opóźnione. Wymaga parametru query id: numeru całkowitego 0–1999 istniejącej sceny, odczytanego w aplikacji mobilnej. Nie wymaga body ani parametru time.

Zatrzymanie nie wysyła automatycznie poleceń przeciwnych do już wykonanych. Na przykład przekaźnik włączony przez scenę nie otrzymuje z tego powodu automatycznego polecenia wyłączenia. Zakończenie podtrzymania temperatury także nie stanowi polecenia przywrócenia poprzedniej nastawy.

Żądanie HTTP:

GET /integrations/api/scene/stop?id=12 HTTP/1.1
Host: ADRES_SERWERA:PORT
Authorization: Bearer KLUCZ_API

To samo żądanie w curl:

curl --include --request GET \
  'https://ADRES_SERWERA:PORT/integrations/api/scene/stop?id=12' \
  --header 'Authorization: Bearer KLUCZ_API'

Przykładowa odpowiedź z pełnym body JSON:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"logic_action":"off_scene","status":"ok"}

logic_action: "off_scene" identyfikuje wynik zatrzymania. Status ok potwierdza obsługę polecenia, bez potwierdzenia odwrócenia wcześniejszych działań.

Brak id, wartość niecałkowita lub numer poza zakresem daje HTTP 400 z pełnym body JSON:

{"error":"Scene ID must be a number between 0 and 1999"}

Nieistniejąca scena może zwrócić HTTP 200 z pełnym body JSON:

{"logic_action":"off_scene","status":"invalid_scene_num"}

Sprawdź numer i istnienie sceny w aplikacji mobilnej. Wspólne błędy dostępu i obsługi opisano na stronie Odpowiedzi i błędy.

Ponowienie i utrata odpowiedzi

Ponowny start może ponownie wykonać działania sceny, odnowić czas podtrzymania i ustalić od nowa terminy poleceń opóźnionych. Powtórzone wywołanie jest kolejnym poleceniem, nawet gdy używa tego samego id i time.

Timeout, czyli przekroczenie czasu oczekiwania, lub zerwane połączenie nie dowodzą niewykonania startu albo stopu. Serwer nie ponawia automatycznie wysłanego polecenia. Nie ustawiaj bezwarunkowego automatycznego ponowienia tych żądań: ponowny start może powtórzyć skutki, a ponowny stop może usunąć podtrzymania i polecenia dodane przez uruchomienie sceny w międzyczasie.

Przed ręcznym ponowieniem sprawdź dostępny stan instalacji, na przykład w aplikacji mobilnej, i zdecyduj, czy kolejny start lub stop odpowiada zamierzonemu działaniu. REST nie udostępnia odczytu bieżącego statusu sceny, który rozstrzygałby wynik utraconego żądania. Szczegóły przekroczenia czasu oczekiwania i interpretacji odpowiedzi opisano na stronie Odpowiedzi i błędy.

Wróć do Rozpoczęcia pracy, aby wybrać kolejne zadanie.