CheckForUpdates

/osc/checkForUpdates API 通过将客户端最近一次的已知 stateFingerprint 与相机的当前 fingerprint 进行比较来识别状态更新。

输入

名称 类型 说明
stateFingerprint 字符串 客户端上次调用 /osc/state 或 /osc/checkForUpdates 时的相机状态指纹。
waitTimeout 整数（可选） 在返回响应之前等待相机状态发生变化的秒数。waitTimeout 到期后，即使指纹没有更改，摄像头也应返回响应。如果在 waitTimeout 过期之前检测到状态变化，或者省略了 waitTimeout，摄像头应立即返回响应。注意：即使指纹未更改，摄像头也可以在 waitTimeout 过期之前返回响应，但最佳实践是等待 waitTimeout 过期。

相机实现注意事项：

  • 收到此调用后，相机会将其当前状态指纹与收到的 stateFingerprint 参数进行比较。如果指纹已更改，相机必须立即返回新的指纹。

输出

名称 类型 说明
stateFingerprint 字符串 相机状态的新指纹（与 /osc/state API 中的相同）。
throttleTimeout 整数 建议在下一次调用 checkForUpdates 之前等待的秒数。客户端可以在 throttleTimeout 到期之前发出请求，并且相机应尽可能允许这些提前的请求。

客户端实现注意事项：

  • 收到响应后，客户端应将收到的 stateFingerprint 与其副本进行比较。如果不匹配，客户端应使用 _/osc/state API 请求相机的当前状态。
  • 无论相机响应如何，智能客户端都会限制请求。例如，如果相机返回非标准响应（立即返回没有变化且 throttleTimeout) 较低或为 0），那么客户端在从相机请求另一个 checkForUpdates 之前应强制实施自己的 throttleTimeout。

相机实现注意事项：

  • 在响应 checkForUpdates 时，相机应确定合理的 throttleTimeout。如果相机支持长期请求逻辑（仅在状态未更改时在 waitTimeout 后响应），则可以作为 0 返回 throttleTimeout。在此情况下，客户端可以立即请求更新。
  • 如果相机仅支持快速响应（不推荐），则应返回合理的 throttleTimeout，以避免来自客户端的持续请求/响应流量。例如，合理的 throttleTimeout 为 60 秒，以允许每分钟一个客户端请求。
  • 最佳实践是返回适合相机功能的 throttleTimeout。如果服务器因服务器问题而无法确定适当的 throttleTimeout，相机应以 5XX 状态代码和包含 serverError 错误代码的 JSON 正文进行响应。

错误

错误代码 说明
missingParameter 未指定 stateFingerprint。
invalidParameterName 一个或多个输入参数名称无法识别。
invalidParameterValue 参数名称已被识别，但一个或多个值无效；例如，waitTimeout 超出范围或其类型不正确。
serverError 服务器无法为其响应确定合适的 throttleTimeout 值。服务器问题由响应中返回的 5XX 值确定。相机制造商应提供一个 5XX 代码表，以及可能会引发此错误的相应服务器状态。

示例
请求 
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
}
答案 
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
}
请求 
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
}
答案 
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."
    }
}