Die API /osc/checkForUpdates
ermittelt Zustandsaktualisierungen durch einen Vergleich des letzten bekannten Client-stateFingerprint
mit dem aktuellen fingerprint
der Kamera.
Eingabe
Name |
Typ |
Beschreibung |
stateFingerprint |
Zeichenfolge |
Fingerabdruck des Kamerazustands zum Zeitpunkt des letzten Clientaufrufs von /osc/state oder /osc/checkForUpdates . |
waitTimeout |
Ganzzahl (optional) |
Gibt an, wie viele Sekunden auf eine Änderung des Kamerazustands gewartet werden soll, bevor die Antwort zurückgegeben wird. Nach Ablauf von waitTimeout sollte die Kamera eine Antwort zurückgeben, auch wenn der Fingerabdruck unverändert ist. Wenn eine Zustandsänderung vor Ablauf von waitTimeout erkannt wird oder waitTimeout nicht angegeben ist, sollte die Kamera die Antwort sofort zurückgeben.Hinweis: Die Kamera im Falle eines unveränderten Fingerabdrucks kann auch eine Antwort vor Ablauf von waitTimeout zurückgeben, das bewährte Verfahren ist jedoch, bis zum Ablauf von waitTimeout zu warten. |
Hinweise zur Kameraimplementierung:
- Beim Eingang dieses Aufrufs wird in der Kamera der aktuelle Zustandsfingerabdruck mit dem erhaltenen Parameter
stateFingerprint
verglichen. Wenn der Fingerabdruck sich verändert hat, muss der neue Fingerabdruck sofort von der Kamera zurückgegeben werden.
Ausgabe
Name |
Typ |
Beschreibung |
stateFingerprint |
Zeichenfolge |
Der neue Fingerabdruck des Kamerazustands (identisch mit dem Wert in der API /osc/state ). |
throttleTimeout |
Ganzzahl |
Empfohlene Anzahl Sekunden, die der Client vor dem nächsten Aufruf von checkForUpdates warten soll. Clients können Anforderungen vor Ablauf von throttleTimeout stellen, und in den Kameras sollten diese Anforderungen nach Möglichkeit zulässig sein. |
Hinweise zur Clientimplementierung:
- Beim Eingang einer Antwort sollte der erhaltene Wert von
stateFingerprint
im Client mit seiner Kopie abgeglichen werden. Stimmen die Werte nicht überein, sollte vom Client mithilfe der API _/osc/state
der aktuelle Zustand der Kamera angefordert werden.
- Intelligente Clients begrenzen Anforderungen unabhängig von der Kameraantwort. Wenn von einer Kamera beispielsweise eine nicht dem Standard entsprechende Antwort zurückgegeben wird (sofort, mit dem Wert keine Änderung und mit einem niedrigen Wert oder Wert null für
throttleTimeout)
) sollte vom Client ein eigener throttleTimeout
erzwungen werden, bevor checkForUpdates
erneut von der Kamera angefordert wird.
Hinweise zur Kameraimplementierung:
- Beim Senden einer Antwort auf
checkForUpdates
sollte von der Kamera ein angemessener Wert für throttleTimeout
festgelegt werden. Wenn von der Kamera eine Logik für lange Daueranforderungen unterstützt wird (Antwort erst nach waitTimeout
, wenn der Zustand unverändert ist), ist es OK, throttleTimeout
mit dem Wert 0
zurückzugeben. In diesem Fall können Clients Aktualisierungen sofort anfordern.
- Wenn von der Kamera nur schnelle Antworten unterstützt werden (nicht empfohlen), sollte von der Kamera ein angemessener
throttleTimeout
zurückgegeben werden, um einen ununterbrochenen Anforderungs-/Antwortverkehr mit dem Client zu vermeiden. Ein angemessener Wert für throttleTimeout
wären beispielsweise 60 Sekunden, um eine Clientanforderung pro Minute zuzulassen.
- Die bewährte Methode ist die Rückgabe eines Wertes für
throttleTimeout
, der an die Kameraleistung angepasst ist. Wenn vom Server aufgrund von Serverproblemen kein angemessener Wert für throttleTimeout
ermittelt werden kann, sollte die Kameraantwort in Form eines Statuscodes 5XX und eines JSON-Textkörpers mit dem Fehlercode serverError
erfolgen.
Fehler
Fehlercode |
Beschreibung |
missingParameter |
stateFingerprint ist nicht angegeben. |
invalidParameterName |
Mindestens ein Eingabeparameter wurde nicht erkannt. |
invalidParameterValue |
Die Parameternamen wurden erkannt, aber mindestens ein Wert ist unzulässig; beispielsweise liegt waitTimeout außerhalb des zulässigen Bereichs, oder sein Typ ist nicht korrekt. |
serverError |
Vom Server konnte kein angemessener Wert throttleTimeout für seine Antwort ermittelt werden. Das Serverproblem wird in der Antwort durch den Wert 5XX gekennzeichnet. Kamerahersteller sollten eine Tabelle mit 5XX-Codes und den entsprechenden Serverzuständen, die diesen Fehler auslösen können, bereitstellen. |
Beispiel |
Anforderung |
POST /osc/checkForUpdates HTTP/1.1
Host: [camera ip address]:[httpUpdatesPort]
Content-Type: application/json;charset=utf-8
Accept: application/jsonContent-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1
{
"stateFingerprint": "12EGA33",
"waitTimeout": 300
} |
Antwort |
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff
{
"stateFingerprint": "12EGA86",
"throttleTimeout": 60
} |
Anforderung |
POST /osc/checkForUpdates HTTP/1.1
Host: [camera ip address]:[httpUpdatesPort]
Content-Type: application/json;charset=utf-8
Accept: application/jsonContent-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1
{
"stateFingerprint": "12EGA33",
"waitTimeout": 300
} |
Antwort |
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff
{
"name": "camera.checkForUpdates",
"state": "error",
"error": {
"code": "missingParameter",
"message": "parameter stateFingerprint is missing."
}
} |