Inhaltsverzeichnis  MOBOTIX Online-Hilfe

Die Fernkonfigurations-API

Inhaltsverzeichnis
Die Fernkonfigurations-API
Verwenden der Fernkonfigurations-API
Erklärung des HTTP-POST-Requests im Beispiel
Befehle der Fernkonfigurations-API
Verfügbare Befehle
Ausgaben der Fernkonfigurations-API
Beispiel: Aktivieren des Mikrofons
Beispiel: Abrufen der implementierten Befehle mit dem Befehl help
Beispiel: Ändern einer Profilzeile mit dem Befehl write

Die Fernkonfigurations-API (Application Programming Interface) http://192.168.2.54/admin/remoteconfig ermöglicht die Fernkonfiguration der Kamera, indem bestimmte Parameter der Konfigurationsdatei direkt auf der Kamera manipuliert werden.

Verwenden der Fernkonfigurations-API

Die HTTP-Schnittstelle der Kamera erwartet Befehle und Konfigurationsparameter in einem HTTP-POST-Request wie in diesem Beispiel:

POST /admin/remoteconfig HTTP/1.0
Content-type: application/x-www-form-urlencoded
Authorization: Basic YWRtaW46bWVpbnNt
Content-length: 87
helo
view section audio
write params
audio/MICRO=1
view section audio
update
store
quit
 

Erklärung des HTTP-POST-Requests im Beispiel

Bestandteil

Beschreibung

POST /admin/remoteconfig HTTP/1.0
Content-type: application/x-www-form-urlencoded
Authorization: Basic YWRtaW46bWVpbnNt
Content-length: 87

Header (Kopf) des HTTP-POST-Requests.

 

Leerzeile, trennt den Header vom Inhalt des Requests.

helo

Beginn der Befehlssequenz.

view section audio
write params
audio/MICRO=1
view section audio
update
store

Befehlssequenz mit verschiedenen Befehlen, wie im Abschnitt Befehle der Fernkonfigurations-API erläutert.

quit
 

Ende der Befehlssequenz.

Anmerk­ungen

  • Die Befehlssequenz muss mit einem Leerzeichen und einem Zeilenumbruch am Ende abgeschlossen werden.

  • Der Inhaltstyp (Content-type: application/x-www-form-urlencoded) muss nicht angegeben werden, wird aber vom Webserver der Kamera erwartet.

  • Die Autorisierung erfolgt durch den Webserver der Kamera, hier über die Variante Basic. Dabei werden Benutzername und Passwort durch einen Doppelpunkt (":") getrennt zusammengesetzt und dann Base64-kodiert. Für "admin:meinsm" ergibt sich die oben angegebene Zeile.

  • Die Länge des Inhalts (Content-length) wird über alle Daten nach der Header-Leerzeile berechnet.

  • Der Inhalt des Requests wird zeilenweise ausgewertet.

  • Sonderzeichen in Parametern müssen URL-kodiert werden, wie im Abschnitt Schreibweise für Befehlsaufrufe der Hilfeseite Die HTTP-API gezeigt.

Im Abschnitt Ausgaben der Fernkonfigurations-API wird dieses Beispiel genau erläutert und mithilfe von cURL durchgeführt.

Befehle der Fernkonfigurations-API

Die Befehle können mit den folgenden Syntaxformen verwendet werden:

Verfügbare Befehle

Befehl

Beschreibung

reset

Setzt die komplette Kamerakonfiguration oder einzelne Abschnitte darin auf Werkseinstellungen zurück.

Schlüsselwort

Auswirkung

configfile

Setzt die gesamte Konfiguration zurück.

section

Setzt nur die als Parameter angegebenen Abschnitte der Konfiguration zurück.

exceptsection

Setzt alle Abschnitte der Konfiguration außer den als Parameter angegebenen Abschnitten zurück.

restore

Stellt die im Flash gespeicherte Konfiguration wieder her.

Schlüsselwort

Auswirkung

configfile

Stellt die gesamte Konfiguration wieder her.

section

Stellt nur die als Parameter angegebenen Abschnitte der Konfiguration wieder her.

delete

Löscht die komplette Konfiguration, einzelne Abschnitte oder einzelne Parameter.

Schlüsselwort

Auswirkung

configfile

Löscht die gesamte Konfiguration.

section

Löscht nur die als Parameter angegebenen Abschnitte der Konfiguration.

params

Löscht nur die in den folgenden Zeilen angegebenen Parameter aus der Konfiguration. Die zu löschenden Parameter müssen mit vorangestelltem Abschnittnamen gefolgt von "/" als Trennzeichen angegeben werden:

<Abschnittname>/<Parameter>

Bei Profilen wird der Abschnittname um den ebenfalls mit "/" abgetrennten Profilnamen erweitert:

<Abschnittname>/<Profilname>/<Parameter>

Das Ansprechen eines Profils wie z. B.

SECTION ipnotify
profile=ip0:<Wert> 
ENDSECTION ipnotify

erfolgt entsprechend mit

ipnotify/ip0/profile

write

Schreibt ganze Abschnitte oder - mit vorangestelltem Schlüsselwort params - einzelne Parameter der Konfiguration.

Schlüsselwort

Auswirkung

(nicht angegeben)

Schreibt die in den folgenden Zeilen angegebenen Abschnitte in die Konfiguration. Die Abschnitte müssen komplett mit Start- und Endzeilen gesendet werden:

SECTION <Abschnittname1>
<Parameter>=<Wert> 
<Parameter>=<Wert> 
ENDSECTION <Abschnittname1>
SECTION <Abschnittname2>
<Parameter>=<Wert> 
ENDSECTION <Abschnittname2>

params

Schreibt die in den folgenden Zeilen angegebenen Parameter in die Konfiguration. Die Parameter müssen mit vorangestelltem Abschnittnamen gefolgt von "/" als Trennzeichen angegeben werden:

<Abschnittname>/<Parameter>=<Wert> 

Bei Profilen wird der Abschnittname um den ebenfalls mit "/" abgetrennten Profilnamen erweitert:

<Abschnittname>/<Profilname>/<Parameter>=<Wert> 

Das Ansprechen eines Profils wie z. B.

SECTION ipnotify
profile=ip0:<Wert> 
ENDSECTION ipnotify

erfolgt entsprechend mit

ipnotify/ip0/profile

Hinweis

Profile können nur als Ganzes geschrieben werden. Der Zugriff auf einzelne Parameter innerhalb eines Profils ist nicht möglich.

append

Hängt Daten an Konfigurationsabschnitte an. Die anzuhängenden Parameter für einen Abschnitt werden zeilenweise zwischen SECTION und ENDSECTION angegeben:

SECTION <Abschnittname>
Parameter=<Wert>
Parameter=<Wert>
ENDSECTION <Abschnittname>

view

Gibt die komplette Konfiguration oder ausgewählte Abschnitte aus.

Schlüsselwort

Auswirkung

configfile

Gibt die komplette Konfiguration aus.

section

Gibt nur die als Parameter angegebenen Abschnitte der Konfiguration aus.

store

Sichert die Konfiguration der Kamera permanent (im Flash-Speicher).

reboot

Löst einen Neustart der Kamera aus.

update

Aktiviert die an der Konfiguration vorgenommenen Änderungen, soweit dies ohne Neustart möglich ist.

Schlüsselwort

Auswirkung

all (oder ohne Schlüsselwort)

Es werden alle Änderungen aktiviert.

section

Nur Änderungen an den als Parameter angegebenen Abschnitten werden aktiviert.

profile

Gibt eine Zeile mit dem Namen des gerade aktiven Konfigurationsprofils aus. Die Zeile ist leer, wenn kein Profil aktiv ist.

activate_profile

Aktiviert das als Parameter angegebene Konfigurationsprofil: activate_profile <Profilname>

reboot_needed

Listet die Konfigurationssektionen auf, die verändert wurden und einen Neustart zur Aktivierung der Änderungen benötigen. Die Zeile ist leer, wenn keine Änderung einen Neustart erfordert.

Hinweis

Nach Änderungen an der gesamten Konfiguration (mit write, reset, delete oder nach dem Hochladen oder dem Editieren der Konfiguration über das Web-Interface) ist keine Information über die Änderung einzelner Abschnitte verfügbar. In diesem Fall liefert dieser Befehl die Antwort "unknown".

exit quit

Identische Bedeutung. Beide Befehle schließen den vorangehenden Befehl ab und beenden den API-Aufruf. In einer Befehlssequenz kann immer nur einer dieser beiden Befehle verwendet werden.

help

Gibt eine Liste der verfügbaren Befehle zurück (siehe Abrufen der implementierten Befehle mit dem Befehl help).

Ausgaben der Fernkonfigurations-API

Die Ausgabe der API erfolgt zeilenweise:

Beispiel: Aktivieren des Mikrofons

Dieses Beispiel zeigt, wie das Mikrofon der Kamera mit einem HTTP-Request aktiviert werden kann. Zum Testen kann das Befehlszeilenwerkzeug cURL (http://curl.haxx.se/download.html) verwendet werden, das für Windows erhältlich ist und unter Mac OS X und Linux bereits installiert ist.

Vorteil von cURL ist, dass die Befehle schnell getestet werden können, da diese Anwendung die Kommunikation mit der Kamera übernimmt. So sendet cURL automatisch den richtigen Header und berechnet die Länge der eingegebenen Befehlssequenz.

Befehle

Beschreibung

helo
view section audio
write params
audio/MICRO=1
view section audio
update
store
quit
 
# Beginn der Befehlssequenz.
# Abschnitt audio ausgeben.
# Schreiben des in der folgenden Zeile angegebenen Parameters.
# Parameter MICRO im Abschnitt audio auf den Wert "1" setzen.
# Abschnitt audio erneut ausgeben.
# Änderungen ohne Neustart aktivieren.
# Konfiguration im Flash-Speicher der Kamera sichern.
# Ende der Befehlssequenz.
 
Schrittweise Anleitung:
  • Öffnen Sie eine Eingabeaufforderung (Windows) bzw. ein Terminal (Mac OS X, Linux).

  • Geben Sie folgende Befehlszeile ein, wobei Sie <Benutzername>, <Passwort> und <IP-Adresse> durch die tatsächliche Daten für Ihre Kamera ersetzen:

    curl -q -v -u "<Benutzername>:<Passwort>" --data-binary @- "http://<IP-Adresse>/admin/remoteconfig"
  • Drücken Sie die [Eingabetaste]; cURL wartet jetzt auf Befehle.

  • Kopieren Sie den Textblock in der linken Spalte der obigen Tabelle von helo bis quit.

  • Fügen Sie den Inhalt der Zwischenablage in der Eingabeaufforderung/im Terminal ein.

  • Drücken Sie zwei Mal hintereinander die Tastenkombination [Strg+D] (Windows, Linux) bzw. einmal [Ctrl+D] (Mac OS X), um die Befehlssequenz an die Kamera zu senden.

Ausgabe der obigen Befehlssequenz mit folgenden Daten:
  • <Benutzername>: admin

  • <Passwort>: meinsm

  • <IP-Adresse>: 10.8.0.118

* About to connect() to 10.8.0.118 port 80 (#0)
* Trying 10.8.0.118... connected
* Connected to 10.8.0.118 port 80 (#0)
* Server auth using Basic with user 'admin'
> POST /admin/remoteconfig HTTP/1.1
> Authorization: Basic YWRtaW46bWVpbnNt
> User-Agent: curl/7.18.2 (i486-pc-linux-gnu) libcurl/7.18.2 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.8 libssh2/0.18
> Host: 10.8.0.118
> Accept: */*
> Content-Length: 87
> Content-Type: application/x-www-form-urlencoded
>
* HTTP 1.0, assume close after body
< HTTP/1.0 200 OK
< Content-Type: text/plain; charset=utf-8
< Cache-Control: no-cache
<
#read:helo:
#read:view section audio:
#exec cmd=view section audio
SECTION audio
SPEAKER=1
MICRO=0
PREAMPLIFIER=2
SPEAKERLEVEL=0
ENDSECTION audio
#read:write params:
#exec cmd=write params
#read:view section audio:
#exec cmd=view section audio
SECTION audio
SPEAKER=1
MICRO=1
PREAMPLIFIER=2
SPEAKERLEVEL=0
ENDSECTION audio
#read:update:
#exec cmd=update
#updating daemons!
#read:store:
#exec cmd=store
#Storing to flash...
#read:quit:
OK
#bye
* Closing connection #0

Hinweis

Die Ausgaben, die mit "*", "<" und ">" beginnen, werden von cURL ausgegeben. Hierbei kennzeichnet ">" Befehle, die zur Kamera gesendet werden und "<" Meldungen, die vom Webserver der Kamera zurückgegeben werden. Die restlichen Zeilen werden von der Fernkonfigurations-API zurückgegeben, wie unter Ausgaben der Fernkonfigurations-API beschrieben.

Beispiel: Abrufen der implementierten Befehle mit dem Befehl help

Befehle

Beschreibung

helo
help
quit
 
# Beginn der Befehlssequenz.
# Hilfe der Fernkonfigurations-API aufrufen.
# Ende der Befehlssequenz.
 
Schrittweise Anleitung:
  • Öffnen Sie eine Eingabeaufforderung (Windows) bzw. ein Terminal (Mac OS X, Linux).

  • Geben Sie folgende Befehlszeile ein, wobei Sie <Benutzername>, <Passwort> und <IP-Adresse> durch die tatsächliche Daten für Ihre Kamera ersetzen:

    curl -q -v -u "<Benutzername>:<Passwort>" --data-binary @- "http://<IP-Adresse>/admin/remoteconfig"
  • Drücken Sie die [Eingabetaste]; cURL wartet jetzt auf Befehle.

  • Kopieren Sie den Textblock in der linken Spalte der obigen Tabelle von helo bis quit.

  • Fügen Sie den Inhalt der Zwischenablage in der Eingabeaufforderung/im Terminal ein.

  • Drücken Sie zwei Mal hintereinander die Tastenkombination [Strg+D] (Windows, Linux) bzw. [Ctrl+D] (Mac OS X), um die Befehlssequenz an die Kamera zu senden.

Ausgabe der obigen Befehlssequenz mit folgenden Daten:
  • <Benutzername>: admin

  • <Passwort>: meinsm

  • <IP-Adresse>: 10.8.0.118

* About to connect() to 10.8.0.118 port 80 (#0)
* Trying 10.8.0.118... connected
* Connected to 10.8.0.118 port 80 (#0)
* Server auth using Basic with user 'admin'
> POST /admin/remoteconfig HTTP/1.1
> Authorization: Basic YWRtaW46bWVpbnNt
> User-Agent: curl/7.18.2 (i486-pc-linux-gnu) libcurl/7.18.2 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.8 libssh2/0.18
> Host: 10.8.0.118
> Accept: */*
> Content-Length: 87
> Content-Type: application/x-www-form-urlencoded
>
* HTTP 1.0, assume close after body
< HTTP/1.0 200 OK
< Content-Type: text/plain; charset=utf-8
< Cache-Control: no-cache
<
#read:helo:
#read:help:
The following commands are currently implemented:
append
reboot_needed
view
reboot
write
profile
restore
activate_profile
reset
update
delete
store
exit
quit
help
#read:quit:
OK
#bye
* Closing connection #0

Hinweis

Die Ausgaben, die mit "*", "<" und ">" beginnen, werden von cURL ausgegeben. Hierbei kennzeichnet ">" Befehle, die zur Kamera gesendet werden und "<" Meldungen, die vom Webserver der Kamera zurückgegeben werden. Die restlichen Zeilen werden von der Fernkonfigurations-API zurückgegeben, wie unter Ausgaben der Fernkonfigurations-API beschrieben.

Beispiel: Ändern einer Profilzeile mit dem Befehl write

Die Zieladresse ipnotifyaddress des Netzwerknachrichten-Profils ip0 im Konfigurationsabschnitt ipnotify soll von 10.0.0.42:8000 auf 10.11.12.13:6750 umgestellt werden.

Hinweis

Sie müssen immer die komplette Profilzeile schreiben. Einzelne Werte innerhalb eines Profils können nicht separat geändert werden.

Befehle

Beschreibung

helo
view section ipnotify
write params
ipnotify/ip0/profile=ip0:_profilename=MxCC-Alarm
:preset=mxpeg_alarm:ackn_time=60
:ipnotifyaddress=10.11.12.13%3A6750
:send=on_error:protocol=raw
:boundary=--next-image--:httppath=:httpauth=
:data=msg:ipnotifymessage=Hello World!
:filetype=mxg:rate100=100:antetime=1
:posttime=1:systime=1440:ipnotifyport=0
view section ipnotify
update
store
quit
 
# Beginn der Befehlssequenz.
# Abschnitt ipnotify ausgeben.
# Schreiben des in der folgenden Zeile angegebenen Profils.
# Profil ip0 im Abschnitt ipnotify mit der Adresse
# "10.11.12.13" und Port "6750" setzen...
# ...
# ...
# ...
# ...
# ...
# ...
# Abschnitt ipnotify erneut ausgeben.
# Änderungen ohne Neustart aktivieren.
# Konfiguration im Flash-Speicher der Kamera sichern.
# Ende der Befehlssequenz.
 
Schrittweise Anleitung:
  • Öffnen Sie eine Eingabeaufforderung (Windows) bzw. ein Terminal (Mac OS X, Linux).

  • Geben Sie folgende Befehlszeile ein, wobei Sie <Benutzername>, <Passwort> und <IP-Adresse> durch die tatsächliche Daten für Ihre Kamera ersetzen:

    curl -q -v -u "<Benutzername>:<Passwort>" --data-binary @- "http://<IP-Adresse>/admin/remoteconfig"
  • Drücken Sie die [Eingabetaste]; cURL wartet jetzt auf Befehle.

  • Kopieren Sie den Textblock in der linken Spalte der obigen Tabelle von helo bis quit.

  • Fügen Sie den Inhalt der Zwischenablage in der Eingabeaufforderung/im Terminal ein.

  • Drücken Sie zwei Mal hintereinander die Tastenkombination [Strg+D] (Windows, Linux) bzw. [Ctrl+D] (Mac OS X), um die Befehlssequenz an die Kamera zu senden.

Ausgabe der obigen Befehlssequenz mit folgenden Daten:
  • <Benutzername>: admin

  • <Passwort>: meinsm

  • <IP-Adresse>: 10.8.0.118

* About to connect() to 10.8.0.118 port 80 (#0)
* Trying 10.8.0.118... connected
* Connected to 10.8.0.118 port 80 (#0)
* Server auth using Basic with user 'admin'
> POST /admin/remoteconfig HTTP/1.1
> Authorization: Basic YWRtaW46bWVpbnNt
> User-Agent: curl/7.18.2 (i486-pc-linux-gnu) libcurl/7.18.2 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.8 libssh2/0.18
> Host: 10.8.0.118
> Accept: */*
> Content-Length: 87
> Content-Type: application/x-www-form-urlencoded
>
* HTTP 1.0, assume close after body
< HTTP/1.0 200 OK
< Content-Type: text/plain; charset=utf-8
< Cache-Control: no-cache
<
#read:helo:
#read:view section ipnotify:
#exec cmd=view section ipnotify
SECTION ipnotify
ipnotify/ip0/profile=ip0:_profilename=MxCC-Alarm
:preset=mxpeg_alarm:ackn_time=60
:ipnotifyaddress=10.0.0.42%3A8000
:send=on_error:protocol=raw
:boundary=--next-image--:httppath=:httpauth=
:data=msg:ipnotifymessage=Hello World!
:filetype=mxg:rate100=100:antetime=1
:posttime=1:systime=1440:ipnotifyport=0
...
ENDSECTION ipnotify
#read:write params:
#exec cmd=write params
#read:view section ipnotify:
#exec cmd=view section ipnotify
SECTION ipnotify
ipnotify/ip0/profile=ip0:_profilename=MxCC-Alarm
:preset=mxpeg_alarm:ackn_time=60
:ipnotifyaddress= 10.11.12.13%3A6750
:send=on_error:protocol=raw
:boundary=--next-image--:httppath=:httpauth=
:data=msg:ipnotifymessage=Hello World!
:filetype=mxg:rate100=100:antetime=1
:posttime=1:systime=1440:ipnotifyport=0
...
ENDSECTION ipnotify
#read:update:
#exec cmd=update
#updating daemons!
#read:store:
#exec cmd=store
#Storing to flash...
#read:quit:
OK
#bye
* Closing connection 0

Hinweis

Die Ausgaben, die mit "*", "<" und ">" beginnen, werden von cURL ausgegeben. Hierbei kennzeichnet ">" Befehle, die zur Kamera gesendet werden und "<" Meldungen, die vom Webserver der Kamera zurückgegeben werden. Die restlichen Zeilen werden von der Fernkonfigurations-API zurückgegeben, wie unter Ausgaben der Fernkonfigurations-API beschrieben.


© 2001-2018 MOBOTIX · http://www.mobotix.com/