Skip to content

REST API — zmienne

Zmienne łączą integrację z logiką projektu: pozwalają odczytać pomiar udostępniony przez bloczek albo przekazać wartość do sterowania. API odczytuje i zapisuje istniejące zmienne; nie tworzy ich.

Najpierw skonfiguruj dostęp według Rozpoczęcia pracy. W poniższych przykładach zastąp ADRES_SERWERA, PORT i KLUCZ_API adresem instalacji, portem HTTPS i kluczem z panelu. Ścieżki metod są względne wobec /integrations/api. Przykładowe nazwy i wartości są fikcyjne. Wspólne błędy dostępu i obsługi opisano na stronie Odpowiedzi i błędy.

Przygotuj zmienne w projekcie

Zmienna jest dostępna, gdy zapisany projekt zawiera przynajmniej jeden poprawnie skonfigurowany, aktywny bloczek variable o tej nazwie. Nie wymaga osobnego zaznaczenia publikacji ani eksportu do API. Wszystkie instancje z tą samą nazwą współdzielą jedną wartość.

Nazwa musi mieć od 1 do 25 znaków: litery ASCII (A–Z, a–z), cyfry lub _. Pierwszy znak nie może być cyfrą. Wielkość liter ma znaczenie: room_temp i Room_temp to różne nazwy. Zmienna bloczka variable nie jest urządzeniem tworzonym przez app-value.

Odczyt pomiaru: input → variable

  1. Dodaj bloczek input. W polu Urządzenie wybierz czujnik temperatury w pokoju, a w polu Właściwość jego pomiar temperatury.
  2. Dodaj bloczek variable i ustaw Nazwa na room_temp.
  3. Połącz wyjście 1 bloczka input z wejściem bloczka variable. Wyjście 1 udostępnia wartość; wyjście 2 informuje o podłączeniu urządzenia.
  4. Zapisz projekt. Po otrzymaniu pomiaru od urządzenia odczytaj room_temp metodą GET /variable opisaną poniżej.

Na przykład pomiar 21.5 będzie zwrócony jako liczba. W tym przepływie oznacza temperaturę w °C, ponieważ tak skonfigurowano źródło pomiaru; sama odpowiedź zmiennej nie zawiera jednostki.

Sterowanie: variable → output

  1. Dodaj bloczek variable i ustaw Nazwa na garden_light.
  2. Dodaj bloczek output. W polu Urządzenie wybierz przekaźnik sterujący oświetleniem ogrodu, a w polu Właściwość jego wyjście binarne.
  3. Połącz wyjście bloczka variable z wejściem bloczka output i zapisz projekt.
  4. Wyślij POST /variable z {"name":"garden_light","value":true}, jak w przykładzie poniżej. Dla tej właściwości używaj wartości logicznych JSON true lub false.

Typ i zakres wartości muszą odpowiadać wybranej właściwości. output nie zmienia typu otrzymanej wartości. Status ok zapisu potwierdza przyjęcie wartości przez zmienną, ale nie potwierdza fizycznego wykonania przez urządzenie. Zachowanie przy odłączeniu i filtrowanie wartości opisuje strona bloczka output.

Typy, początkowa wartość i dokładność

Obsługiwane wartości zapisu to:

Typ JSON Przykłady wartości value
Brak wartości null
Wartość logiczna true, false
Liczba 0, 21.5, 40
Tekst "evening", "1", ""

Obiekty i tablice nie są obsługiwanymi wartościami zmiennej. true, 1 i "1" są różnymi wartościami. Kolejny zapis może zmienić typ zmiennej. null oznacza brak wartości i nie jest zerem, false ani pustym tekstem.

Początkowy brak wartości jest odczytywany jako null. Wartości nie są trwałe: po restarcie lub przeładowaniu projektu trzeba je ponownie dostarczyć z logiki albo zapisać przez API.

Liczby mają rozdzielczość 0,001. Dalsze cyfry są obcinane w kierunku zera, a nie zaokrąglane; reprezentacja zmiennoprzecinkowa może wpływać na wynik konwersji. Stosuj typowe zakresy automatyki i nie zakładaj obsługi dowolnie dużych liczb, również całkowitych. Odczyt liczby nie zawiera jednostki; jej znaczenie wynika z konfiguracji projektu.

Lista nazw: GET /variable/list

Pobiera tablicę nazw dostępnych zmiennych. Nie wymaga parametrów ani body. Wynik nie zawiera wartości, jednostek ani deklaracji typu.

Żądanie HTTP:

GET /integrations/api/variable/list 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/variable/list' \
  --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

["garden_light", "room_temp"]

Pusta tablica [] przy HTTP 200 jest poprawnym wynikiem: projekt nie udostępnia zmiennych. Sprawdź bloczki variable i zapis projektu, jeśli oczekujesz nazw. Błędy dostępu i obsługi opisano na stronie Odpowiedzi i błędy.

Odczyt jednej zmiennej: GET /variable

Podaj nazwę w parametrze query name. Parametry query dopisuje się do adresu po ?, na przykład ?name=room_temp. Metoda nie wymaga body.

Żądanie HTTP:

GET /integrations/api/variable?name=room_temp 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/variable?name=room_temp' \
  --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

{"value":21.5}

Istniejąca zmienna bez wartości zwraca pełne body {"value":null}. Nieznana zmienna zwraca zwykle HTTP 200 z pełnym body {"status":"invalid_variable"}. Nie interpretuj tego jako sukcesu ani nie oczekuj HTTP 404 jako zwykłego wyniku dla nieznanej zmiennej. Udany odczyt ma pole value i nie musi zawierać status.

Zapis jednej zmiennej: POST /variable

Wyślij obiekt JSON z tekstowym name oraz polem value obsługiwanego typu. Nagłówek Content-Type: application/json określa format body i pozwala zachować typ wartości.

Żądanie HTTP:

POST /integrations/api/variable HTTP/1.1
Host: ADRES_SERWERA:PORT
Authorization: Bearer KLUCZ_API
Content-Type: application/json

{"name":"garden_light","value":true}

To samo żądanie w curl:

curl --include --request POST \
  'https://ADRES_SERWERA:PORT/integrations/api/variable' \
  --header 'Authorization: Bearer KLUCZ_API' \
  --header 'Content-Type: application/json' \
  --data-raw '{"name":"garden_light","value":true}'

Przykładowa odpowiedź z pełnym body JSON, gdy wartość została zmieniona:

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

{"status":"ok"}

Sprawdź pole status, także przy HTTP 200:

status Znaczenie
ok Wartość została przyjęta przez zmienną i przekazana do połączonej logiki; nie jest to potwierdzenie fizycznego działania urządzenia.
already_set Zmienna ma już tę samą wartość. Zapis nie uruchamia ponownie logiki.
invalid_variable Brakuje poprawnej nazwy lub projekt nie udostępnia zmiennej o tej nazwie. Sprawdź aktywny bloczek i zapis projektu.
invalid_value Brakuje pola value albo jego typ jest nieobsługiwany, na przykład obiekt lub tablica.

Wyłączenie Blokuj powtarzające się wartości w bloczku output nie omija already_set: taki zapis zatrzymuje się przed ponownym przekazaniem wartości do logiki.

Pojedynczy zapis przyjmuje także parametry query name i value. Każdy podany parametr query ma pierwszeństwo nad odpowiadającym mu polem body. Wartość z query pozostaje tekstem: value=true oznacza tekst "true", a nie wartość logiczną true. Używaj body JSON jak w przykładzie i nie dodawaj tych parametrów do URL, jeśli chcesz zachować typ.

Operacje zbiorcze

Obie metody zbiorcze przyjmują bezpośrednio niepustą tablicę JSON, bez obiektu opakowującego data. Niepoprawny kształt całej listy lub jej elementu powoduje HTTP 400 przed wysłaniem któregokolwiek polecenia:

  • odczyt wymaga tekstowych nazw; [] lub ["room_temp", 7] zostanie odrzucone;
  • zapis wymaga obiektów z tekstowym name i obecnym polem value; [] lub [{"name":"garden_light"}] zostanie odrzucone.

null, false, 0 i pusty tekst są obecnymi wartościami, a nie brakiem pola. Przykład pełnego body zapisu poprawnego pod względem formatu; każda z tych fikcyjnych nazw musi istnieć w projekcie:

[
  {"name":"empty_value","value":null},
  {"name":"enabled_flag","value":false},
  {"name":"counter_value","value":0},
  {"name":"mode_text","value":""}
]

Obiekt lub tablica w polu value przechodzi sprawdzenie obecności pola, lecz daje invalid_value dla tej pozycji. Nie jest to odrzucenie formatu całej listy przed jej wykonaniem.

Odczyt wielu zmiennych: POST /variables/get

Pobiera wartości nazw podanych w body. W tym przykładzie garden_light i room_temp istnieją, a missing_variable nie istnieje.

Żądanie HTTP:

POST /integrations/api/variables/get HTTP/1.1
Host: ADRES_SERWERA:PORT
Authorization: Bearer KLUCZ_API
Content-Type: application/json

["garden_light","room_temp","missing_variable"]

To samo żądanie w curl:

curl --include --request POST \
  'https://ADRES_SERWERA:PORT/integrations/api/variables/get' \
  --header 'Authorization: Bearer KLUCZ_API' \
  --header 'Content-Type: application/json' \
  --data-raw '["garden_light","room_temp","missing_variable"]'

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

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

[{"name":"room_temp","value":21.5},{"name":"garden_light","value":true}]

Nieznane zmienne są pomijane. Jeśli żadna podana zmienna nie istnieje, poprawnym wynikiem jest []. Zmienna istniejąca bez wartości pozostaje w wyniku z "value":null.

Zapis wielu zmiennych: POST /variables/set

Zapisuje wartości z obiektów w body. W tym przykładzie garden_light i target_temp istnieją w zapisanym projekcie, target_temp ma już wartość 21.5, a missing_variable nie istnieje.

Żądanie HTTP:

POST /integrations/api/variables/set HTTP/1.1
Host: ADRES_SERWERA:PORT
Authorization: Bearer KLUCZ_API
Content-Type: application/json

[{"name":"garden_light","value":true},{"name":"target_temp","value":21.5},{"name":"missing_variable","value":false}]

To samo żądanie w curl:

curl --include --request POST \
  'https://ADRES_SERWERA:PORT/integrations/api/variables/set' \
  --header 'Authorization: Bearer KLUCZ_API' \
  --header 'Content-Type: application/json' \
  --data-raw '[{"name":"garden_light","value":true},{"name":"target_temp","value":21.5},{"name":"missing_variable","value":false}]'

Przykładowa odpowiedź z pełnym body JSON, jeśli wymiana zakończyła się poprawnie, a garden_light zmieniło wartość:

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

[{"name":"target_temp","status":"already_set"},{"name":"garden_light","status":"ok"},{"name":"missing_variable","status":"invalid_variable"}]

Każda pozycja ma własny wynik status, o znaczeniu opisanym przy zapisie pojedynczym. HTTP 200 nie oznacza powodzenia wszystkich zapisów.

Kolejność, częściowe wykonanie i limity

Kolejność odpowiedzi obu metod zbiorczych nie musi odpowiadać kolejności wejściowej. Stosuj unikalne nazwy, jak w przykładach, i dopasowuj wyniki po name, a nie po pozycji na liście.

Zapis zbiorczy nie jest transakcją i nie wycofuje wcześniejszych zmian. Błąd transportu lub timeout może zakończyć całe żądanie po wykonaniu części zapisów, bez zwrócenia częściowego wyniku. Limit oczekiwania około 5 sekund dotyczy kompletu odpowiedzi, a nie każdej pozycji osobno. Błędy obsługi lub wymiany mogą dać HTTP 500.

Serwer nie ponawia automatycznie wysłanych poleceń. Po utracie odpowiedzi nie zakładaj, że zapis się nie wykonał; odczytaj wartości i oceń wynik przed decyzją o dalszym zapisie. Sam odczyt zmiennej nadal nie potwierdza fizycznego działania urządzenia.

Ustalony limit HTTP to body 1 MiB; przekroczenie daje HTTP 413. Nie ma tu osobnego ustalonego limitu liczby elementów. Szczegóły błędów i niepewności po timeout opisano na stronie Odpowiedzi i błędy.

Do konfiguracji dostępu wróć przez Rozpoczęcie pracy.