ALGO RESTful API

Produktinformation: RESTful API Guide

Algo RESTful API tillåter användare att komma åt, manipulera och utlösa åtgärder på Algo IP-slutpunkter i deras nätverk genom HTTP/HTTPS-förfrågningar. Detta dokument tillhandahåller en enhetlig och fördefinierad uppsättning tillståndslösa operationer som kan användas för att interagera med Algo-enheter. API:et stöder HTTP/HTTPS GET-, POST- och PUT-förfrågningar med JSON-nyttolaster.

Autentisering

Det finns tre typer av autentiseringar tillgängliga med Algo RESTful API:

• Standardautentisering (aktiverad som standard)
• Grundläggande autentisering (valfritt)
• Ingen autentiseringsmetod (rekommenderas inte, endast för teständamål)

Produktanvändningsinstruktioner: RESTful API

Förutsättningar

Innan du aktiverar RESTful API, se till att enheten har en internetanslutning för att nå de förkonfigurerade NTP-servrarna. Om ingen internetanslutning är tillgänglig, konfigurera en lokal NTP-server och ange dess IP-adress.

Aktiverar RESTful API

1. Logga in på enhetens web gränssnittet och navigera till fliken Avancerade inställningar Admin.
2. Rulla ned till avsnittet API-support och aktivera RESTful API.
3. Ställ in önskat lösenord (standardlösenord: algo). Observera att standardautentisering är aktiverad som standard.

Aktivera grundläggande autentisering (valfritt)

1. I den web gränssnitt, navigera till fliken Systemunderhåll och ladda ner konfigurationen file.
2. Öppna konfigurationen file med valfri textredigerare och lägg till följande rad: api.auth.basic = 1
3. Spara och ladda upp den ändrade konfigurationen file tillbaka till enheten med hjälp av Återställ konfiguration File funktionen på fliken Systemunderhåll.

Aktiverar ingen autentiseringsmetod (valfritt)

För att aktivera metoden för ingen autentisering, lämna fältet RESTful API-lösenord tomt. Denna metod rekommenderas inte och bör endast användas för teständamål eftersom den inte ger någon säkerhet.

Aktivera enkelt kontrollgränssnitt (valfritt)

1. På web gränssnitt, navigera till fliken Systemunderhåll och ladda ner konfigurationen file.
2. Öppna konfigurationen file använd en textredigerare och lägg till två rader. Ändra till ditt önskade lösenord.
3. Administration.web.sci = 1
4. Sci.admin.pwd =
5. Spara och ladda upp den ändrade konfigurationen file tillbaka till enheten med hjälp av Återställ konfiguration File funktionen på fliken Systemunderhåll.

Autentisering Sample Kod

Vänligen maila support@algosolutions.com om du vill ha en standard- eller grundläggande autentiseringampkoden.
För ytterligare support, ring 604-454-3792 eller mejla support@algosolutions.com

Informationsmeddelanden

Notera
Obs anger användbara uppdateringar, information och instruktioner som bör följas

Ansvarsfriskrivning

Informationen i detta dokument anses vara korrekt i alla avseenden men garanteras inte av Algo. Informationen kan ändras utan föregående meddelande och ska inte på något sätt tolkas som ett åtagande från Algo eller något av dess dotterbolag eller dotterbolag. Algo och dess dotterbolag och dotterbolag tar inget ansvar för eventuella fel eller utelämnanden i detta dokument. Revideringar av detta dokument eller nya upplagor av det kan komma ut för att införliva sådana ändringar. Algo tar inget ansvar för skador eller anspråk som härrör från någon användning av denna manual eller sådana produkter, mjukvara, fast programvara och/eller hårdvara. Ingen del av detta dokument får reproduceras eller överföras i någon form eller på något sätt – elektroniskt eller mekaniskt – för något syfte utan skriftligt tillstånd från Algo.
För ytterligare information eller teknisk assistans i Nordamerika, vänligen kontakta Algos supportteam:

Algo teknisk support
1-604-454-3792
support@algosolutions.com

©2022 Algo är ett registrerat varumärke som tillhör Algo Communication Products Ltd.
Alla rättigheter förbehållna. Alla andra varumärken tillhör sina respektive ägare. Alla specifikationer kan ändras utan föregående meddelande.

 ALLMÄN

Introduktion

Det här dokumentet beskriver hur Algo RESTful API kan användas för att komma åt, manipulera och utlösa åtgärder på Algo IP-slutpunkter i ditt nätverk genom HTTP/HTTPS-förfrågningar, samt ett par olika autentiseringsmetoder med olika säkerhetsnivåer. Begärande system kan interagera med Algo-enheter genom en enhetlig och fördefinierad uppsättning tillståndslösa operationer som definieras i detta dokument. Förfrågningar görs till en resurs URI med en JSON-nyttolast och framkallar ett JSON-svar. HTTP/HTTPS GET-, POST- och PUT-förfrågningar görs till resurs-URI tillsammans med JSON-nyttolasten (se kommandoavsnittet för en lista över nyttolaster).

 Autentisering

Det finns tre typer av autentiseringar:

•  Standard (rekommenderas)
•  Grundläggande
•  Ingen (rekommenderas inte)

Standardautentiseringen använder en Hash-baserad meddelandeautentiseringskod (HMAC) med en SHA-256-kodad sammanfattning. Grundläggande autentisering använder Base64-kodning och bör endast användas över HTTPS. Ingen autentisering bör endast användas med extrem försiktighet eftersom den inte ger någon autentisering. Se avsnittet Autentiseringskrav för mer information.

INSTÄLLNING OCH KONFIGURATION

Förutsättningar

•  Det här dokumentet förutsätter att Algo-slutpunkten kör firmwareversion 3.3 eller högre.
•  Tidsskillnaden mellan begäranden och Algo-enheterna bör vara mindre än 30 sekunder för att använda standardautentisering.
• Se till att NTP (Network Time Protocol) används. Adresserna för anpassade NTP-servrar kan konfigureras i fliken Avancerade inställningar → Tid.

Notera
De förkonfigurerade NTP-servrarna är offentliga värdar, därför krävs internetanslutning för att nå den. Om ingen internetanslutning är tillgänglig, konfigurera en lokal NTP-server och ange dess IP-adress.

• Se till att Algo-enhetens systemtid är justerad till rätt tidszon. Detta kan göras genom att navigera till fliken Avancerade inställningar → Tid.

 Aktiverar RESTful API

1. Logga in på web gränssnittet och navigera till fliken Avancerade inställningar → Admin.
2. Rulla ned till avsnittet API-support, aktivera RESTful API och ställ in lösenordet som önskat (standardlösenord: algo)
   Notera
   Standardautentisering är aktiverad som standard.

Aktivera grundläggande autentisering (valfritt)

1. I den web gränssnitt, navigera till fliken System → Underhåll och ladda ner konfigurationen file.
2. Öppna konfigurationen file med valfri textredigerare och lägg till följande rad: api.auth.basic = 1
3.  Spara och ladda upp den ändrade konfigurationen file tillbaka till enheten med hjälp av Återställ konfiguration File funktionen på fliken System → Underhåll.

Ingen autentiseringsmetod (valfritt)

För att aktivera metoden för ingen autentisering, lämna fältet RESTful API-lösenord tomt. Denna metod rekommenderas inte och bör endast användas för teständamål eftersom den inte ger någon säkerhet.

Aktivera enkelt kontrollgränssnitt (valfritt)

1. På web gränssnitt, navigera till fliken System → Underhåll och ladda ner konfigurationen file.
2.  Öppna konfigurationen file använd en textredigerare och lägg till två rader. Ändra till ditt önskade lösenord. Administration.web.sci = 1
   Sci.admin.pwd =
3.  Spara och ladda upp den ändrade konfigurationen file tillbaka till enheten med hjälp av Återställ konfiguration File funktionen på fliken System → Underhåll.

AUTENTICERINGSKRAV

Vänligen maila support@algosolutions.com om du vill ha en standard- eller grundläggande autentiseringampkoden.

Standard autentiseringsbegäran med en JSON-nyttolast

Obligatoriska rubriker i HTTP/HTTPS-begäran
> Innehållstyp: "application/json"
> Innehåll-MD5: [content_md5] Example
Content-MD5: 74362cc86588b2b3c5a4491baf80375b

Auktorisering: hmac admin:[nonce]:[hmac_output]
Auktoriseringshuvudena består av:

1. Strängen 'hmac admin' följt av ett kolon ':'.
2. Nonce – Ett slumpmässigt eller icke-repeterande värde, följt av ett kolon ':'.
3. Hmac_output – genererad av RESTful API-lösenordet (hemlig nyckel) konfigurerat på din enhet och HMAC-ingången enligt nedan:
   [request_method]:[request_uri]:[content_md5]:[content_type]:[timestamp]:[inte]

HMAC-ingång example: (använder 'algo' som den hemliga nyckeln)
POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936 Generera HMAC med lösenord och HMAC-indatasträng som sammandrag med SHA-256:
HMAC-utgång example: 2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330

Datum: dag, datum månad, år hr:min:sek GMT
Example
Datum: Tors, 22 Sept, 2022 02:33:07 GMT
Standardautentisering med nyttolast exampde:

 Standard autentiseringsbegäran utan en JSON-nyttolast

Identisk med 3.1 med innehållsrelaterade rubriker/hmac-ingång utelämnad.
HMAC-ingång: [request_method]:[request_uri]:[timestamp]:[ej] HMAC-ingång example: (använder 'algo' som den hemliga nyckeln)
GET:/api/settings/audio.page.vol:1601312252:49936
Generera HMAC med lösenord och HMAC-ingångssträng med SHA-256:
HMAC-utgång example: c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8
Standardautentisering utan nyttolast exampde:

 Grundläggande autentiseringsbegäran

Denna autentiseringsmetod bör användas med försiktighet eftersom den är mindre säker än standardmetoden.

Auktorisering: Grundläggande [base64]
Exampde:
Auktorisering: Grundläggande YWRtaW46YWxnbwo=
Grundläggande autentisering exampde:

KOMMANDO

 RESTful API-kommandon

Nedan finns en lista över alla API-kommandon som stöds.

Notera
En PUT-begäran ändras eller skapar en permanent resurs som överlever en omstart, medan en POST-begäran endast styr enheten för den aktuella sessionen.

Beskrivning	Metod	URI	Nyttolast Parametrar	Återvända Example	Produkt	FW
Hämta värdet för en specifik parameter.	FÅ	/api/settings/[nyckelnamn] Ex./api/settings/audio.page.vol	N/A	{“audio.page.vol”: “-18dB”}	Alla	> 3.3
Returnera den omgivande ljudnivån mätt i decibel. Kompensation för omgivande brus måste vara aktiverad i Grundinställningar -> Fliken Funktioner.	FÅ	/api/info/audio.noise.level	N/A	{“audio.noise.level”: 72}	Högtalare Display Högtalare	> 3.3
Extrahera status för reläingångsterminalen.	FÅ	/api/info/input.relay.status	N/A	{“input.relay.status”: “idle”} eller {“input.relay.status”: “active”}	Alla produkter med reläingång, förutom 8063. Se nedan.	> 4.1
Extrahera status för ingång 1 eller ingång 2 terminaler.	FÅ	/api/info/input.relay1.status eller /api/info/input.relay2.status	N/A	{“input.relay1.status”: “idle”} eller {“input.relay1.status”: “active”}	8063	> 4.1
Hämta listan med toner fileär för närvarande installerat.	FÅ	/api/info/tonelist	N/A	{“tonelist”:[“bell-na.wav”,,”bell uk.wav”,,”buzzer.wav”,...]}	Alla	> 5.0
Hämta enhetsinformationen som visas på statussidan.	FÅ	/api/info/status	N/A	Fullständig lista med information från fliken Status.	Alla	> 5.4

Hämta produktinformationen som visas på sidan Om.	FÅ	/api/info/about	N/A	All information finns på fliken Om.	Alla	> 5.4
Aktivera stroben med önskade färg- och mönsterparametrar.	POSTA	/api/controls/strobe/start	mönster: {0 – 15} färg1: {blå, röd, bärnsten, grön} färg2: {blå, röd, bärnsten, grön} ledlvl: {1 – 255} kvarhållande: {true, false}	N/A	8128(G2) 8138 8190S	> 3.3
Stoppa stroben.	POSTA	/api/controls/strobe/stop	N/A	N/A	8128(G2) 8138 8190S	> 3.3
Spela en ton en gång eller loopa den.	POSTA	/api/controls/tone/start	sökväg: {ton} dvs. chime.wav loop: {true, false} eller {0, 1} t.ex. {"sökväg":"chime.wav", "loop":true}	N/A	Högtalare 8301 8373 8028(G2) 8201 8039	> 3.3
Stoppa tonen.	POSTA	/api/kontroller/tone/stopp	N/A	N/A	Högtalare 8301 8373 8028(G2) 8201 8039	> 3.3
Ring en anknytning med ett förinspelat meddelande.	POSTA	/api/controls/call/start	{“extension”:”2099″, “tone”:”gong.wav”, “intervall”:”0″, “maxdur”:”10″}	N/A	Högtalare 8301 8410 8420	> 3.3
Avsluta samtalet.	POSTA	/api/controls/call/stop	N/A	N/A	Högtalare 8301 8410 8420	> 3.3

Initiera ett enkelriktat sidsamtal. Enheten kommer att ta emot ljudströmmen från måltillägget.	POSTA	/api/controls/call/page	{"förlängning":" ”}	N/A	Högtalare 8410 8420	> 5.3.4
Starta om målslutpunkten.	POSTA	/api/controls/reboot	N/A	N/A	Alla	> 3.3
Lås upp dörren. "local" styr det lokala reläet "netdc1" styr fjärrnätverkets dörrkontroller (8063)	POSTA	/api/kontroller/dörr/lås upp	doorid: {local, netdc1} *Frivillig	N/A	8039 8028(G2) 8201 8063	> 3.3
Låsa dörren.	POSTA	/api/kontroller/dörr/lås	doorid: {local, netdc1} *Frivillig	N/A	8039 8028(G2) 8201 8063	> 3.3
Aktivera 24v aux ut-relä.	POSTA	api/controls/24v/enable	N/A	N/A	8063	> 5.0
Inaktivera 24v aux ut-reläet.	POSTA	api/kontroller/24v/avaktivera	N/A	N/A	8063	> 5.0
Aktivera utgångsreläet.	POSTA	/api/controls/relay/enable	N/A	N/A	8063	> 5.0
Inaktivera utgångsreläet.	POSTA	/api/controls/relay/disable	N/A	N/A	8063	> 5.0
Kontrollera Algos firmware-server för senaste firmware-version.	POSTA	/api/controls/upgrade/check	N/A	{"version": "updated"} eller {"version": " ”}	Alla	> 4.1
Kontrollera Algos firmware-server för senaste firmware-version och uppgradera till den versionen.	POSTA	/api/controls/upgrade/start	N/A	{“status”: “updated”} eller {"status": "uppgraderar ”, “url”: url>} eller {"status": " ”}	Alla	> 4.1
Visa en bild eller ett mönster på skärmen.	POSTA	/api/kontroller/skärm/start	Se nedan	N/A	8410 8420	> 5.3.4
Stoppa skärmmönstret och återgå till standardskärmen.	POSTA	/api/kontroller/skärm/stopp	N/A	N/A	8410 8420	> 5.3.4

Starta om huvudprogrammet.	POSTA	/api/controls/reload	N/A	N/A	Alla	> 5.3.4
Börja lyssna på en direkt ljudström. Konfigurera portnumret som strömmen skickas till.	POSTA	/api/controls/rx/start	{"hamn": }	N/A	Alla	> 5.3.4
Sluta lyssna på en direkt ljudström.	POSTA	/api/controls/rx/stop	N/A	N/A	Alla	> 5.3.4
Ställ in multicast-läget.	SÄTTA	/api/state/mcast/update/	{"mode":"avsändare", "adress": , "port": , "typ":"rtp"} eller {"mode":"avsändare", "adress": , "port": , "typ":"poly", "grupp":1} **Obs**: Om kontroller/ton/start används före detta kommando, kommer tonen att spelas med nuvarande inställningar på web UI.	N/A	8301	> 5.0
Infoga ett värde till en specifik parameter från JSON-nyttolasten.	SÄTTA	/api/inställningar	parameter: {värde} t.ex. {“audio.page.vol”: “-3dB”}	N/A	8180(G2) 8186 8190 8190S 8301 8373	> 3.3

 Simple Control Interface (SCI) kommandon

Alla SCI-kommandon är GET-förfrågningar och har de gemensamma parametrarna "usi" och "admin" för autentisering.
Exampde:
HÄMTA http:// /sci/controls/door/unlock?usr=admin&pwd=algo&doorid=local

Beskrivning	URI	Ytterligare Nyttolast Parametrar	Produkter	FW
Lås upp dörren. "local" styr det lokala reläet "netdc1" styr fjärrnätverkets dörrkontroller (8063)	/sci/controls/do eller/lås upp	doorid: {local, netdc1} *Frivillig	8039 8028(G2) 8201 8063	> 3.3
Låsa dörren.	/sci/controls/do eller/lock	doorid: {local, netdc1} *Frivillig	8039 8028(G2) 8201 8063	> 3.3
Spela en ton en gång eller loopa den.	/sci/controls/to ne/start	sökväg: {ton} dvs. chime.wav loop: {true, false} eller {0, 1}	Alla	> 3.3
Stoppa tonen.	/sci/controls/to ne/stop	N/A	Alla	> 3.3
Aktivera stroben med önskade färg- och mönsterparametrar.	/sci/controls/strobe/start	mönster: {0 – 15} färg1: {blå, röd, bärnsten, grön} färg2: {blå, röd, bärnsten, grön} ledlvl: {1 – 255} kvarhållning: {true, false}	8128(G2) 8138 8190S	> 3.3
Stoppa stroben.	/sci/controls/strobe/stop	N/A	8128(G2) 8138 8190S	> 3.3

Dokument/resurser

	ALGO RESTful API [pdf] Användarhandbok AL061-GU-GF000API-001-R0, AL061-GU-CP00TEAM-001-R0, RESTful API, RESTful, API
	ALGO RESTful API [pdf] Användarhandbok AL061-GU-CP000API-230717, RESTful API, RESTful, API

Referenser

• Användarmanual