L'API /osc/checkForUpdates
identifica gli aggiornamenti di stato confrontando l'ultimo stateFingerprint
noto del client con l'attuale fingerprint
della videocamera.
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."
}
} |