If-Match

使い方

If-Match ヘッダーは、ETag 値を比較することで条件付きリクエストを可能にします。クライアントは、リソースの現在のエンティティタグが列挙した値のいずれかに一致する場合にのみサーバーがリクエストを処理するよう、このヘッダーを含めます。

GET や HEAD のような安全なメソッドでは、If-Match ヘッダーはエンティティタグが一致するリソースにレスポンスを限定します。これはキャッシュの検証ではなく特定の表現を選択するものです（キャッシュの検証には代わりに If-None-Match を使います）。

PUT や DELETE のような状態を変更するメソッドでは、If-Match ヘッダーが更新の喪失（lost update）問題を防ぎます。2 つのクライアントが同じリソースを取得し、それぞれ独立にコピーを変更して書き戻そうとした場合、If-Match ヘッダーは最初の書き込みだけが成功するようにします。最初の書き込みの後で ETag が変わるため、2 番目の書き込みは 412 Precondition Failed で失敗します。

このパターンは楽観的並行性制御として知られています。クライアントはリソースとその ETag を読み取り、ローカルで変更を加え、元の ETag を If-Match に設定して更新を送信します。サーバーは更新を適用する前に、その間にリソースが変更されていないことを確認します。

If-Match ヘッダーは強い比較のみを行います。不透明な値が同一であっても、弱いエンティティタグ（W/ を前置したもの）は一致しません。この厳格な挙動により、リソースのバイトレベルでの同一性が保証されます。

エンティティタグのリスト

二重引用符で囲まれ、カンマで区切られた 1 つ以上の ETag 値です。サーバーは各値をリソースの現在のエンティティタグと照合します。

ワイルドカード（*）

アスタリスク * は、リソースの現在のあらゆる表現に一致します。この形式は、エンティティタグの値に関わらず、対象リソースが存在してさえいれば成立します。* の値は、対象 URI にすでにリソースが存在する場合に PUT が新しいリソースを作成してしまうのを防ぐ用途でよく使われます。

例

クライアントがリソースを更新するために PUT リクエストを送ります。If-Match ヘッダーは、最初の GET レスポンスで得た ETag を運びます。サーバーは ETag がまだ一致する場合にのみ更新を適用します。

PUT /document/42 HTTP/1.1
Host: api.example.re
Content-Type: application/json
If-Match: "a1b2c3d4"

{"title": "Updated Document"}

別のクライアントがリソースを変更していた場合、ETag はもう一致しません。サーバーは 412 Precondition Failed で応答し、更新を拒否します。

HTTP/1.1 412 Precondition Failed
Content-Type: application/json
ETag: "e5f6g7h8"

複数のエンティティタグはカンマ区切りの値として列挙します。列挙した値のいずれか 1 つがリソースの現在の ETag と一致すれば、条件は成立します。

If-Match: "a1b2c3d4", "x9y8z7w6"

ワイルドカードの形式は、リソースが存在する場合に成立します。これにより、PUT が誤って新しいリソースを作成するのを防げます。

If-Match: *