CheckForUpdates

La API de /osc/checkForUpdates identifica las actualizaciones de estado comparando el último stateFingerprint conocido del cliente con el fingerprint actual de la cámara.

Entrada

Nombre Tipo Descripción
stateFingerprint Cadena Huella digital del estado de la cámara de la última vez que el cliente llamó a /osc/state o /osc/checkForUpdates.
waitTimeout Número entero (opcional) Cantidad de segundos que se debe esperar para que ocurra el cambio de estado en la cámara antes de devolver la respuesta. Cuando waitTimeout vence, la cámara debe devolver una respuesta, incluso si la huella dactilar no cambió. Si se detecta un cambio de estado antes de que venza waitTimeout, o si se omite waitTimeout, la cámara debe mostrar la respuesta de inmediato.Nota: La cámara puede mostrar una respuesta antes de que venza waitTimeout, incluso si no cambió la huella digital, pero la práctica recomendada es esperar hasta que venza waitTimeout.

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

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

Salida
stateFingerprint Cadena Nueva huella digital del estado de la cámara (igual que en la API de /osc/state).
throttleTimeout Número entero Cantidad de segundos que el cliente debe esperar antes de la próxima llamada a checkForUpdates. Los clientes pueden realizar solicitudes antes del vencimiento de throttleTimeout, y las cámaras deben permitirlas, si es posible.

Notas sobre la implementación del cliente:

  • Tras recibir una respuesta, el cliente debe comparar el stateFingerprint recibido con su copia. Si no coinciden, el cliente debe solicitar el estado actual de la cámara mediante la API de _/osc/state.
  • Los clientes inteligentes limitarán las solicitudes independientemente de la respuesta de la cámara. Por ejemplo, si una cámara muestra una respuesta no estándar (inmediatamente, sin ningún cambio y un valor de throttleTimeout) bajo o de 0), el cliente debe imponer su propio throttleTimeout antes de solicitar otro checkForUpdates a la cámara.

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

  • Cuando responde a checkForUpdates, la cámara debe determinar un throttleTimeout razonable. Si la cámara admite la lógica de solicitud antigua (responde solo después de waitTimeout si el estado no cambió), puedes devolver throttleTimeout como 0. En ese caso, los clientes pueden solicitar actualizaciones de inmediato.
  • Si la cámara solo admite respuestas rápidas (no se recomienda), debería mostrar un throttleTimeout razonable para evitar un tráfico constante de solicitudes o respuestas con el cliente. Por ejemplo, un throttleTimeout razonable serían 60 segundos para permitir una solicitud de cliente por minuto.
  • La práctica recomendada es mostrar un valor throttleTimeout apropiado 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 debería responder con un código de estado 5XX y un cuerpo JSON que contenga el código de error serverError.

Error

Código de error
missingParameter No se especificó stateFingerprint.
invalidParameterName No se reconocen 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 apropiado 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 arrojar 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."
    }
}