Interfejs API RESTful ALGO

Informacje o produkcie: Przewodnik po interfejsie API RESTful

Interfejs API Algo RESTful umożliwia użytkownikom dostęp, manipulowanie i wyzwalanie działań na punktach końcowych IP Algo w ich sieci za pośrednictwem żądań HTTP/HTTPS. Ten dokument zawiera jednolity i wstępnie zdefiniowany zestaw operacji bezstanowych, których można używać do interakcji z urządzeniami Algo. Interfejs API obsługuje żądania HTTP/HTTPS GET, POST i PUT z ładunkami JSON.

Uwierzytelnianie

W ramach interfejsu API Algo RESTful dostępne są trzy typy uwierzytelniania:

• Standardowe uwierzytelnianie (domyślnie włączone)
• Podstawowe uwierzytelnianie (opcjonalne)
• Brak metody uwierzytelniania (niezalecane; tylko do celów testowych)

Instrukcje użytkowania produktu: RESTful API

Wymagania wstępne

Przed włączeniem RESTful API upewnij się, że urządzenie ma połączenie internetowe, aby dotrzeć do wstępnie skonfigurowanych serwerów NTP. Jeśli połączenie internetowe nie jest dostępne, skonfiguruj lokalny serwer NTP i wprowadź jego adres IP.

Włączanie interfejsu API RESTful

1. Zaloguj się do urządzenia web interfejsu i przejdź do zakładki Ustawienia zaawansowane – Administrator.
2. Przewiń w dół do sekcji Obsługa API i włącz interfejs API RESTful.
3. Ustaw żądane hasło (domyślne hasło: algo). Należy pamiętać, że uwierzytelnianie standardowe jest domyślnie włączone.

Włączanie uwierzytelniania podstawowego (opcjonalnie)

1. W web interfejs, przejdź do zakładki Konserwacja systemu i pobierz konfigurację file.
2. Otwórz konfigurację file za pomocą dowolnego edytora tekstu i dodaj następujący wiersz: api.auth.basic = 1
3. Zapisz i prześlij zmodyfikowaną konfigurację file powrót do urządzenia za pomocą opcji Przywróć konfigurację File funkcja na karcie Konserwacja systemu.

Włączanie opcji Brak metody uwierzytelniania (opcjonalnie)

Aby włączyć metodę bez uwierzytelniania, pozostaw pole RESTful API Password puste. Ta metoda nie jest zalecana i powinna być używana tylko do celów testowych, ponieważ nie zapewnia żadnego bezpieczeństwa.

Włączanie prostego interfejsu sterowania (opcjonalnie)

1. Na web interfejs, przejdź do zakładki Konserwacja systemu i pobierz konfigurację file.
2. Otwórz konfigurację file używając edytora tekstu i dodaj dwie linie. Zmień na swoje hasło.
3. Administrator.web.sci = 1
4. Sci.admin.hasło =
5. Zapisz i prześlij zmodyfikowaną konfigurację file powrót do urządzenia za pomocą opcji Przywróć konfigurację File funkcja na karcie Konserwacja systemu.

Uwierzytelnianie Sample Kod

Proszę o e-mail wsparcie@algosolutions.com jeśli chcesz standardową lub podstawową autoryzacjęampkod.
Aby uzyskać dodatkowe wsparcie, zadzwoń 604-454-3792 lub e-mail wsparcie@algosolutions.com

Powiadomienia informacyjne

Notatka
Uwaga oznacza przydatne aktualizacje, informacje i instrukcje, których należy przestrzegać

Zastrzeżenie

Uważa się, że informacje zawarte w tym dokumencie są dokładne pod każdym względem, ale nie są gwarantowane przez Algo. Informacje mogą ulec zmianie bez powiadomienia i nie powinny być w żaden sposób interpretowane jako zobowiązanie Algo ani żadnego z jej podmiotów stowarzyszonych lub zależnych. Algo i jego podmioty stowarzyszone i zależne nie ponoszą odpowiedzialności za jakiekolwiek błędy lub pominięcia w tym dokumencie. Mogą zostać wydane rewizje tego dokumentu lub jego nowe wydania w celu uwzględnienia takich zmian. Algo nie ponosi odpowiedzialności za szkody lub roszczenia wynikające z jakiegokolwiek użycia tej instrukcji lub takich produktów, oprogramowania, oprogramowania sprzętowego i/lub sprzętu. Żadna część tego dokumentu nie może być powielana ani przesyłana w żadnej formie ani za pomocą żadnych środków – elektronicznych lub mechanicznych – w jakimkolwiek celu bez pisemnej zgody Algo.
Aby uzyskać dodatkowe informacje lub pomoc techniczną w Ameryce Północnej, skontaktuj się z zespołem wsparcia Algo:

Wsparcie techniczne Algo
1-604-454-3792
wsparcie@algosolutions.com

©2022 Algo jest zarejestrowanym znakiem towarowym firmy Algo Communication Products Ltd.
Wszelkie prawa zastrzeżone. Wszystkie inne znaki towarowe są własnością ich właścicieli. Wszystkie specyfikacje mogą ulec zmianie bez powiadomienia.

 OGÓLNY

Wstęp

W tym dokumencie opisano, jak można używać Algo RESTful API do uzyskiwania dostępu, manipulowania i wyzwalania działań na punktach końcowych Algo IP w sieci za pośrednictwem żądań HTTP/HTTPS, a także kilku różnych metod uwierzytelniania o różnym poziomie bezpieczeństwa. Systemy żądające mogą wchodzić w interakcje z urządzeniami Algo za pośrednictwem jednolitego i wstępnie zdefiniowanego zestawu operacji bezstanowych zdefiniowanych w tym dokumencie. Żądania są kierowane do URI zasobu z ładunkiem JSON i wywołują odpowiedź JSON. Żądania HTTP/HTTPS GET, POST i PUT są kierowane do URI zasobu wraz z ładunkiem JSON (zobacz sekcję poleceń, aby uzyskać listę ładunków).

 Uwierzytelnianie

Istnieją trzy rodzaje uwierzytelniania:

•  Standard (zalecany)
•  Podstawowy
•  Brak (niezalecane)

Uwierzytelnianie standardowe wykorzystuje kod uwierzytelniania wiadomości oparty na skrótach (HMAC) z zakodowanym skrótem SHA-256. Uwierzytelnianie podstawowe wykorzystuje kodowanie Base64 i powinno być używane tylko przez HTTPS. Żadne uwierzytelnianie powinno być używane tylko ze szczególną ostrożnością, ponieważ nie zapewnia uwierzytelniania. Więcej szczegółów można znaleźć w sekcji Wymagania uwierzytelniania.

USTAWIENIA I KONFIGURACJA

Wymagania wstępne

•  W tym dokumencie przyjęto założenie, że punkt końcowy Algo korzysta z oprogramowania sprzętowego w wersji 3.3 lub nowszej.
•  Różnica czasu między wnioskodawcą a urządzeniami Algo powinna wynosić mniej niż 30 sekund, aby można było użyć standardowego uwierzytelniania.
• Upewnij się, że NTP (Network Time Protocol) jest w użyciu. Adresy niestandardowych serwerów NTP można skonfigurować w zakładce Advanced Settings → Time.

Notatka
Wstępnie skonfigurowane serwery NTP są publicznie hostowane, dlatego do ich uzyskania wymagane jest połączenie internetowe. Jeśli nie ma połączenia internetowego, skonfiguruj lokalny serwer NTP i wprowadź jego adres IP.

• Upewnij się, że czas systemowy urządzenia Algo jest dostosowany do prawidłowej strefy czasowej. Można to zrobić, przechodząc do zakładki Ustawienia zaawansowane → Czas.

 Włączanie interfejsu API RESTful

1. Zaloguj się do web interfejsu i przejdź do Ustawień zaawansowanych → zakładki Administrator.
2. Przewiń w dół do sekcji Wsparcie API, włącz API RESTful i ustaw hasło zgodnie z życzeniem (domyślne hasło: algo)
   Notatka
   Standardowe uwierzytelnianie jest włączone domyślnie.

Włącz podstawowe uwierzytelnianie (opcjonalnie)

1. W web interfejsu, przejdź do zakładki System → Konserwacja i pobierz konfigurację file.
2. Otwórz konfigurację file za pomocą dowolnego edytora tekstu i dodaj następujący wiersz: api.auth.basic = 1
3.  Zapisz i prześlij zmodyfikowaną konfigurację file powrót do urządzenia za pomocą opcji Przywróć konfigurację File funkcja na karcie System → Konserwacja.

Brak metody uwierzytelniania (opcjonalnie)

Aby włączyć metodę bez uwierzytelniania, pozostaw pole RESTful API Password puste. Ta metoda nie jest zalecana i powinna być używana tylko do celów testowych, ponieważ nie zapewnia żadnego bezpieczeństwa.

Włączanie prostego interfejsu sterowania (opcjonalnie)

1. Na web interfejsu, przejdź do zakładki System → Konserwacja i pobierz konfigurację file.
2.  Otwórz konfigurację file używając edytora tekstu i dodaj dwie linie. Zmień do Twojego pożądanego hasła. Admin.web.sci = 1
   Sci.admin.hasło =
3.  Zapisz i prześlij zmodyfikowaną konfigurację file powrót do urządzenia za pomocą opcji Przywróć konfigurację File funkcja na karcie System → Konserwacja.

WYMAGANIA DOTYCZĄCE UWIERZYTELNIANIA

Proszę o e-mail wsparcie@algosolutions.com jeśli chcesz standardową lub podstawową autoryzacjęampkod.

Standardowe żądanie uwierzytelnienia z ładunkiem JSON

Wymagane nagłówki w żądaniu HTTP/HTTPS
> Typ zawartości: „application/json”
> Zawartość-MD5: [content_md5] Example
Content-MD5: 74362cc86588b2b3c5a4491baf80375b

Autoryzacja: hmac admin:[nonce]:[hmac_output]
Nagłówki autoryzacji składają się z:

1. Ciąg „hmac admin” po którym następuje dwukropek „:”.
2. Nonce – losowa lub niepowtarzalna wartość, po której następuje dwukropek „:”.
3. Hmac_output – wygenerowany przez RESTful API Hasło (klucz tajny) skonfigurowany na Twoim urządzeniu i dane wejściowe HMAC, jak poniżej:
   [metoda_żądania]:[identyfikator_URI_żądania]:[adres_zawartości_MD5]:[typ_zawartości]:[czasamp]:[chwilowo]

Wejście HMAC example: (używając „algo” jako klucza tajnego)
POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936 Generowanie HMAC z hasłem i ciągiem wejściowym HMAC jako skrótem przy użyciu algorytmu SHA-256:
Wyjście HMAC np.ample: 2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330

Data: dzień, data miesiąc, rok godz.:min.:sek. GMT
Example
Data: Czwartek, 22 września 2022 02:33:07 GMT
Standardowe uwierzytelnianie z ładunkiem np.ampna:

 Standardowe żądanie uwierzytelnienia bez ładunku JSON

Identyczne z 3.1, z pominięciem nagłówków związanych z treścią/danych wejściowych hmac.
Dane wejściowe HMAC: [metoda_żądania]:[uri_żądania]:[czasamp]:[nonce] dane wejściowe HMACample: (używając „algo” jako klucza tajnego)
POBIERZ:/api/settings/audio.page.vol:1601312252:49936
Wygeneruj HMAC z hasłem i ciągiem wejściowym HMAC przy użyciu SHA-256:
Wyjście HMAC np.ample: c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8
Standardowe uwierzytelnianie bez ładunku np.ampna:

 Podstawowa prośba o uwierzytelnienie

Należy zachować ostrożność podczas korzystania z tej metody uwierzytelniania, gdyż jest ona mniej bezpieczna od metody standardowej.

Autoryzacja: podstawowa [base64]
Exampna:
Autoryzacja: Podstawowa YWRtaW46YWxnbwo=
Podstawowe uwierzytelnianie np.ampna:

POLECANIA

 Polecenia interfejsu API RESTful

Poniżej znajduje się lista wszystkich obsługiwanych poleceń API.

Notatka
Żądanie PUT zmienia lub tworzy zasób trwały, który przetrwa ponowne uruchomienie, podczas gdy żądanie POST steruje urządzeniem tylko w trakcie bieżącej sesji.

Opis	Metoda	URI	Ładunek Parametry	Powrót Example	Produkt	FW
Pobierz wartość określonego parametru.	DOSTAWAĆ	/api/settings/[nazwa-klucza] Np. /api/settings/audio.page.vol	Brak	{„audio.page.vol”: „-18dB”}	Wszystko	> 3.3
Zwróć poziom hałasu otoczenia mierzony w decybelach. Kompensacja hałasu otoczenia musi być włączona w Ustawieniach podstawowych -> karta Funkcje.	DOSTAWAĆ	/api/info/audio.noise.poziom	Brak	{„poziom.hałasu.audio”: 72}	Głośniki Wyświetlacz Głośniki	> 3.3
Wyodrębnij stan zacisku wejściowego przekaźnika.	DOSTAWAĆ	/api/info/input.relay.status	Brak	{“input.relay.status”: “bezczynny”} lub {“input.relay.status”: “aktywny”}	Wszystkie produkty z wejściem przekaźnikowym, z wyjątkiem 8063. Zobacz poniżej.	> 4.1
Wyodrębnij stan zacisków wejściowych 1 lub wejściowych 2.	DOSTAWAĆ	/api/info/input.relay1.status lub /api/info/input.relay2.status	Brak	{“input.relay1.status”: “bezczynny”} lub {“input.relay1.status”: “aktywny”}	8063	> 4.1
Pobierz listę tonów files aktualnie zainstalowany.	DOSTAWAĆ	/api/info/tonlist	Brak	{„tonelist”:[„bell-na.wav”,”bell uk.wav”,”buzzer.wav”,…]}	Wszystko	> 5.0
Pobierz informacje o urządzeniu wyświetlane na stronie Status.	DOSTAWAĆ	/api/info/status	Brak	Pełna lista informacji na karcie Status.	Wszystko	> 5.4

Pobierz informacje o produkcie wyświetlane na stronie „O produkcie”.	DOSTAWAĆ	/api/info/o	Brak	Wszystkie informacje znajdują się na karcie „O nas”.	Wszystko	> 5.4
Włącz stroboskop o pożądanych parametrach koloru i wzoru.	POST	/api/controls/strobe/start	wzór: {0 – 15} color1: {niebieski, czerwony, bursztynowy, zielony} color2: {niebieski, czerwony, bursztynowy, zielony} ledlvl: {1 – 255} holdover: {prawda, fałsz}	Brak	8128(G2) 8138 8190S	> 3.3
Zatrzymaj stroboskop.	POST	/api/controls/strobe/stop	Brak	Brak	8128(G2) 8138 8190S	> 3.3
Zagraj dźwięk raz lub zapętl go.	POST	/api/controls/tone/start	ścieżka: {tone} np. chime.wav pętla: {prawda, fałsz} lub {0, 1} np. {“ścieżka”:”chime.wav”, “pętla”:true}	Brak	Głośniki 8301 8373 8028(G2) 8201 8039	> 3.3
Zatrzymaj dźwięk.	POST	/api/controls/ton/stop	Brak	Brak	Głośniki 8301 8373 8028(G2) 8201 8039	> 3.3
Zadzwoń na numer wewnętrzny i odtwórz nagraną wcześniej wiadomość.	POST	/api/controls/call/start	{„rozszerzenie”:”2099″, „ton”: „gong.wav”, „interwał”: „0”, „maks.czas trwania”: „10”}	Brak	Głośniki 8301 8410 8420	> 3.3
Zakończ połączenie.	POST	/api/controls/call/stop	Brak	Brak	Głośniki 8301 8410 8420	> 3.3

Zainicjuj jednokierunkowe wywołanie strony. Urządzenie odbierze strumień audio z rozszerzenia docelowego.	POST	/api/controls/wywołanie/strona	{"rozszerzenie":" ”}	Brak	Głośniki 8410 8420	> 5.3.4
Uruchom ponownie punkt końcowy.	POST	/api/controls/reboot	Brak	Brak	Wszystko	> 3.3
Odblokuj drzwi. „local” steruje lokalnym przekaźnikiem „netdc1” steruje zdalnym kontrolerem drzwi sieciowych (8063)	POST	/api/controls/drzwi/odblokowanie	doorid: {lokalny, netdc1} *Opcjonalny	Brak	8039 8028(G2) 8201 8063	> 3.3
Zamknij drzwi.	POST	/api/controls/drzwi/zamek	doorid: {lokalny, netdc1} *Opcjonalny	Brak	8039 8028(G2) 8201 8063	> 3.3
Włącz przekaźnik wyjściowy 24 V.	POST	api/kontrole/24v/włącz	Brak	Brak	8063	> 5.0
Wyłącz przekaźnik wyjściowy 24 V.	POST	api/controls/24v/wyłącz	Brak	Brak	8063	> 5.0
Włącz przekaźnik wyjściowy.	POST	/api/controls/przekaźnik/włącz	Brak	Brak	8063	> 5.0
Wyłącz przekaźnik wyjściowy.	POST	/api/controls/relay/wyłącz	Brak	Brak	8063	> 5.0
Sprawdź serwer oprogramowania sprzętowego Algo w celu uzyskania najnowszej wersji oprogramowania sprzętowego.	POST	/api/controls/upgrade/sprawdź	Brak	{„wersja”: „zaktualizowana”} lub {„wersja”: „ ”}	Wszystko	> 4.1
Sprawdź serwer oprogramowania sprzętowego Algo pod kątem najnowszej wersji oprogramowania sprzętowego i wykonaj aktualizację do tej wersji.	POST	/api/controls/upgrade/start	Brak	{„status”: „zaktualizowano”} lub {„status”: „aktualizacja ”, „url”: url>} lub {„status”: „ ”}	Wszystko	> 4.1
Wyświetl obraz lub wzór na ekranie.	POST	/api/controls/ekran/start	Widzieć poniżej	Brak	8410 8420	> 5.3.4
Zatrzymaj schemat wyświetlania ekranu i wróć do ekranu domyślnego.	POST	/api/controls/ekran/stop	Brak	Brak	8410 8420	> 5.3.4

Uruchom ponownie aplikację główną.	POST	/api/kontrole/odśwież	Brak	Brak	Wszystko	> 5.3.4
Rozpocznij słuchanie bezpośredniego strumienia audio. Skonfiguruj numer portu, do którego strumień jest wysyłany.	POST	/api/controls/rx/start	{"port": }	Brak	Wszystko	> 5.3.4
Przestań słuchać bezpośredniego strumienia audio.	POST	/api/controls/rx/stop	Brak	Brak	Wszystko	> 5.3.4
Ustaw tryb multicast.	UMIEŚCIĆ	/api/state/mcast/aktualizacja/	{„tryb”:”nadawca”, „adres”: , „port”: , „typ”:”rtp”} lub {„tryb”:”nadawca”, „adres”: , „port”: , „typ”:”poli”, „grupa”:1} **Uwaga**: Jeśli przed tym poleceniem zostanie użyta opcja Sterowanie/Dźwięk/Start, dźwięk zostanie odtworzony przy użyciu bieżących ustawień web UI.	Brak	8301	> 5.0
Wstaw wartość do określonego parametru z ładunku JSON.	UMIEŚCIĆ	/api/ustawienia	parametr: {wartość} np. {“audio.page.vol”: “-3dB”}	Brak	8180(G2) 8186 8190 8190S 8301 8373	> 3.3

 Polecenia prostego interfejsu sterowania (SCI)

Wszystkie polecenia SCI są żądaniami GET i mają wspólne parametry „usi” i „admin” służące do uwierzytelniania.
Exampna:
POBIERZ http:// /sci/controls/door/unlock?usr=admin&pwd=algo&doorid=local

Opis	URI	Dodatkowy Ładunek Parametry	Produkty	FW
Odblokuj drzwi. „lokalny” steruje lokalnym przekaźnikiem „netdc1” steruje zdalnym kontrolerem drzwi sieciowych (8063)	/sci/controls/do lub/odblokuj	doorid: {lokalny, netdc1} *Opcjonalny	8039 8028(G2) 8201 8063	> 3.3
Zamknij drzwi.	/sci/controls/do lub/lock	doorid: {lokalny, netdc1} *Opcjonalny	8039 8028(G2) 8201 8063	> 3.3
Zagraj dźwięk raz lub zapętl go.	/sci/controls/do ne/start	ścieżka: {tone} np. chime.wav pętla: {prawda, fałsz} lub {0, 1}	Wszystko	> 3.3
Zatrzymaj dźwięk.	/sci/controls/to ne/stop	Brak	Wszystko	> 3.3
Włącz stroboskop o pożądanych parametrach koloru i wzoru.	/sci/controls/strobe/start	wzór: {0 – 15} kolor1: {niebieski, czerwony, bursztynowy, zielony} kolor2: {niebieski, czerwony, bursztynowy, zielony} ledlvl: {1 – 255} holdover: {true, false}	8128(G2) 8138 8190S	> 3.3
Zatrzymaj stroboskop.	/sci/controls/strobe/stop	Brak	8128(G2) 8138 8190S	> 3.3

Dokumenty / Zasoby

	Interfejs API RESTful ALGO [plik PDF] Instrukcja użytkownika AL061-GU-GF000API-001-R0, AL061-GU-CP00TEAM-001-R0, API RESTful, API RESTful
	Interfejs API RESTful ALGO [plik PDF] Instrukcja użytkownika AL061-GU-CP000API-230717, API RESTful, API RESTful

Odniesienia

• Instrukcja obsługi