Skip to content

REST API — urządzenia

Metody urządzeń pozwalają pobrać listę obiektów i odczytać stan wybranego obiektu. Jeden moduł może udostępniać wiele obiektów, na przykład osobne wyjścia. Zacznij od listy, wybierz obiekt, skopiuj jego object_id i użyj go do kolejnego odczytu.

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. Identyfikatory są fikcyjne; w swojej integracji używaj wartości zwróconych przez serwer. Ścieżki metod są względne wobec /integrations/api.

Wspólne pola statusu

Odpowiedzi mają format JSON, czyli tekstowy format danych. Lista jest tablicą w nawiasach [], a status jednego obiektu jest obiektem w nawiasach {}. W obu metodach obiekty statusu zawierają:

Pole Znaczenie
object_id Tekstowy identyfikator konkretnego obiektu, kopiowany dokładnie z listy.
device_type Typ obiektu, pomagający rozpoznać znaczenie jego pól.
attached Wartość logiczna informująca o dostępności obiektu zgłaszanej przez system. Nie potwierdza poprawności wszystkich jego wartości.
logic_action W tych odczytach ma wartość "initial_device_status" i oznacza odpowiedź ze stanem obiektu. Nie ustanawia subskrypcji.

Pozostałe metadane, na przykład opis, nazwa modułu, numer kanału czy identyfikatory modułu, zależą od obiektu. Nie muszą występować w każdym statusie. Także nazwy pól funkcjonalnych i ich jednostki zależą od typu; poniższe przykłady nie stanowią pełnego schematu odpowiedzi.

Pobranie listy: GET /device/list

Pobiera tablicę obiektów statusu urządzeń. Nie wymaga parametrów ani body, czyli treści żądania.

Żądanie HTTP z nagłówkiem autoryzacji, czyli dodatkową informacją dołączoną do żądania:

GET /integrations/api/device/list HTTP/1.1
Host: ADRES_SERWERA:PORT
Authorization: Bearer KLUCZ_API

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

curl --include --request GET \
  'https://ADRES_SERWERA:PORT/integrations/api/device/list' \
  --header 'Authorization: Bearer KLUCZ_API'

Przy HTTP 200 body jest tablicą statusów. Każdy jej element jest obiektem takim jak fragmenty pokazane niżej, z dodatkowymi polami zależnymi od obiektu. Nie zakładaj stałej kolejności elementów.

Przykład odpowiedzi z pełnym body JSON, gdy nie ma dostępnych na liście obiektów:

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

[]

Pusta tablica przy HTTP 200 jest prawidłowym wynikiem, bez pola status. Nie oznacza błędu ani statusu wyłączenia urządzenia. Gdy lista jest pusta, nie ma identyfikatora do dalszego odczytu; sprawdź dostępne obiekty w instalacji.

Błędy dostępu (401, 403), przekierowanie do HTTPS (308) i błędy obsługi (500, także po przekroczeniu czasu oczekiwania) opisano na stronie Odpowiedzi i błędy.

Wybór obiektu i jego identyfikatora

  1. W pobranej tablicy odszukaj właściwy obiekt według device_type oraz dostępnego opisu, nazwy modułu lub numeru kanału.
  2. Skopiuj całe object_id tego elementu i przechowuj je dokładnie w otrzymanej postaci, z zachowaniem wielkości liter i wszystkich znaków.
  3. Przekaż ten identyfikator do GET /device/status, a wartość odczytaj razem z attached i ewentualną flagą poprawności.

Traktuj object_id jako nieprzezroczysty identyfikator: nie odtwarzaj go z device_id, level i index. Jeden moduł może mieć wiele obiektów, a ta trójka liczb nie jest uniwersalnym unikalnym kluczem.

Odczyt jednego obiektu: GET /device/status

Pobiera pojedynczy obiekt statusu. Wymaga jednego tekstowego, niepustego parametru query object_id. Parametr query to wartość dopisywana do adresu po ?. Metoda nie wymaga body.

Poniższy przykład zakłada, że lista zwróciła dla wybranego wyjścia object_id o fikcyjnej wartości example-relay-A. Zastąp ją dokładnie skopiowanym identyfikatorem ze swojej listy.

GET /integrations/api/device/status?object_id=example-relay-A HTTP/1.1
Host: ADRES_SERWERA:PORT
Authorization: Bearer KLUCZ_API

To samo żądanie w curl. Opcja --get wysyła odczyt, a --data-urlencode koduje wartość parametru do użycia w URL, zachowując przekazany identyfikator:

curl --include --get \
  'https://ADRES_SERWERA:PORT/integrations/api/device/status' \
  --data-urlencode 'object_id=example-relay-A' \
  --header 'Authorization: Bearer KLUCZ_API'

Przy HTTP 200 body zawiera jeden obiekt JSON, bez tablicy otaczającej status. Pierwszy z trzech fragmentów poniżej pokazuje przykładowe pola odpowiedzi dla tego wyjścia. Odczyt może już różnić się od wcześniej pobranej listy, ponieważ stan mógł się zmienić.

Trzy fragmenty odpowiedzi i ich interpretacja

Każdy przykład jest fragmentem odpowiedzi, obejmującym tylko wybrane pola. Taki obiekt może być elementem listy albo wynikiem odczytu jednego obiektu; dodatkowe pola mogą występować. Dobór przykładów nie ogranicza typów zwracanych przez serwer.

Fragment 1 — wyjście przekaźnikowe: io32_output

{
  "logic_action": "initial_device_status",
  "object_id": "example-relay-A",
  "device_type": "io32_output",
  "attached": true,
  "binary_output": false,
  "binary_output_valid": false
}

binary_output jest wartością logiczną. W tym przykładzie binary_output_valid=false oznacza brak poprawnego odczytu; neutralne binary_output=false nie potwierdza wyłączenia. Dopiero przy binary_output_valid=true można interpretować false jako odczytany stan wyłączenia, a true jako stan włączenia. Samo attached=true nie zastępuje flagi poprawności.

Fragment 2 — czujnik temperatury: s4t_temperature_sensor

{
  "logic_action": "initial_device_status",
  "object_id": "example-temperature-B",
  "device_type": "s4t_temperature_sensor",
  "attached": true,
  "temperature": null
}

temperature jest liczbą w °C, na przykład 21.5, albo null przy braku znanego pomiaru. Pokazane null nie oznacza 0 °C, mimo dostępności obiektu. Ten typ nie zwraca osobnej flagi poprawności tego pomiaru.

Fragment 3 — ściemniacz: l4_dimmer

{
  "logic_action": "initial_device_status",
  "object_id": "example-dimmer-C",
  "device_type": "l4_dimmer",
  "attached": true,
  "brightness": 60
}

brightness jest liczbą całkowitą od 0 do 100, oznaczającą procentową jasność sterowania. W przykładzie wynosi 60%. Dla tego pola nie ma osobnej flagi poprawności.

Błędy odczytu jednego obiektu

Brak object_id, pusty tekst, same białe znaki albo przekazanie go w postaci innej niż jeden tekstowy parametr daje HTTP 400 z pełnym body JSON:

{"error":"Device ID is required"}

Dla nieznanego identyfikatora odpowiedź ma HTTP 404. Przykład z pełnym body JSON:

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"error":"Device not found"}

Pobierz listę ponownie i skopiuj identyfikator wybranego obiektu. 404 nie jest tym samym co status z attached=false: obiekt niedostępny może nadal znajdować się na liście i mieć swój status. Wspólne błędy dostępu (401, 403), przekierowanie (308) i błędy obsługi (500) opisuje strona Odpowiedzi i błędy.

Dostępność i kolejne odczyty

Oceniaj każdą wartość wraz z dostępnością obiektu i flagą *_valid, jeżeli dany typ ją zwraca. Nazwy i obecność takich flag różnią się między typami. attached=true nie gwarantuje poprawności każdego pomiaru lub ustawienia, a null oznaczające brak znanej wartości nie jest zerem.

Po odłączeniu obiektu część pól może zniknąć. Brak pola nie jest nowym odczytem zera ani potwierdzeniem wcześniej zapisanej wartości. Dane zachowane przez integrację z poprzedniej odpowiedzi nie stają się przez to aktualnym, potwierdzonym odczytem.

Każde żądanie pobiera stan. Aby odświeżyć dane, wykonaj kolejne żądanie. Te metody nie udostępniają strumienia zdarzeń, subskrypcji REST, webhooków ani SSE. Lista jest zwracana jako jedna tablica, bez parametrów paginacji i bez gwarancji kolejności. Nie ma ustalonej gwarantowanej częstotliwości odpytywania.

Publiczne REST API nie udostępnia metody zapisu urządzenia. Także obecność metadanych możliwości zapisu w statusie nie ustanawia takiej metody. Do sterowania użyj zmiennych połączonych z logiką albo scen.

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