ALGO RESTful API

Produktinformationen: RESTful API-Leitfaden

Mit der Algo RESTful API können Benutzer über HTTP/HTTPS-Anfragen auf Algo IP-Endpunkte in ihrem Netzwerk zugreifen, diese bearbeiten und Aktionen darauf auslösen. Dieses Dokument stellt einen einheitlichen und vordefinierten Satz zustandsloser Operationen bereit, die für die Interaktion mit Algo-Geräten verwendet werden können. Die API unterstützt HTTP/HTTPS-GET-, POST- und PUT-Anfragen mit JSON-Nutzlasten.

Authentifizierung

Mit der Algo RESTful API stehen drei Arten von Authentifizierungen zur Verfügung:

• Standardauthentifizierung (standardmäßig aktiviert)
• Basisauthentifizierung (optional)
• Keine Authentifizierungsmethode (nicht empfohlen; nur zu Testzwecken)

Anweisungen zur Produktnutzung: RESTful API

Voraussetzungen

Stellen Sie vor der Aktivierung der RESTful-API sicher, dass das Gerät über eine Internetverbindung verfügt, um die vorkonfigurierten NTP-Server zu erreichen. Wenn keine Internetverbindung verfügbar ist, konfigurieren Sie einen lokalen NTP-Server und geben Sie dessen IP-Adresse ein.

Aktivieren der RESTful-API

1. Melden Sie sich beim Gerät an web Benutzeroberfläche und navigieren Sie zur Registerkarte „Admin“ für „Erweiterte Einstellungen“.
2. Scrollen Sie nach unten zum Abschnitt API-Unterstützung und aktivieren Sie die RESTful-API.
3. Legen Sie das gewünschte Passwort fest (Standardpasswort: algo). Beachten Sie, dass die Standardauthentifizierung standardmäßig aktiviert ist.

Aktivieren der Standardauthentifizierung (optional)

1. Im web Navigieren Sie zur Registerkarte „Systemwartung“ und laden Sie die Konfiguration herunter file.
2. Öffnen Sie die Konfiguration file mit einem beliebigen Texteditor und fügen Sie die folgende Zeile hinzu: api.auth.basic = 1
3. Speichern Sie die geänderte Konfiguration und laden Sie sie hoch file mit der Funktion „Konfiguration wiederherstellen“ auf das Gerät zurücksetzen File Funktion auf der Registerkarte „Systemwartung“.

Keine Authentifizierungsmethode aktivieren (optional)

Um die Methode ohne Authentifizierung zu aktivieren, lassen Sie das Feld „RESTful API-Passwort“ leer. Diese Methode wird nicht empfohlen und sollte nur zu Testzwecken verwendet werden, da sie keine Sicherheit bietet.

Aktivieren der einfachen Steuerschnittstelle (optional)

1. Auf der web Navigieren Sie zur Registerkarte „Systemwartung“ und laden Sie die Konfiguration herunter file.
2. Öffnen Sie die Konfiguration file Verwenden Sie einen Texteditor und fügen Sie zwei Zeilen hinzu. Ändern Sie das Passwort in Ihr Wunschpasswort.
3. Administrator.web.sci = 1
4. Sci.admin.pwd =
5. Speichern Sie die geänderte Konfiguration und laden Sie sie hoch file mit der Funktion „Konfiguration wiederherstellen“ auf das Gerät zurücksetzen File Funktion auf der Registerkarte „Systemwartung“.

Authentifizierung Sampder Code

Bitte senden Sie eine E-Mail support@algosolutions.com wenn Sie eine Standard- oder Basisauthentifizierung wünschenampder Code.
Für zusätzliche Unterstützung rufen Sie an 604-454-3792 oder per E-Mail support@algosolutions.com

Informationshinweise

Notiz
Hinweis weist auf nützliche Aktualisierungen, Informationen und Anweisungen hin, die befolgt werden sollten

Haftungsausschluss

Wir gehen davon aus, dass die in diesem Dokument enthaltenen Informationen in jeder Hinsicht korrekt sind, Algo übernimmt jedoch keine Garantie dafür. Die Informationen können ohne vorherige Ankündigung geändert werden und sollten in keiner Weise als Verpflichtung seitens Algo oder einer seiner verbundenen Unternehmen oder Tochtergesellschaften ausgelegt werden. Algo und seine verbundenen Unternehmen und Tochtergesellschaften übernehmen keine Verantwortung für etwaige Fehler oder Auslassungen in diesem Dokument. Es können Überarbeitungen dieses Dokuments oder neue Ausgaben davon herausgegeben werden, um solche Änderungen zu berücksichtigen. Algo übernimmt keine Haftung für Schäden oder Ansprüche, die sich aus der Verwendung dieses Handbuchs oder solcher Produkte, Software, Firmware und/oder Hardware ergeben. Kein Teil dieses Dokuments darf ohne schriftliche Genehmigung von Algo in irgendeiner Form oder mit irgendwelchen Mitteln – elektronisch oder mechanisch – für irgendeinen Zweck reproduziert oder übertragen werden.
Für weitere Informationen oder technische Unterstützung in Nordamerika wenden Sie sich bitte an das Support-Team von Algo:

Technischer Algo-Support
1-604-454-3792
support@algosolutions.com

©2022 Algo ist eine eingetragene Marke von Algo Communication Products Ltd.
Alle Rechte vorbehalten. Alle anderen Marken sind Eigentum ihrer jeweiligen Inhaber. Alle Spezifikationen können ohne vorherige Ankündigung geändert werden.

 ALLGEMEIN

Einführung

In diesem Dokument wird beschrieben, wie die Algo RESTful API verwendet werden kann, um über HTTP/HTTPS-Anfragen sowie über verschiedene Authentifizierungsmethoden mit unterschiedlichen Sicherheitsstufen auf Algo IP-Endpunkte in Ihrem Netzwerk zuzugreifen, diese zu manipulieren und Aktionen auszulösen. Anfordernde Systeme können mit Algo-Geräten über einen einheitlichen und vordefinierten Satz zustandsloser Operationen interagieren, die in diesem Dokument definiert sind. Anfragen werden mit einer JSON-Nutzlast an den URI einer Ressource gestellt und lösen eine JSON-Antwort aus. HTTP/HTTPS-GET-, POST- und PUT-Anfragen werden zusammen mit der JSON-Nutzlast an den Ressourcen-URI gesendet (eine Liste der Nutzlasten finden Sie im Abschnitt „Befehle“).

 Authentifizierung

Es gibt drei Arten von Authentifizierungen:

•  Standard (empfohlen)
•  Basic
•  Keine (nicht empfohlen)

Die Standardauthentifizierung verwendet einen Hash-basierten Nachrichtenauthentifizierungscode (HMAC) mit einem SHA-256-codierten Digest. Die Standardauthentifizierung verwendet Base64-Codierung und sollte nur über HTTPS verwendet werden. Keine Authentifizierung sollte nur mit äußerster Vorsicht verwendet werden, da keine Authentifizierung erfolgt. Weitere Einzelheiten finden Sie im Abschnitt „Authentifizierungsanforderungen“.

SETUP UND KONFIGURATION

Voraussetzungen

•  In diesem Dokument wird davon ausgegangen, dass auf dem Algo-Endpunkt die Firmware-Version 3.3 oder höher ausgeführt wird.
•  Der Zeitunterschied zwischen dem Anforderer und den Algo-Geräten sollte weniger als 30 Sekunden betragen, um die Standardauthentifizierung zu verwenden.
• Stellen Sie sicher, dass NTP (Network Time Protocol) verwendet wird. Die Adressen benutzerdefinierter NTP-Server können auf der Registerkarte Erweiterte Einstellungen → Zeit konfiguriert werden.

Notiz
Die vorkonfigurierten NTP-Server werden öffentlich gehostet, daher ist eine Internetverbindung erforderlich, um sie zu erreichen. Wenn keine Internetverbindung verfügbar ist, konfigurieren Sie einen lokalen NTP-Server und geben Sie dessen IP-Adresse ein.

• Stellen Sie sicher, dass die Systemzeit des Algo-Geräts auf die richtige Zeitzone eingestellt ist. Dies kann durch Navigieren zur Registerkarte „Erweiterte Einstellungen“ → „Zeit“ erfolgen.

 Aktivieren der RESTful-API

1. Melden Sie sich beim web Benutzeroberfläche und navigieren Sie zur Registerkarte „Erweiterte Einstellungen“ → „Admin“.
2. Scrollen Sie nach unten zum Abschnitt „API-Unterstützung“, aktivieren Sie die RESTful-API und legen Sie das Passwort wie gewünscht fest (Standardpasswort: algo).
   Notiz
   Die Standardauthentifizierung ist standardmäßig aktiviert.

Standardauthentifizierung aktivieren (optional)

1. Im web Navigieren Sie zur Registerkarte System → Wartung und laden Sie die Konfiguration herunter file.
2. Öffnen Sie die Konfiguration file mit einem beliebigen Texteditor und fügen Sie die folgende Zeile hinzu: api.auth.basic = 1
3.  Speichern Sie die geänderte Konfiguration und laden Sie sie hoch file mit der Funktion „Konfiguration wiederherstellen“ auf das Gerät zurücksetzen File Funktion auf der Registerkarte System → Wartung.

Keine Authentifizierungsmethode (optional)

Um die Methode ohne Authentifizierung zu aktivieren, lassen Sie das Feld „RESTful API-Passwort“ leer. Diese Methode wird nicht empfohlen und sollte nur zu Testzwecken verwendet werden, da sie keine Sicherheit bietet.

Aktivieren der einfachen Steuerschnittstelle (optional)

1. Auf der web Navigieren Sie zur Registerkarte System → Wartung und laden Sie die Konfiguration herunter file.
2.  Öffnen Sie die Konfiguration file Verwenden Sie einen Texteditor und fügen Sie zwei Zeilen hinzu. Ändere das zu Ihrem Wunschpasswort. Administrator.web.sci = 1
   Sci.admin.pwd =
3.  Speichern Sie die geänderte Konfiguration und laden Sie sie hoch file mit der Funktion „Konfiguration wiederherstellen“ auf das Gerät zurücksetzen File Funktion auf der Registerkarte System → Wartung.

Authentifizierungsanforderungen

Bitte senden Sie eine E-Mail support@algosolutions.com wenn Sie eine Standard- oder Basisauthentifizierung wünschenampder Code.

Standardauthentifizierungsanforderung mit einer JSON-Nutzlast

Erforderliche Header in der HTTP/HTTPS-Anfrage
> Inhaltstyp: „application/json“
> Content-MD5: [content_md5] Bspample
Content-MD5: 74362cc86588b2b3c5a4491baf80375b

Autorisierung: hmac admin:[nonce]:[hmac_output]
Die Autorisierungsheader bestehen aus:

1. Die Zeichenfolge „hmac admin“, gefolgt von einem Doppelpunkt „:“.
2. Nonce – Ein zufälliger oder sich nicht wiederholender Wert, gefolgt von einem Doppelpunkt „:“.
3. Hmac_output – generiert durch das auf Ihrem Gerät konfigurierte RESTful-API-Passwort (geheimer Schlüssel) und die HMAC-Eingabe, wie unten dargestellt:
   [request_method]:[request_uri]:[content_md5]:[content_type]:[timestamp]:[nonce]

HMAC-Eingang example: (verwendet „algo“ als geheimen Schlüssel)
POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936 HMAC mit Passwort und HMAC-Eingabezeichenfolge als Digest mit SHA-256 generieren:
HMAC-Ausgabe example: 2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330

Datum: Tag, Datum, Monat, Jahr Std.:Min.:Sek. GMT
Example
Datum: Do, 22. September 2022 02:33:07 GMT
Standardauthentifizierung mit Nutzdaten, z. Bampauf:

 Standardauthentifizierungsanforderung ohne JSON-Nutzlast

Identisch mit 3.1, wobei inhaltsbezogene Header/hmac-Eingaben weggelassen wurden.
HMAC-Eingabe: [request_method]:[request_uri]:[timestamp]:[nonce] HMAC-Eingabebeispielample: (verwendet „algo“ als geheimen Schlüssel)
GET:/api/settings/audio.page.vol:1601312252:49936
Generieren Sie HMAC mit Passwort und HMAC-Eingabezeichenfolge mithilfe von SHA-256:
HMAC-Ausgabe example: c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8
Standardauthentifizierung ohne Payload, zampauf:

 Grundlegende Authentifizierungsanforderung

Diese Authentifizierungsmethode sollte mit Vorsicht verwendet werden, da sie weniger sicher ist als die Standardmethode.

Autorisierung: Basic [base64]
Exampauf:
Autorisierung: Basic YWRtaW46YWxnbwo=
Standardauthentifizierung z. Bampauf:

BEFEHLE

 RESTful API-Befehle

Nachfolgend finden Sie eine Liste aller unterstützten API-Befehle.

Notiz
Eine PUT-Anfrage ändert oder erstellt eine permanente Ressource, die einen Neustart übersteht, während eine POST-Anfrage nur das Gerät für die aktuelle Sitzung steuert.

Beschreibung	Verfahren	URI	Nutzlast Parameter	Zurückkehren Example	Produkt	FW
Rufen Sie den Wert eines bestimmten Parameters ab.	ERHALTEN	/api/settings/[Schlüsselname] Bsp./api/settings/audio.page.vol	N / A	{„audio.page.vol“: „-18dB“}	Alle	> 3.3
Geben Sie den in Dezibel gemessenen Umgebungsgeräuschpegel zurück. Die Umgebungsgeräuschkompensation muss in den Grundeinstellungen -> Registerkarte „Funktionen“ aktiviert sein.	ERHALTEN	/api/info/audio.noise.level	N / A	{„audio.noise.level“: 72}	Lautsprecher zeigen Lautsprecher an	> 3.3
Extrahieren Sie den Status des Relaiseingangsanschlusses.	ERHALTEN	/api/info/input.relay.status	N / A	{“input.relay.status“: „idle“} oder {“input.relay.status“: „active“}	Alle Produkte mit Relaiseingang, außer 8063. Siehe unten.	> 4.1
Extrahieren Sie den Status der Eingangsklemmen 1 oder 2.	ERHALTEN	/api/info/input.relay1.status oder /api/info/input.relay2.status	N / A	{“input.relay1.status“: „idle“} oder {“input.relay1.status“: „active“}	8063	> 4.1
Rufen Sie die Tonliste ab files ist derzeit installiert.	ERHALTEN	/api/info/tonelist	N / A	{„tonelist“:[„bell-na.wav“, „bell uk.wav“, „buzzer.wav“,…]}	Alle	> 5.0
Rufen Sie die Geräteinformationen ab, die auf der Statusseite angezeigt werden.	ERHALTEN	/api/info/status	N / A	Vollständige Liste der Informationen auf der Registerkarte „Status“.	Alle	> 5.4

Rufen Sie die Produktinformationen ab, die auf der Seite „Info“ angezeigt werden.	ERHALTEN	/api/info/about	N / A	Alle Informationen finden Sie auf der Registerkarte „Info“.	Alle	> 5.4
Aktivieren Sie den Blitz mit den gewünschten Farb- und Musterparametern.	POST	/api/controls/strobe/start	Muster: {0 – 15} Farbe1: {Blau, Rot, Bernstein, Grün} Farbe2: {Blau, Rot, Bernstein, Grün} Ledlvl: {1 – 255} Überbleibsel: {wahr, falsch}	N / A	8128(G2) 8138 8190S	> 3.3
Stoppen Sie den Blitz.	POST	/api/controls/strobe/stop	N / A	N / A	8128(G2) 8138 8190S	> 3.3
Spielen Sie einen Ton einmal ab oder wiederholen Sie ihn.	POST	/api/controls/tone/start	Pfad: {tone} dh. chime.wav Schleife: {true, false} oder {0, 1} z.B. {„path“:“chime.wav“, „loop“:true}	N / A	Lautsprecher 8301 8373 8028(G2) 8201 8039	> 3.3
Stoppen Sie den Ton.	POST	/api/controls/tone/stop	N / A	N / A	Lautsprecher 8301 8373 8028(G2) 8201 8039	> 3.3
Rufen Sie eine Telefonnebenstelle mit einer zuvor aufgezeichneten Nachricht an.	POST	/api/controls/call/start	{„Erweiterung“: „2099“, „tone“:“gong.wav“, „interval“:“0″, „maxdur“:“10″}	N / A	Lautsprecher 8301 8410 8420	> 3.3
Beenden Sie den Anruf.	POST	/api/controls/call/stop	N / A	N / A	Lautsprecher 8301 8410 8420	> 3.3

Leiten Sie einen unidirektionalen Seitenaufruf ein. Das Gerät empfängt den Audiostream von der Zielerweiterung.	POST	/api/controls/call/page	{"Verlängerung":" ”}	N / A	Lautsprecher 8410 8420	> 5.3.4
Starten Sie den Zielendpunkt neu.	POST	/api/controls/reboot	N / A	N / A	Alle	> 3.3
Öffne die Tür. „local“ steuert das lokale Relais „netdc1“ steuert den Remote-Netzwerk-Türcontroller (8063)	POST	/api/controls/door/unlock	Tür-ID: {local, netdc1} *Optional	N / A	8039 8028(G2) 8201 8063	> 3.3
Schließen Sie die Tür.	POST	/api/controls/door/lock	Tür-ID: {local, netdc1} *Optional	N / A	8039 8028(G2) 8201 8063	> 3.3
Aktivieren Sie das 24-V-Aux-Out-Relais.	POST	api/controls/24v/enable	N / A	N / A	8063	> 5.0
Deaktivieren Sie das 24-V-Aux-Out-Relais.	POST	api/controls/24v/disable	N / A	N / A	8063	> 5.0
Aktivieren Sie das Ausgangsrelais.	POST	/api/controls/relay/enable	N / A	N / A	8063	> 5.0
Deaktivieren Sie das Ausgangsrelais.	POST	/api/controls/relay/disable	N / A	N / A	8063	> 5.0
Überprüfen Sie den Firmware-Server von Algo auf die neueste Firmware-Version.	POST	/api/controls/upgrade/check	N / A	{„Version“: „aktualisiert“} oder {"Ausführung": " ”}	Alle	> 4.1
Überprüfen Sie den Firmware-Server von Algo auf die neueste Firmware-Version und aktualisieren Sie auf diese Version.	POST	/api/controls/upgrade/start	N / A	{„Status“: „aktualisiert“} oder {„status“: „wird aktualisiert “, „url”: url>} oder {„Status“: „ ”}	Alle	> 4.1
Zeigen Sie ein Bild oder Muster auf dem Bildschirm an.	POST	/api/controls/screen/start	Sehen unten	N / A	8410 8420	> 5.3.4
Stoppen Sie das Bildschirmmuster und kehren Sie zum Standardbildschirm zurück.	POST	/api/controls/screen/stop	N / A	N / A	8410 8420	> 5.3.4

Starten Sie die Hauptanwendung neu.	POST	/api/controls/reload	N / A	N / A	Alle	> 5.3.4
Hören Sie sich einen direkten Audiostream an. Konfigurieren Sie die Portnummer, an die der Stream gesendet wird.	POST	/api/controls/rx/start	{"Hafen": }	N / A	Alle	> 5.3.4
Hören Sie auf, einen direkten Audiostream anzuhören.	POST	/api/controls/rx/stop	N / A	N / A	Alle	> 5.3.4
Stellen Sie den Multicast-Modus ein.	SETZEN	/api/state/mcast/update/	{„mode“: „sender“, „address“: , "Hafen": , „type“:“rtp“} oder {“mode“:“sender“, „address“: , "Hafen": , „type“:“poly“, „group“:1} **Hinweis**: Wenn vor diesem Befehl „controls/tone/start“ verwendet wird, wird der Ton mit den aktuellen Einstellungen auf dem abgespielt web UI	N / A	8301	> 5.0
Fügen Sie einen Wert für einen bestimmten Parameter aus der JSON-Nutzlast ein.	SETZEN	/api/settings	Parameterwert} zB {“audio.page.vol“: „-3dB“}	N / A	8180(G2) 8186 8190 8190S 8301 8373	> 3.3

 SCI-Befehle (Simple Control Interface).

Alle SCI-Befehle sind GET-Anfragen und verfügen zur Authentifizierung über die gemeinsamen Parameter „usi“ und „admin“.
Exampauf:
Holen Sie sich http:// /sci/controls/door/unlock?usr=admin&pwd=algo&doorid=local

Beschreibung	URI	Zusätzlich Nutzlast Parameter	Produkte	FW
Entriegeln Sie die Tür. „local“ steuert das lokale Relais „netdc1“ steuert den Remote-Netzwerk-Türcontroller (8063)	/sci/controls/do oder/unlock	Tür-ID: {local, netdc1} *Optional	8039 8028(G2) 8201 8063	> 3.3
Schließen Sie die Tür.	/sci/controls/do oder/lock	Tür-ID: {local, netdc1} *Optional	8039 8028(G2) 8201 8063	> 3.3
Spielen Sie einen Ton einmal ab oder wiederholen Sie ihn.	/sci/controls/to ne/start	Pfad: {tone} dh. chime.wav Schleife: {true, false} oder {0, 1}	Alle	> 3.3
Stoppen Sie den Ton.	/sci/controls/to ne/stop	N / A	Alle	> 3.3
Aktivieren Sie den Blitz mit den gewünschten Farb- und Musterparametern.	/sci/controls/strobe/start	Muster: {0 – 15} Farbe1: {Blau, Rot, Bernstein, Grün} Farbe2: {blau, rot, bernsteinfarben, grün} ledlvl: {1 – 255} Holdover: {true, false}	8128(G2) 8138 8190S	> 3.3
Stoppen Sie den Blitz.	/sci/controls/strobe/stop	N / A	8128(G2) 8138 8190S	> 3.3

Dokumente / Ressourcen

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

Verweise

• Bedienungsanleitung