CheckForUpdates

La API /osc/checkForUpdates identifica actualizaciones de estado al comparar la última stateFingerprint conocida del cliente con la fingerprint actual de la cámara.

Entrada

Nombre Tipo Descripción
stateFingerprint Cadena Huella digital del estado de la cámara desde la última vez que el cliente llamó a /osc/state o /osc/checkForUpdates.
waitTimeout Entero (opcional) Segundos que se deben esperar hasta que ocurra un cambio de estado en la cámara antes de devolver la respuesta. Cuando waitTimeout caduca, la cámara debe devolver una respuesta, aunque no haya cambiado la huella digital. Si se detecta un cambio de estado antes de que waitTimeout caduque, o si se omite waitTimeout, la cámara debe devolver la respuesta de inmediato.Nota: la cámara puede devolver una respuesta antes de que waitTimeout caduque, aunque no haya cambiado la huella digital, pero la mejor práctica es esperar hasta que waitTimeout caduque.

Notas sobre la implementación de la cámara:

  • Después de recibir esta llamada, la cámara compara su huella digital de estado actual con el parámetrostateFingerprint recibido. Si la huella digital cambió, la cámara debe devolver de inmediato la nueva huella digital.

Salida

Nombre Tipo Descripción
stateFingerprint Cadena Nueva huella digital del estado de la cámara (la misma que en la API /osc/state).
throttleTimeout Entero Segundos recomendados de espera del cliente antes de la siguiente llamada de checkForUpdates. Los clientes pueden realizar solicitudes antes de que throttleTimeout caduque, y las cámaras deben permitir solicitudes anticipadas, si fuera posible.

Notas sobre la implementación del cliente:

  • Después de recibir una respuesta, el cliente debe comparar la stateFingerprint recibida con la copia de esta. Si no coinciden, el cliente debe solicitar el estado actual de la cámara usando la API _/osc/state.
  • Los clientes inteligentes regularán las solicitudes independientemente de la respuesta de la cámara. Por ejemplo, si una cámara devuelve una respuesta no estándar (de inmediato, con no change y un throttleTimeout) bajo o de 0, el cliente debe imponer su propio throttleTimeout antes de solicitar otro checkForUpdates desde la cámara.

Notas sobre la implementación de la cámara:

  • Al responder a checkForUpdates, la cámara debe determinar un throttleTimeout razonable. Si la cámara admite lógica de solicitud antigua (si el estado no cambió, responde solo después del waitTimeout), puedes devolver throttleTimeout con un valor de 0. En ese caso, los clientes pueden solicitar actualizaciones de inmediato.
  • Si la cámara solo admite respuestas rápidas (no se recomienda), debe devolver un throttleTimeout razonable para evitar el tráfico constante de solicitudes/respuestas con el cliente. Por ejemplo, un throttleTimeout razonable serían 60 segundos, para permitir el acceso de un cliente por minuto.
  • La mejor práctica es devolver un throttleTimeout adecuado para las capacidades de la cámara. Si el servidor no puede determinar un throttleTimeout adecuado debido a un problema del servidor, la cámara debe responder con un código de estado 5XX y un cuerpo JSON con el cóodigo de error serverError.

Error

Código de error Descripción
missingParameter stateFingerprint no se ha especificado.
invalidParameterName No se reconoce uno o más nombres de parámetros de entrada.
invalidParameterValue Se reconocen los nombres de los parámetros, pero uno o más valores no son válidos; por ejemplo, waitTimeout está fuera de rango o su tipo es incorrecto.
serverError El servidor no pudo determinar un valor de throttleTimeout adecuado para su respuesta. El problema del servidor se identificará con el valor 5XX devuelto en la respuesta. Los fabricantes de la cámara deben proporcionar una tabla de códigos 5XX y los estados de servidor correspondientes que pueden iniciar este error.

Ejemplo
Solicitud 
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
}
Respuesta 
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
}
Solicitud 
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
}
Respuesta 
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."
    }
}