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 を返す必要があります。 たとえば、1 分ごとに 1 つのクライアント リクエストを許可するために妥当な throttleTimeout は 60 秒です。
  • ベスト プラクティス は、カメラの性能に適した throttleTimeout を返すことです。 サーバーの問題により、サーバーで適切な throttleTimeout を決定できない場合、カメラは serverError エラーコードを含む JSON 本体と 5XX ステータス コードで応答する必要があります。

エラー

エラーコード 説明
missingParameter stateFingerprint が指定されていません。
invalidParameterName 1 つ以上の入力パラメータ名を認識できません。
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."
    }
}