2.2.8. クエリパラメータ (Query Parameters)

リクエストターゲット URI のクエリ部分が [HTMLURL] の 5 節 ("application/x-www-form-urlencoded") で定義される形式の HTML フォームパラメータを用いる場合, @query-param 派生コンポーネントによりこれら個々のクエリパラメータを指定できる. クエリパラメータは [HTMLURL] の 5.1 節 ("application/x-www-form-urlencoded parsing") に従って解析しなければならない (MUST), その結果 (nameString, valueString) のタプルのリストとなる. 各コンポーネント識別子の必須 (REQUIRED) な name パラメータには, 単一のクエリパラメータのエンコード済み nameString が String 値として含まれる. 単一名付きパラメータのコンポーネント値は, その単一のクエリパラメータのエンコード済み valueString である. 複数の異なる名前のクエリパラメータを被覆コンポーネント (covered components) に含めてもよい (MAY). 単一名付きパラメータはクエリ文字列内の出現順に関わらず, 被覆コンポーネント内では任意の順序でよい (MAY).

name パラメータの値および単一名付きパラメータのコンポーネント値は, 次の手順で算出される:

[HTMLURL] の 5.1 節 ("application/x-www-form-urlencoded parsing") で定義されるとおり, 名前付きクエリパラメータの nameString または valueString を解析する, これはパーセントエンコードされたオクテットがデコードされた後の値である.
[HTMLURL] の 5.2 節 ("application/x-www-form-urlencoded serializing") で定義される「エンコード後にパーセントエンコードする」手順を用いて nameString または valueString をエンコードする, これにより ASCII 文字列 [ASCII] となる.
その ASCII 文字列を出力する.

コンポーネント値には, 先頭の疑問符 (?), 等号 (=), 区切りのアンパサンド (&) 文字は含まれない. valueString が空の名前付きクエリパラメータは, コンポーネント値として空文字列を持つ. 実装の不整合により, 一部のクエリパラメータ解析ライブラリはそのような空の値を捨てることに注意すること.

被覆コンポーネントとして名前が付けられたクエリパラメータがクエリパラメータに存在しない場合, 署名ベース生成においてエラーとならなければならない (MUST).

例えば, 次のリクエストについて:

GET /path?param=value&foo=bar&baz=batman&qux= HTTP/1.1 Host: www.example.com

baz, qux, param という名前付きクエリパラメータを示すと, 次の @query-param コンポーネント値となる:

baz: batman

qux: 空文字列

param: value

および次の署名ベース行となる. (SP) は空のコンポーネント値の前の単一の末尾スペース文字を示す:

"@query-param";name="baz": batman "@query-param";name="qux":(SP) "@query-param";name="param": value

この派生コンポーネントにはいくつか制限がある. 特に, [HTMLURL] の 5 節 ("application/x-www-form-urlencoded") に示すアルゴリズムは, パーセントエスケープされた UTF-8 エンコーディングを用いるクエリパラメータのみをサポートする. 他のエンコーディングはサポートされない. また, 同一の名前のパラメータが複数ある場合, 実運用では確実にサポートされていない. リクエスト内でパラメータ名が複数回現れる場合, その名前付きクエリパラメータを含めてはならない (MUST NOT). アプリケーション内で複数パラメータが一般的である場合, 2.2.7 節で定義される @query コンポーネント識別子を用いてクエリ文字列全体に署名することが推奨される (RECOMMENDED).

エンコード手順により, 値に改行やその他問題のある文字を含むクエリパラメータや, スペースをプラス (+) 文字で表すなどの別表現を用いる場合にも対応できる. このメッセージ内のクエリパラメータについて:

NOTE: '' line wrapping per RFC 8792

GET /parameters?var=this%20is%20a%20big%0Amultiline%20value&
bar=with+plus+whitespace&fa%C3%A7ade%22%3A%20=something HTTP/1.1 Host: www.example.com Date: Tue, 20 Apr 2021 02:07:56 GMT

結果として次のように値がエンコードされる:

"@query-param";name="var": this%20is%20a%20big%0Amultiline%20value "@query-param";name="bar": with%20plus%20whitespace "@query-param";name="fa%C3%A7ade%22%3A%20": something

エンコードを適用しなかった場合, 結果の値は次のようになる:

"@query-param";name="var": this is a big multiline value "@query-param";name="bar": with plus whitespace "@query-param";name="façade": ": something

このベース文字列はコンポーネント名および値に対する制約に違反する文字を含み, したがって無効である.

2.2.8. クエリパラメータ (Query Parameters)​

2.2.8. クエリパラメータ (Query Parameters)