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，要求相機的目前狀態。
  • 不論相機回應為何，智慧型用戶端都會為要求進行節流處理。 例如，如果相機傳回非標準回應，(立即傳回、「毫無變更」且有很低或為 0 的 throttleTimeout)，用戶端應該強制施行自己的 throttleTimeout，然後才要求另一個來自相機的 checkForUpdates。

相機實作注意事項：

  • 回應 checkForUpdates 時，相機應該決定一個合理的 throttleTimeout。 如果相機支援長期要求邏輯 (只有當 waitTimeout 過後狀態都無變更，才會回應)，就可以將 throttleTimeout 傳回為 0。 在此情況下，用戶端可以立即要求更新。
  • 如果相機只支援快速回應 (不建議使用)，應該傳回合理的 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."
    }
}