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
- Dodaj bloczek
input. W polu Urządzenie wybierz czujnik temperatury w pokoju, a w polu Właściwość jego pomiar temperatury. - Dodaj bloczek
variablei ustaw Nazwa naroom_temp. - Połącz wyjście 1 bloczka
inputz wejściem bloczkavariable. Wyjście 1 udostępnia wartość; wyjście 2 informuje o podłączeniu urządzenia. - Zapisz projekt. Po otrzymaniu pomiaru od urządzenia odczytaj
room_tempmetodąGET /variableopisaną 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
- Dodaj bloczek
variablei ustaw Nazwa nagarden_light. - 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. - Połącz wyjście bloczka
variablez wejściem bloczkaoutputi zapisz projekt. - Wyślij
POST /variablez{"name":"garden_light","value":true}, jak w przykładzie poniżej. Dla tej właściwości używaj wartości logicznych JSONtruelubfalse.
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
namei obecnym polemvalue;[]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.