CheckForUpdates

/osc/checkForUpdates API は、クライアントが最後に認識した stateFingerprint とカメラの現在の fingerprint を比較して、状態の更新を特定します。

入力

名前 型 説明
stateFingerprint 文字列 クライアントが最後に /osc/state または /osc/checkForUpdates を呼び出したときのカメラ状態のフィンガープリント。
waitTimeout 整数（省略可） レスポンスを返す前にカメラの状態変化を待機する秒数。waitTimeout が期限切れになると、指紋が変更されていなくても、カメラから応答が返されます。waitTimeout が期限切れになる前に状態変更が検出された場合、または waitTimeout が省略された場合、カメラはすぐにレスポンスを返します。注: フィンガープリントが変更されていなくても、waitTimeout の有効期限が切れる前にカメラがレスポンスを返すことがありますが、ベスト プラクティスとして、waitTimeout が期限切れになるまで待つことをおすすめします。

カメラ実装に関する注意事項:

  • この呼び出しを受信すると、カメラは現在の状態のフィンガープリントと受け取った stateFingerprint パラメータを比較します。フィンガープリントが変更されている場合は、カメラはすぐに新しいフィンガープリントを返す必要があります。

出力

名前 タイプ 説明
stateFingerprint 文字列 カメラの状態の新しいフィンガープリント（/osc/state API と同様）。
throttleTimeout Integer クライアントが次の checkForUpdates 呼び出しの前に待機する推奨秒数。クライアントは throttleTimeout の期限が切れる前にリクエストを送信できます。カメラは、可能であればこれらの早期リクエストを許可する必要があります。

クライアント実装に関する注意事項:

  • レスポンスを受信したら、クライアントは受信した stateFingerprint をそのコピーと比較する必要があります。一致しない場合、クライアントは _/osc/state API を使用してカメラの現在の状態をリクエストする必要があります。
  • スマート クライアントは、カメラの応答に関係なくリクエストをスロットリングします。たとえば、カメラが標準以外のレスポンスを返した場合（すぐに変更なしで、throttleTimeout) が小さいか 0 の場合）、クライアントはカメラに別の checkForUpdates をリクエストする前に、独自の throttleTimeout を適用する必要があります。

カメラ実装に関する注意事項:

  • checkForUpdates に応答する際、カメラは適切な throttleTimeout を判断する必要があります。カメラが長時間のリクエスト ロジックをサポートしている場合（状態が変わっていない場合、waitTimeout の後にのみ応答する場合）、throttleTimeout を 0 として返しても問題ありません。この場合、クライアントはすぐにアップデートをリクエストできます。
  • カメラが迅速な応答のみをサポートしている場合（おすすめしません）、クライアントとの継続的なリクエスト/レスポンス トラフィックが発生しないように、適切な throttleTimeout を返す必要があります。たとえば、1 分あたり 1 つのクライアント リクエストを許可するには、適切な throttleTimeout は 60 秒です。
  • ベスト プラクティスとして、カメラの機能に適した throttleTimeout を返すことをおすすめします。サーバーの問題によりサーバーが適切な throttleTimeout を判断できない場合、カメラは 5XX ステータス コードと serverError エラーコードを含む JSON 本文を返します。

エラー

エラーコード 説明
missingParameter stateFingerprint が指定されていません。
invalidParameterName 認識できない入力パラメータ名があります。
invalidParameterValue パラメータ名は認識されていますが、無効な値が 1 つ以上あります。たとえば、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."
    }
}