冪等性とは?
冪等性とは、同じ識別情報を持つ操作を繰り返しても、最初の成功後に意図しない追加の影響が生じない性質です。クライアントが以前のリクエストの完了を判断できない場合に重要です。
冪等性の仕組み
冪等性を備えたサービスは、ネットワークの不確実性によって呼び出し元が同じ論理コマンドを再送しても、繰り返しの実行を一度の効果として扱います。サーバーは通常、リクエストの識別情報、処理状態、以前のレスポンスまたは結果のリソースとともにキーを永続化します。この保証には適用範囲と保持期間があり、無制限の重複排除を約束するものではありません。メディアシステムでは、再試行が発生しやすい境界で、アップロードの作成、エンコードの送信、課金操作、Webhook 処理を保護します。
要点
- 堅牢な実装では、再試行されたリクエストの関連パラメーターを、保存済みの操作と比較します。キーが同じでも入力が異なる場合に以前の結果を返すと、誤ったメディアが気づかないうちに関連付けられるおそれがあります。
- 同時に届く重複リクエストには、アトミックな予約または一意性制約が必要です。確認と挿入を別々に行うと、二つのワーカーがどちらも未登録と判断し、同じ効果を二度発生させる可能性があります。
- HTTP メソッドの意味論とアプリケーションの冪等性は別のものです。PUT はプロトコルレベルで冪等と定義されていますが、POST も操作固有のキーによって安全に再試行できるようにできます。
冪等性が重要になる場面
自作のサービスや、キーのサポートをドキュメントに明記している外部 API の呼び出しでは、再試行する操作に冪等性キーを割り当ててください。サーバーが別のリソースを作成せず、元の結果を返せるようになります。Transloadit の API は Assembly 作成時の冪等性キーを受け付けないため、Assembly の重複送信を排除する責任は、連携するアプリケーション側にあります。使用するキーは同じ論理操作を識別するものとし、無関係な処理に再利用しないでください。