リレーを安全に制御

ユースケース

このパターンは、リレー操作が実際の機器に影響し、呼び出し側がリトライ、不確実な結果、複数のリレーチャネルを、重複する副作用を生まずに処理する必要がある場合に使います。

1台のデバイスに対するすべてのリレー変更は、1つの relays 配列にまとめて送信してください。1回のバッチが1つのデバイスコマンドになり、デバイスが確実に処理できない可能性のある連続送信を避けられます。

デバイスタイプ定義一覧の取得（英語）を使って、device.relay.set、リレー数、許可されている操作を確認します。
目標とするリレー配列を組み立てます。単一チャネルの制御には1つの要素を、協調した変更には複数の一意なインデックスを使います。
この操作の意図に対して、呼び出し側が所有する新しい Idempotency-Key を生成します。
device:control とともにリレーコマンドの実行（英語）を呼び出します。
data.command.id と data.command.status を読み取ります。ステータスが SENT の場合は、終端状態に達するか、自分で設定した上限のポーリング期限までコマンド結果の取得（英語）を使用します。
デバイスの確認応答に data.state が含まれている場合はそれを使用してください。任意項目を埋めるためだけに別の更新を発行しないでください。
結果が TIMEOUT の場合は、別の操作が安全かどうかを判断する前に、現在のデバイス状態を読み取ってください。

結果	意味	クライアントの対応
HTTP `202` + `COMMAND_ACCEPTED`	プラットフォームがリクエストを受け付けた。独立したコマンドステータスではない	`data.command.status` を読み取り、コマンドIDを保持する
`SENT`	コマンドはまだ確認待ちである	上限のあるポーリングで結果を照会する
`SUCCESS`	デバイスが実行を確認した	返された状態があれば適用する
`FAILED`	プラットフォームがコマンドの未完了を確認した	自動リトライを停止し、失敗を処理する
`TIMEOUT`	待機ウィンドウ内に最終確認が届かなかった	デバイスが実行したかどうかを想定せず、まず現在の状態を読み取る

ネットワーク障害によりHTTPの結果が不明な場合は、同じ Idempotency-Key で同一のリクエストを再試行してください。
429 RATE_LIMITED の後は Retry-After を待ち、元のキーで同じ操作を再試行してください。
別のデバイス、別のリレー配列、別の操作にキーを再利用しないでください。それは IDEMPOTENCY_CONFLICT を返します。
TIMEOUT の後は、まず状態を更新してください。状態がまだ不明な場合は、別の物理操作を送信する前にビジネス上の判断を求めてください。
以前のレスポンスが失われていた場合でも、JOG などの機器操作を繰り返すと実際の副作用が発生する可能性があります。それに応じて確認手順とオペレーター向けの安全策を設計してください。