REST API — rozpoczęcie pracy
REST API pozwala zewnętrznej integracji odczytywać i zapisywać zmienne projektu, uruchamiać i zatrzymywać sceny oraz odczytywać stan urządzeń F&Home. Sterowanie urządzeniami odbywa się przez zmienne połączone z logiką albo przez sceny.
Żądanie to pojedyncze wywołanie adresu API z wybraną metodą HTTP, na przykład GET do odczytu. Zacznij od pobrania listy zmiennych: ten odczyt nie zmienia stanu instalacji.
Włącz dostęp w panelu
- Zaloguj się do panelu WWW jako administrator.
- Otwórz Ustawienia → Zarządzanie systemem → Zdalny dostęp → Zarządzaj → REST API.
- Jeśli klucz jeszcze nie istnieje, wybierz Wygeneruj klucz.
- Włącz Włącz REST API i poczekaj na potwierdzony stan Aktywne.
- Wybierz Kopiuj klucz.
- Wprowadź klucz do konfiguracji swojej integracji i wykonaj pierwszy odczyt opisany poniżej.
Samo otwarcie ekranu nie generuje klucza ani nie włącza REST API. Generowanie klucza zachowuje dotychczasowy stan włączenia. Wyłączenie REST API zachowuje klucz, więc po ponownym włączeniu można korzystać z tej samej wartości.
Przy wyłączonym REST API panel blokuje kopiowanie i wymianę istniejącego klucza oraz zmianę opcji Zezwalaj na HTTP. Pierwsze generowanie klucza pozostaje dostępne, aby przygotować dostęp przed jego włączeniem.
Aby wymienić istniejący klucz, przy aktywnym REST API wybierz Wygeneruj nowy token i potwierdź operację. Poprzedni klucz przestanie działać. Wpisz nowy klucz we wszystkich korzystających z niego integracjach.
Jeśli panel nie otrzyma potwierdzenia operacji, nie zakładaj, że zmiana się nie wykonała. Oprzyj się na ponownym odczycie stanu i klucza. Gdy panel udostępnia Odczytaj stan ponownie, użyj tej opcji; przy utracie lub wygaśnięciu sesji wybierz Zaloguj się ponownie. Ostatni potwierdzony stan nie musi przedstawiać wyniku niepotwierdzonej zmiany.
Klucz i nagłówek autoryzacji
Nagłówek to dodatkowa informacja dołączona do żądania HTTP. Każde wywołanie REST API wymaga nagłówka:
Authorization: Bearer KLUCZ_API
Zastąp KLUCZ_API skopiowanym kluczem. Zachowaj dokładne słowo Bearer, z wielką literą B, oraz jedną spację przed kluczem. Klucz przesyłaj wyłącznie w tym nagłówku, bez umieszczania go w adresie URL lub treści żądania.
Nowy klucz ma 32 znaki alfanumeryczne. Jest wspólny dla integracji REST, nie ma terminu ważności ani osobnych zakresów dla aplikacji lub urządzeń. Dostęp nie dziedziczy ograniczeń pojedynczego konta użytkownika do wybranych zmiennych lub scen. Zachowaj klucz w tajemnicy.
Klucz integracyjny jest niezależny od tokenu sesji administratora. Do konfiguracji integracji używaj klucza z sekcji REST API.
Adres serwera i połączenie
Adres bazowy API ma postać:
https://ADRES_SERWERA:PORT/integrations/api
ADRES_SERWERAzastąp bezpośrednim adresem instalacji osiągalnym z urządzenia, na którym działa integracja.PORTzastąp portem HTTPS tej instalacji. Jeśli połączenie używa domyślnego portu HTTPS443, można pominąć część:PORT./integrations/apijest stałą ścieżką API. Nie dopisuj fragmentów adresu panelu, takich jak/#/system/remote.
Nazwa panelu chmurowego i włączenie dostępu przez chmurę nie ustanawiają dostępu REST. Tunel panelu chmurowego nie przenosi wywołań REST API; integracja potrzebuje bezpośredniego połączenia z instalacją.
Połączenia ze źródłowych adresów loopback, w tym 127.0.0.1 i ::1, są odrzucane także przy poprawnym kluczu. Użyj połączenia sieciowego z adresem instalacji, zamiast adresu loopback.
HTTPS i opcjonalne HTTP
Jeśli instalacja korzysta z HTTPS, używaj właściwego adresu HTTPS i certyfikatu zaufanego przez klienta integracji. Adres musi odpowiadać certyfikatowi.
Opcja Zezwalaj na HTTP dopuszcza nieszyfrowane żądania REST z nadal wymaganym kluczem. Domyślnie jest wyłączona. Jej włączenie pozostawia HTTPS dostępny, ale samo nie uruchamia HTTPS ani TLS. Preferuj połączenie HTTPS z poprawnie weryfikowanym certyfikatem.
Przy aktywnym HTTPS zdalne żądanie HTTP bez tego wyjątku otrzymuje przekierowanie HTTP 308 z adresem HTTPS. Gdy HTTPS nie jest aktywne, samo wyłączenie opcji Zezwalaj na HTTP nie blokuje dotychczasowej obsługi HTTP.
Opcja HTTP nie zmienia klucza, stanu włączenia REST API ani konfiguracji chmury. Zapisana preferencja pozostaje zachowana po wyłączeniu i ponownym włączeniu REST API.
Pierwszy odczyt: GET /variable/list
Ta metoda pobiera nazwy zmiennych dostępnych w projekcie. Nie wymaga parametrów, czyli dodatkowych wartości przekazywanych do metody, ani treści żądania. Wynik nie zawiera wartości zmiennych, jednostek ani deklaracji ich typów.
Przykładowe żądanie HTTP; wszystkie oznaczenia adresu, portu i klucza zastąp zgodnie z opisem powyżej:
GET /integrations/api/variable/list HTTP/1.1
Host: ADRES_SERWERA:PORT
Authorization: Bearer KLUCZ_API
To samo wywołanie w curl; opcja --include pokazuje również nagłówki odpowiedzi:
curl --include --request GET \
'https://ADRES_SERWERA:PORT/integrations/api/variable/list' \
--header 'Authorization: Bearer KLUCZ_API'
Serwer zwraca JSON, czyli tekstowy format danych używający między innymi tablic w nawiasach [] i obiektów w nawiasach {}. Przykładowa odpowiedź z pełnym body JSON, z fikcyjnymi nazwami zmiennych:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
["garden_light", "room_temp"]
Poprawną pełną odpowiedzią JSON jest również pusta tablica:
[]
Oznacza ona brak dostępnych zmiennych w bieżącym projekcie. Jeśli oczekujesz nazw, sprawdź aktywne bloczki variable i zapisz projekt. Pusta lista przy HTTP 200 jest prawidłowym wynikiem.
Dalsze kroki opisuje strona Zmienne: przygotowanie zmiennej w projekcie, odczyt jej wartości i sterowanie przez zapis.
Błędy dostępu (401, 403), przekierowanie do HTTPS (308) i błędy obsługi (500) opisano na stronie Odpowiedzi i błędy. Przy tej metodzie oczekiwanym wynikiem jest tablica nazw, bez pola status.
Przygotuj format późniejszych zapisów
Body to treść żądania zawierająca dane do przesłania. Przy zapisie danych w JSON dołącz nagłówek:
Content-Type: application/json
Informuje on serwer, jak odczytać body. Typ wartości JSON ma znaczenie: true, 1 i "1" oznaczają odpowiednio wartość logiczną, liczbę i tekst.
Dalsza praca
- Zmienne — odczyt pomiaru, sterowanie właściwością urządzenia i operacje zbiorcze.
- Sceny — uruchamianie i zatrzymywanie scen, wybór czasu podtrzymania i skutki ponawiania poleceń.
- Urządzenia — pobranie listy, wybór obiektu i odczyt jego stanu z interpretacją dostępności oraz wartości.
- Odpowiedzi i błędy — rozpoznawanie błędów dostępu, wyniku polecenia i niepewności po utracie odpowiedzi.
- Spis treści dokumentacji F&Home.