ALGO RESTful API

Informace o produktu: RESTful API Guide

Algo RESTful API umožňuje uživatelům přistupovat, manipulovat a spouštět akce na Algo IP Endpointech v jejich síti prostřednictvím požadavků HTTP/HTTPS. Tento dokument poskytuje jednotnou a předdefinovanou sadu bezstavových operací, které lze použít k interakci se zařízeními Algo. Rozhraní API podporuje požadavky HTTP/HTTPS GET, POST a PUT s datovými částmi JSON.

Autentizace

S Algo RESTful API jsou k dispozici tři typy ověřování:

• Standardní ověřování (ve výchozím nastavení povoleno)
• Základní ověření (volitelné)
• Žádná metoda ověřování (nedoporučuje se, pouze pro účely testování)

Návod k použití produktu: RESTful API

Předpoklady

Před povolením RESTful API se ujistěte, že zařízení má připojení k internetu, aby se dostalo na předem nakonfigurované servery NTP. Pokud není k dispozici připojení k internetu, nakonfigurujte místní server NTP a zadejte jeho IP adresu.

Povolení RESTful API

1. Přihlaste se do zařízení web rozhraní a přejděte na kartu Správce pokročilých nastavení.
2. Přejděte dolů do sekce Podpora API a povolte RESTful API.
3. Nastavte požadované heslo (výchozí heslo: algo). Všimněte si, že standardní ověřování je ve výchozím nastavení povoleno.

Povolení základního ověřování (volitelné)

1. V web rozhraní, přejděte na kartu Údržba systému a stáhněte si konfiguraci file.
2. Otevřete konfiguraci file pomocí libovolného textového editoru a přidejte následující řádek: api.auth.basic = 1
3. Uložte a nahrajte upravenou konfiguraci file zpět do zařízení pomocí Obnovit konfiguraci File na kartě Údržba systému.

Povolení bez metody ověřování (volitelné)

Chcete-li povolit metodu bez ověřování, ponechte pole RESTful API Password prázdné. Tato metoda se nedoporučuje a měla by být používána pouze pro účely testování, protože neposkytuje žádné zabezpečení.

Povolení rozhraní jednoduchého ovládání (volitelné)

1. Na web rozhraní, přejděte na kartu Údržba systému a stáhněte si konfiguraci file.
2. Otevřete konfiguraci file pomocí textového editoru a přidejte dva řádky. Změňte heslo na požadované.
3. Admin.web.sci = 1
4. Sci.admin.pwd =
5. Uložte a nahrajte upravenou konfiguraci file zpět do zařízení pomocí Obnovit konfiguraci File na kartě Údržba systému.

Autentizace Sample Kód

Prosím o email podpora@algosolutions.com pokud byste chtěli standardní nebo základní ověření sampkód.
Pro další podporu zavolejte 604-454-3792 nebo email podpora@algosolutions.com

Informační oznámení

Poznámka
Poznámka označuje užitečné aktualizace, informace a pokyny, které je třeba dodržovat

Zřeknutí se odpovědnosti

Informace obsažené v tomto dokumentu jsou považovány za přesné ve všech ohledech, ale nejsou zaručeny společností Algo. Tyto informace se mohou změnit bez předchozího upozornění a neměly by být žádným způsobem vykládány jako závazek společnosti Algo nebo kterékoli z jejích přidružených společností nebo dceřiných společností. Algo a jeho přidružené společnosti a dceřiné společnosti nenesou žádnou odpovědnost za jakékoli chyby nebo opomenutí v tomto dokumentu. K začlenění takových změn mohou být vydány revize tohoto dokumentu nebo jeho nová vydání. Algo nepřebírá žádnou odpovědnost za škody nebo nároky vyplývající z jakéhokoli použití této příručky nebo takových produktů, softwaru, firmwaru a/nebo hardwaru. Žádná část tohoto dokumentu nemůže být reprodukována nebo přenášena v jakékoli formě nebo jakýmikoli prostředky – elektronickými nebo mechanickými – pro jakýkoli účel bez písemného souhlasu společnosti Algo.
Pro další informace nebo technickou pomoc v Severní Americe se prosím obraťte na tým podpory společnosti Algo:

Technická podpora Algo
1-604-454-3792
podpora@algosolutions.com

©2022 Algo je registrovaná ochranná známka společnosti Algo Communication Products Ltd.
Všechna práva vyhrazena. Všechny ostatní ochranné známky jsou majetkem příslušných vlastníků. Všechny specifikace se mohou bez upozornění změnit.

 GENERÁL

Zavedení

Tento dokument popisuje, jak lze Algo RESTful API použít k přístupu, manipulaci a spouštění akcí na koncových bodech Algo IP ve vaší síti prostřednictvím požadavků HTTP/HTTPS a také několik různých metod ověřování s různou úrovní zabezpečení. Požadující systémy mohou komunikovat se zařízeními Algo prostřednictvím jednotné a předem definované sady bezstavových operací definovaných v tomto dokumentu. Požadavky jsou odesílány na URI zdroje s datovou částí JSON a vyvolávají odpověď JSON. Požadavky HTTP/HTTPS GET, POST a PUT jsou odesílány na identifikátor URI zdroje spolu s datovou částí JSON (seznam datových částí naleznete v části příkazy).

 Autentizace

Existují tři typy ověřování:

•  Standardní (doporučeno)
•  Základní
•  Žádné (nedoporučuje se)

Standardní ověřování používá kód pro ověřování zpráv založený na hash (HMAC) s výtahem kódovaným SHA-256. Základní ověřování používá kódování Base64 a mělo by být používáno pouze přes HTTPS. Žádné ověřování by nemělo být používáno pouze s extrémní opatrností, protože neposkytuje žádné ověřování. Další podrobnosti naleznete v části Požadavky na ověření.

NASTAVENÍ A KONFIGURACE

Předpoklady

•  Tento dokument předpokládá, že koncový bod Algo používá firmware verze 3.3 nebo vyšší.
•  Časový rozdíl mezi žadatelem a zařízeními Algo by měl být menší než 30 sekund, aby bylo možné použít standardní ověřování.
• Ujistěte se, že se používá protokol NTP (Network Time Protocol). Adresy vlastních NTP serverů lze konfigurovat v záložce Pokročilé nastavení → Čas.

Poznámka
Přednastavené NTP servery jsou veřejně hostované, proto je k jejich dosažení nutné připojení k internetu. Pokud není k dispozici připojení k internetu, nakonfigurujte místní server NTP a zadejte jeho IP adresu.

• Ujistěte se, že systémový čas zařízení Algo je nastaven na správné časové pásmo. To lze provést přechodem na kartu Pokročilá nastavení → Čas.

 Povolení RESTful API

1. Přihlaste se do web rozhraní a přejděte na kartu Upřesnit nastavení → Správce.
2. Přejděte dolů do sekce Podpora API, povolte RESTful API a nastavte heslo podle potřeby (výchozí heslo: algo)
   Poznámka
   Standardní ověřování je ve výchozím nastavení povoleno.

Povolit základní ověřování (volitelné)

1. V web rozhraní, přejděte na kartu Systém → Údržba a stáhněte si konfiguraci file.
2. Otevřete konfiguraci file pomocí libovolného textového editoru a přidejte následující řádek: api.auth.basic = 1
3.  Uložte a nahrajte upravenou konfiguraci file zpět do zařízení pomocí Obnovit konfiguraci File na kartě Systém → Údržba.

Žádná metoda ověření (volitelné)

Chcete-li povolit metodu bez ověřování, ponechte pole RESTful API Password prázdné. Tato metoda se nedoporučuje a měla by být používána pouze pro účely testování, protože neposkytuje žádné zabezpečení.

Povolení rozhraní jednoduchého ovládání (volitelné)

1. Na web rozhraní, přejděte na kartu Systém → Údržba a stáhněte si konfiguraci file.
2.  Otevřete konfiguraci file pomocí textového editoru a přidejte dva řádky. Změň na vaše požadované heslo. Admin.web.sci = 1
   Sci.admin.pwd =
3.  Uložte a nahrajte upravenou konfiguraci file zpět do zařízení pomocí Obnovit konfiguraci File na kartě Systém → Údržba.

POŽADAVKY NA OVĚŘENÍ

Prosím o email podpora@algosolutions.com pokud byste chtěli standardní nebo základní ověření sampkód.

Standardní požadavek na autentizaci s JSON Payload

Povinná záhlaví v požadavku HTTP/HTTPS
> Typ obsahu: „application/json“
> Obsah-MD5: [content_md5] Přample
Content-MD5: 74362cc86588b2b3c5a4491baf80375b

Autorizace: hmac admin:[nonce]:[hmac_output]
Autorizační hlavičky se skládají z:

1. Řetězec 'hmac admin' následovaný dvojtečkou ':'.
2. Nonce – Náhodná nebo neopakující se hodnota následovaná dvojtečkou „:“.
3. Hmac_output – generováno heslem RESTful API (tajný klíč) nakonfigurovaným na vašem zařízení a vstupem HMAC, jak je uvedeno níže:
   [request_metoda]:[request_uri]:[content_md5]:[content_type]:[timestamp]:[nikdy]

Vstup HMAC napřample: (jako tajný klíč používá 'algo')
POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936 Vygenerujte HMAC s heslem a vstupním řetězcem HMAC jako výtah pomocí SHA-256:
Výstup HMAC napřample: 2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330

Datum: den, datum měsíc, rok hod:min:sec GMT
Example
Datum: Čt, 22. září 2022 02:33:07 GMT
Standardní autentizace s užitečným zatížením napřampten:

 Standardní požadavek na autentizaci bez JSON Payload

Identické jako 3.1 s vynechanými záhlavími souvisejícími s obsahem/hmac vstupem.
Vstup HMAC: [metoda_požadavku]:[uri_požadavku]:[časamp]:[nonce] Vstup HMAC example: (jako tajný klíč používá 'algo')
GET:/api/settings/audio.page.vol:1601312252:49936
Vygenerujte HMAC s heslem a vstupním řetězcem HMAC pomocí SHA-256:
Výstup HMAC napřample: c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8
Standardní autentizace bez užitečného zatížení, napřampten:

 Základní požadavek na ověření

Tato metoda ověřování by měla být používána opatrně, protože je méně bezpečná než standardní metoda.

Autorizace: Základní [base64]
Exampten:
Oprávnění: Základní YWRtaW46YWxnbwo=
Základní autentizace napřampten:

PŘÍKAZY

 RESTful API příkazy

Níže je uveden seznam všech podporovaných příkazů API.

Poznámka
Požadavek PUT změní nebo vytvoří trvalý prostředek, který přežije restart, zatímco požadavek POST řídí pouze zařízení pro aktuální relaci.

Popis	Metoda	URI	Užitečné zatížení Parametry	Návrat Example	Produkt	FW
Načte hodnotu konkrétního parametru.	ZÍSKAT	/api/settings/[název-klíče] Př./api/settings/audio.page.vol	N/A	{“audio.page.vol”: “-18dB”}	Vše	> 3.3
Vraťte hladinu okolního hluku měřenou v decibelech. Kompenzace okolního hluku musí být povolena na kartě Základní nastavení -> Funkce.	ZÍSKAT	/api/info/audio.noise.level	N/A	{"audio.noise.level": 72}	Reproduktory Displej Reproduktory	> 3.3
Extrahujte stav vstupní svorky relé.	ZÍSKAT	/api/info/input.relay.status	N/A	{“input.relay.status“: „idle“} nebo {“input.relay.status“: „active“}	Všechny produkty s reléovým vstupem kromě 8063. Viz níže.	> 4.1
Extrahujte stav svorek Input 1 nebo Input 2.	ZÍSKAT	/api/info/input.relay1.status nebo /api/info/input.relay2.status	N/A	{“input.relay1.status”: “idle”} nebo {”input.relay1.status”: “active”}	8063	> 4.1
Vyvolejte seznam tónů files aktuálně nainstalováno.	ZÍSKAT	/api/info/tonelist	N/A	{“tonelist“:[“bell-na.wav”,”bell uk.wav”,”buzzer.wav”,…]}	Vše	> 5.0
Načtěte informace o zařízení zobrazené na stránce Stav.	ZÍSKAT	/api/info/status	N/A	Úplný seznam informací na kartě Stav.	Vše	> 5.4

Získejte informace o produktu zobrazené na stránce O produktu.	ZÍSKAT	/api/info/about	N/A	Všechny informace uvedené na kartě O aplikaci.	Vše	> 5.4
Aktivujte stroboskop s požadovanou barvou a parametry vzoru.	ZVEŘEJNIT	/api/controls/strobe/start	vzor: {0 – 15} barva1: {modrá, červená, jantarová, zelená} barva2: {modrá, červená, jantarová, zelená} ledlvl: {1 – 255} holdover: {pravda, nepravda}	N/A	8128 (G2) 8138 8190S	> 3.3
Zastavte stroboskop.	ZVEŘEJNIT	/api/controls/strobe/stop	N/A	N/A	8128 (G2) 8138 8190S	> 3.3
Přehrajte tón jednou nebo jej opakujte.	ZVEŘEJNIT	/api/controls/tone/start	cesta: {tón} tzn. zvonkohra.wav smyčka: {true, false} nebo {0, 1} např. {"cesta":"chime.wav", "smyčka":true}	N/A	Reproduktory 8301 8373 8028 (G2) 8201 8039	> 3.3
Zastavte tón.	ZVEŘEJNIT	/api/controls/tone/stop	N/A	N/A	Reproduktory 8301 8373 8028 (G2) 8201 8039	> 3.3
Zavolejte na telefonní linku s předem nahranou zprávou.	ZVEŘEJNIT	/api/controls/call/start	{“prodloužení”:”2099″, “tón”:”gong.wav”, “interval”:”0″, “maxdur”:”10″}	N/A	Reproduktory 8301 8410 8420	> 3.3
Ukončete hovor.	ZVEŘEJNIT	/api/controls/call/stop	N/A	N/A	Reproduktory 8301 8410 8420	> 3.3

Zahajte jednosměrné volání stránky. Zařízení bude přijímat audio stream z cílového rozšíření.	ZVEŘEJNIT	/api/controls/call/page	{"rozšíření":" “}	N/A	Reproduktory 8410 8420	> 5.3.4
Restartujte cílový koncový bod.	ZVEŘEJNIT	/api/controls/reboot	N/A	N/A	Vše	> 3.3
Odemkněte dveře. „local“ ovládá místní relé „netdc1“ ovládá vzdálený síťový ovladač dveří (8063)	ZVEŘEJNIT	/api/controls/door/unlock	doorid: {local, netdc1} *Volitelný	N/A	8039 8028 (G2) 8201 8063	> 3.3
Zamknout dveře.	ZVEŘEJNIT	/api/controls/door/lock	doorid: {local, netdc1} *Volitelný	N/A	8039 8028 (G2) 8201 8063	> 3.3
Povolte 24V relé pomocného výstupu.	ZVEŘEJNIT	api/controls/24v/enable	N/A	N/A	8063	> 5.0
Vypněte 24V pomocné výstupní relé.	ZVEŘEJNIT	api/controls/24v/disable	N/A	N/A	8063	> 5.0
Povolte výstupní relé.	ZVEŘEJNIT	/api/controls/relay/enable	N/A	N/A	8063	> 5.0
Deaktivujte výstupní relé.	ZVEŘEJNIT	/api/controls/relay/disable	N/A	N/A	8063	> 5.0
Zkontrolujte firmware serveru Algo pro nejnovější verzi firmwaru.	ZVEŘEJNIT	/api/controls/upgrade/check	N/A	{“verze“: „aktualizováno“} nebo {"verze": " “}	Vše	> 4.1
Zkontrolujte firmware serveru Algo pro nejnovější verzi firmwaru a upgradujte na tuto verzi.	ZVEŘEJNIT	/api/controls/upgrade/start	N/A	{“stav“: „aktualizováno“} nebo {“stav“: „upgrade “, “url“: url>} nebo {"stav": " “}	Vše	> 4.1
Zobrazte na obrazovce obrázek nebo vzor.	ZVEŘEJNIT	/api/controls/screen/start	Vidět níže	N/A	8410 8420	> 5.3.4
Zastavte vzor obrazovky a vraťte se na výchozí obrazovku.	ZVEŘEJNIT	/api/controls/screen/stop	N/A	N/A	8410 8420	> 5.3.4

Restartujte hlavní aplikaci.	ZVEŘEJNIT	/api/controls/reload	N/A	N/A	Vše	> 5.3.4
Začněte poslouchat přímý audio stream. Nakonfigurujte číslo portu, na který je stream odesílán.	ZVEŘEJNIT	/api/controls/rx/start	{"přístav": }	N/A	Vše	> 5.3.4
Přestaňte poslouchat přímý audio stream.	ZVEŘEJNIT	/api/controls/rx/stop	N/A	N/A	Vše	> 5.3.4
Nastavte režim vícesměrového vysílání.	DÁT	/api/state/mcast/update/	{"režim":"odesílatel", "adresa": , "přístav": , “type”:”rtp”} nebo {”režim”:”odesílatel”, “adresa”: , "přístav": , "typ":"poly", "skupina":1} **Poznámka**: Pokud před tímto příkazem použijete ovládací prvky/tón/spuštění, zvuk se přehraje podle aktuálního nastavení na web UI.	N/A	8301	> 5.0
Vložte hodnotu do konkrétního parametru z datové části JSON.	DÁT	/api/settings	parametr: {value} např. {“audio.page.vol”: “-3dB”}	N/A	8180 (G2) 8186 8190 8190S 8301 8373	> 3.3

 Příkazy jednoduchého ovládacího rozhraní (SCI).

Všechny příkazy SCI jsou požadavky GET a mají společné parametry „usi“ a „admin“ pro ověřování.
Exampten:
ZÍSKEJTE http:// /sci/controls/door/unlock?usr=admin&pwd=algo&doorid=local

Popis	URI	Další Užitečné zatížení Parametry	Produkty	FW
Odemkněte dveře. „local“ ovládá místní relé „netdc1“ ovládá vzdálený síťový ovladač dveří (8063)	/sci/controls/do or/unlock	doorid: {local, netdc1} *Volitelný	8039 8028 (G2) 8201 8063	> 3.3
Zamknout dveře.	/sci/controls/do or/lock	doorid: {local, netdc1} *Volitelný	8039 8028 (G2) 8201 8063	> 3.3
Přehrajte tón jednou nebo jej opakujte.	/sci/controls/to ne/start	cesta: {tón} tzn. zvonkohra.wav smyčka: {true, false} nebo {0, 1}	Vše	> 3.3
Zastavte tón.	/sci/controls/to ne/stop	N/A	Vše	> 3.3
Aktivujte stroboskop s požadovanou barvou a parametry vzoru.	/sci/controls/strobe/start	vzor: {0 – 15} barva1: {modrá, červená, jantarová, zelená} barva 2: {modrá, červená, jantarová, zelená} ledlvl: {1 – 255} holdover: {pravda, nepravda}	8128 (G2) 8138 8190S	> 3.3
Zastavte stroboskop.	/sci/controls/strobe/stop	N/A	8128 (G2) 8138 8190S	> 3.3

Dokumenty / zdroje

	ALGO RESTful API [pdfUživatelská příručka AL061-GU-GF000API-001-R0, AL061-GU-CP00TEAM-001-R0, RESTful API, RESTful, API
	ALGO RESTful API [pdfUživatelská příručka AL061-GU-CP000API-230717, RESTful API, RESTful, API

Reference

• Uživatelská příručka