CheckForUpdates

Die /osc/checkForUpdates API ermittelt Statusaktualisierungen, indem die letzte bekannte stateFingerprint des Clients mit dem aktuellen fingerprint der Kamera verglichen wird.

Eingabe

Name Typ Beschreibung
stateFingerprint String Fingerabdruck des Kamerastatus vom letzten Aufruf des Clients „/osc/state“ oder „/osc/checkForUpdates“ durch den Client.
waitTimeout Ganzzahl (optional) Anzahl der Sekunden, die auf eine Statusänderung an der Kamera gewartet werden soll, bevor die Antwort zurückgegeben wird. Nach Ablauf des waitTimeout sollte die Kamera eine Antwort zurückgeben, auch wenn sich der Fingerabdruck nicht geändert hat. Wenn eine Statusänderung erkannt wird, bevor waitTimeout abläuft, oder wenn waitTimeout weggelassen wird, sollte die Kamera sofort die Antwort zurückgeben.Hinweis:Die Kamera kann vor Ablauf von waitTimeout eine Antwort zurückgeben, auch wenn sich der Fingerabdruck nicht geändert hat. Es empfiehlt sich jedoch, bis zum Ablauf von waitTimeout zu warten.

Hinweise zur Implementierung der Kamera:

  • Beim Empfang dieses Aufrufs vergleicht die Kamera ihren aktuellen Status-Fingerabdruck mit dem empfangenen stateFingerprint-Parameter. Wenn der Fingerabdruck sich verändert hat, muss der neue Fingerabdruck sofort von der Kamera zurückgegeben werden.

Ausgabe

Name Typ Beschreibung
stateFingerprint String Neuer Fingerabdruck des Kamerastatus (wie in der /osc/state API).
throttleTimeout Ganzzahl Empfohlene Anzahl von Sekunden, die der Client vor dem nächsten checkForUpdates-Anruf warten soll. Clients können Anfragen stellen, bevor der throttleTimeout abläuft. Kameras sollten diese frühen Anfragen nach Möglichkeit zulassen.

Hinweise zur Kundenimplementierung:

  • Nach dem Empfang einer Antwort sollte der Client den empfangenen stateFingerprint mit seiner Kopie vergleichen. Wenn sie nicht übereinstimmen, sollte der Client den aktuellen Status der Kamera über die _/osc/state API anfordern.
  • Intelligente Clients drosseln Anfragen unabhängig von der Kameraantwort. Wenn eine Kamera beispielsweise sofort eine nicht standardmäßige Antwort zurückgibt (sofort mit keine Änderung und einem niedrigen Wert oder einem Wert von 0 throttleTimeout)), sollte der Client eine eigene throttleTimeout festlegen, bevor eine weitere checkForUpdates von der Kamera angefordert wird.

Hinweise zur Implementierung der Kamera:

  • Wenn die Kamera auf „checkForUpdates“ reagiert, sollte sie einen angemessenen Wert für „throttleTimeout“ bestimmen. Wenn die Kamera langjährige Anfragelogik unterstützt (und nur nach waitTimeout antwortet, wenn sich der Status nicht geändert hat), kann throttleTimeout als 0 zurückgegeben werden. In diesem Fall können Clients Aktualisierungen sofort anfordern.
  • Wenn die Kamera nur schnelle Antworten unterstützt (nicht empfohlen), sollte ein angemessener throttleTimeout zurückgegeben werden, um einen konstanten Anfrage-/Antwort-Traffic mit dem Client zu vermeiden. Ein angemessener throttleTimeout wäre beispielsweise 60 Sekunden, um eine Clientanfrage pro Minute zuzulassen.
  • Als Best Practice wird empfohlen, eine throttleTimeout zurückzugeben, die den Kamerafunktionen entspricht. Wenn der Server aufgrund eines Serverproblems kein geeignetes throttleTimeout ermitteln kann, sollte die Kamera mit einem 5XX-Statuscode und einem JSON-Text mit dem Fehlercode serverError antworten.

Fehler

Fehlercode Beschreibung
missingParameter stateFingerprint ist nicht angegeben.
invalidParameterName Mindestens einer der Namen von Eingabeparametern wurde nicht erkannt.
invalidParameterValue Die Parameternamen werden erkannt, aber mindestens ein Wert ist ungültig. Beispiel: waitTimeout liegt außerhalb des zulässigen Bereichs oder der Typ ist falsch.
serverError Der Server konnte keinen geeigneten throttleTimeout-Wert für seine Antwort ermitteln. Das Serverproblem wird in der Antwort durch den Wert 5XX gekennzeichnet. Kamerahersteller sollten eine Tabelle mit 5XX-Codes und entsprechenden Serverstatus bereitstellen, die diesen Fehler auslösen können.

Beispiel
Anfrage 
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
}
Anfrage 
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."
    }
}