データとクエリの構造を分ける
URL のクエリは多くの場合、疑問符の後にアンパサンドで区切った key=value の組として記述します。これらの区切り文字には構造上の意味があります。値自体にアンパサンドが含まれるなら、別の組との区切りと誤認されないよう、値の中で表現する必要があります。コンポーネントエンコーダーは1つの値を準備し、クエリビルダーはキーと値を受け取って全体の構造を組み立てます。これは異なる階層の作業です。完成したクエリをコンポーネントエンコーダーに通すと、疑問符、等号、アンパサンドまでデータになってしまいます。逆に、信頼できない生の値を区切り文字の間に貼り付け、ブラウザーが意図した境界を推測してくれると期待してはいけません。
同じキーを繰り返すクエリ
検索画面で q に「赤 & 青」を入れ、tag に a と b の二つの値を指定するとします。JSON からクエリへのツールに、q を文字列、tag を配列とするオブジェクトを渡します。フォーム形式で組み立てた結果は q=%E8%B5%A4+%26+%E9%9D%92&tag=a&tag=b です。プラス記号はこの方式の空白を表し、%26 は検索語句の一部であるアンパサンドを守ります。対応するツールで解析し直すと、q は「赤 & 青」、tag は二つの文字列の配列に戻ります。tag=a&tag=b という繰り返しは、カンマを含む一つの値とは異なる構造です。埋め込みツールで片方の tag を変え、結果も確かめてください。
- 元のデータ：q = 赤 & 青、tag = a と b
- クエリ: q=%E8%B5%A4+%26+%E9%9D%92&tag=a&tag=b
- 解析結果: q は一つの語句、tag には二つの値
値のエンコードとクエリの組み立てを区別する
専用の URL コンポーネント符号化ツールは、一つの値に対する規則を使います。その方式では空白を %20 と表せますが、URLSearchParams 型のクエリーシリアライザーは空白にプラス記号を使います。どちらもそれぞれの文脈では有効でも、同じ文字列とは限りません。フォーム形式のクエリーに含む文字どおりのプラス記号は、解析時に空白へ変わらないようエスケープする必要があります。符号化済みのパーセント記号をさらに符号化すると %25 になり、意図しない二重符号化の手掛かりになります。クエリー作成ツールが処理するまではキーと値を加工前のまま保つか、手動で組み立てる前に各コンポーネントを一度だけ符号化してください。同じデータに二つの方法を混ぜないでください。
往復変換で保持できない情報を知る
MultiVerto のクエリーパーサーは、同じ名前が繰り返されたパラメーターを配列にまとめます。クエリーの値は、書き出す前の JSON オブジェクトで数値や真偽値だった場合も、読み込むとすべて文字列になります。元の数値型を自動的に復元しません。空の配列や入れ子のオブジェクトは、この単純なキーと値の形式で直接表せないため、ビルダーは拒否します。API によって空値、重複キー、順序の扱いも異なります。往復変換で有用な組を保てても、豊かな JSON オブジェクトの全情報が残るとは限りません。配列、欠けた項目、空文字列の表し方を決める前に、実際の API 契約を確認してください。
再現できるテスト例を残す
まず送信先のエンドポイントを決め、各キーと加工前の値を別々に書き出します。クエリー文字列を一度組み立て、予約文字がどのように符号化されたかを確認してください。その後で解析し直し、アンパサンド、プラス記号、パーセント記号、ASCII 以外の文字を含む値も、意図したキーと値の組として残ったかを調べます。サーバーが配列を受け付けるなら、同じキーを繰り返した場合の解釈も試してください。文字が符号化されていてもクエリー文字列に秘密情報を入れてはいけません。URL はコピー、記録、共有され得ます。MultiVerto は例をブラウザー内で計算しますが、実際に公開または送信する URL には別の公開範囲と保存規則が適用されます。