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 Tipo Descrizione
stateFingerprint Stringa Impronta dello stato della videocamera dall'ultima volta che il client ha chiamato /osc/state o /osc/checkForUpdates.
waitTimeout Numero intero (facoltativo) Numero di secondi di attesa che si verifichi un cambiamento di stato sulla fotocamera 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 fotocamera dovrebbe restituire immediatamente la risposta.Nota:la fotocamera può restituire una risposta prima della scadenza di waitTimeout anche se l'impronta non è cambiata, ma la best practice è attendere la scadenza di waitTimeout.

Note sull'implementazione della videocamera:

  • Dopo aver ricevuto questa chiamata, la videocamera confronta il proprio stato attuale con l'impronta digitale con il parametro stateFingerprint ricevuto. Se l'impronta è cambiata, la fotocamera deve restituire immediatamente la nuova impronta.

Output

Nome Tipo Descrizione
stateFingerprint Stringa Nuova impronta per lo stato della videocamera (come nell'API /osc/state).
throttleTimeout Numero intero Numero di secondi consigliato per il cliente di attendere prima della prossima chiamata checkForUpdates. I client possono effettuare le richieste prima della scadenza di throttleTimeout e le videocamere dovrebbero consentire queste richieste in anteprima, se possibile.

Note sull'implementazione del client:

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

Note sull'implementazione della videocamera:

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

Errore

Codice di errore Descrizione
missingParameter stateFingerprint non specificato.
invalidParameterName Uno o più nomi di parametri di input non sono riconosciuti.
invalidParameterValue I nomi dei parametri sono riconosciuti, ma uno o più valori non sono validi. ad esempio, waitTimeout è fuori intervallo o il suo tipo è errato.
serverError Il server non è riuscito a determinare un valore throttleTimeout appropriato per la sua risposta. Il problema del server verrà identificato dal valore 5XX restituito nella risposta. I produttori di fotocamere devono fornire una tabella con i codici 5XX e gli stati dei 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."
    }
}