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) 的即時回應)，則用戶端在向相機要求另一個 checkForUpdates 之前，應先施加自己的 throttleTimeout。

相機實作注意事項：

  • 回應 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."
    }
}