CheckForUpdates

L'API /osc/checkForUpdates identifica gli aggiornamenti di stato confrontando l'ultimo stateFingerprint noto del client con l'attuale fingerprint della videocamera.

Input

Nome Digitare Descrizione
stateFingerprint Stringa Fingerprint dello stato della videocamera ottenuta dall'ultima volta che il client ha chiamato /osc/state o /osc/checkForUpdates.
waitTimeout Numero intero (facoltativo) Numero di secondi di attesa prima che si verifichi un cambiamento di stato sulla videocamera prima di restituire la risposta. Alla scadenza di waitTimeout, la fotocamera dovrebbe restituire una risposta anche se l'impronta non è cambiata. Se viene rilevato un cambiamento di stato prima della scadenza di waitTimeout o se waitTimeout viene omesso, la videocamera dovrebbe restituire immediatamente la risposta.Nota: la videocamera può restituire una risposta prima della scadenza di waitTimeout anche se la fingerprint non è cambiata, ma la best practice è attendere la scadenza di waitTimeout.

Note sull'implementazione di Fotocamera:

  • Alla ricezione di questa chiamata, la videocamera confronta la propria impronta dello stato attuale con il parametro stateFingerprint ricevuto. Se l'impronta è cambiata, la fotocamera deve restituire immediatamente la nuova impronta.

Output
stateFingerprint Stringa Nuova impronta dello stato della fotocamera (come nell'API /osc/state).
throttleTimeout Numero intero Numero consigliato di secondi che il cliente deve attendere prima della prossima chiamata checkForUpdates. I client possono effettuare richieste prima della scadenza di throttleTimeout e le videocamere dovrebbero consentire queste richieste in anticipo, se possibile.

Note sull'implementazione del client:

  • Dopo aver ricevuto una risposta, il client deve confrontare il stateFingerprint ricevuto con la sua copia. Se non corrispondono, il client deve richiedere lo stato attuale della videocamera utilizzando l'API _/osc/state.
  • I client intelligenti limiteranno le richieste indipendentemente dalla risposta della videocamera. Ad esempio, se una videocamera restituisce una risposta non standard (immediatamente, con nessuna modifica e un valore throttleTimeout) basso o pari a 0, il client deve imporre il proprio throttleTimeout prima di richiedere un altro checkForUpdates alla videocamera.

Note sull'implementazione di Fotocamera:

  • Quando rispondi a checkForUpdates, la fotocamera dovrebbe determinare un valore throttleTimeout ragionevole. Se la videocamera supporta la logica di richiesta di lunga data (rispondi solo dopo waitTimeout se lo stato non è cambiato), puoi restituire throttleTimeout come 0. In questo caso, i clienti possono richiedere immediatamente gli aggiornamenti.
  • Se la videocamera supporta solo risposte rapide (non consigliato), dovrebbe restituire un valore throttleTimeout ragionevole per evitare un traffico di richieste/risposte costante con il client. Ad esempio, un valore throttleTimeout ragionevole corrisponde a 60 secondi, per consentire una richiesta del client al minuto.
  • La best practice consiste nel restituire un throttleTimeout appropriato per le funzionalità della fotocamera. Se il server non riesce a determinare un throttleTimeout appropriato a causa di un problema del server, la videocamera deve rispondere con un codice di stato 5XX e un corpo JSON contenente il codice di errore serverError.

Errore

Codice di errore
missingParameter stateFingerprint non è specificato.
invalidParameterName Uno o più nomi di parametri di input non sono riconosciuti.
invalidParameterValue I nomi dei parametri vengono riconosciuti, ma uno o più valori non sono validi; ad esempio, waitTimeout è fuori intervallo o il suo tipo non è corretto.
serverError Il server non è riuscito a determinare un valore throttleTimeout appropriato per la risposta. Il problema del server verrà identificato dal valore 5XX restituito nella risposta. I produttori di videocamere devono fornire una tabella contenente i codici 5XX e gli stati del server corrispondenti che possono generare questo errore.

Esempio
Richiedi 
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
}
Risposta 
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
}
Richiedi 
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
}
Risposta 
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."
    }
}