クエリパラメータの値として"="(イコール)や"&"(アンパサンド)を設定したい。

Question

Javaにて、以下を設定項目とするWebAPIの呼び出しを実装中です。

• 送信方式：POST
• Content-Type：application/x-www-form-urlencoded
• クエリパラメータ：キー1=値1&キー2=値2&キー3=値3

クエリパラメータの各値には"="や"&"が設定される可能性があるのですが、Content-Typeがapplication/x-www-form-urlencodedの場合、そもそも接続文字列として"="と"&"が使用されているため、これらを値として設定するには考慮が必要と考えております。

質問１： このような場合、そもそもエンコードにあたり考慮は必要でしょうか。
質問２： 考慮が必要である場合、どのようにクエリパラメータを作成すれば良いのでしょうか。

現在の実装

import org.apache.commons.codec.net.URLCodec.URLCodec;

public request() {
    String url = "http://webapi";
    StringBuilder sb = new StringBuilder();
    String value1 = "value1";
    String value2 = "hoge&fuga";
    String value3 = "foo=bar";
    sb.append("key1=").append("value1")
    .append("&").append("key2=").append(value2)
    .append("&").append("key3=").append(value3);

    String enc = new URLCodec("URL-8").encode(sb.toString());

    HttpURLConnection conn;
    conn = new URL(url).openConnection();
    conn.setRequestMethod("POST");
    conn.setDoOutput(true);
    conn.setInstanceFollowRedirects(false);
    conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded;charset=utf-8");
    conn.connect();
    try (PrintWriter pw = new PrintWriter(
        new BufferedeWriter(
            new OutputStreamWriter(
                conn.getOutputStream(), "utf-8"))))
    {
        pw.print(enc);
    }
}

※例外処理は見やすさのため除外しています。
また、文字列をエンコードするのにapache commonsのURLCodecを使用しています。

Answer 1

質問１： このような場合、そもそもエンコードにあたり考慮は必要でしょうか。

はい、必要です。

質問２： 考慮が必要である場合、どのようにクエリパラメータを作成すれば良いのでしょうか。

全体のクエリ文字列を一度に作ろうとするから難しくなります。それぞれのクエリパラメータ、すなわち「パラメータ名=値」のそれぞれを個別にエンコードし、複数のパラメータを配列もしくはリストで扱って、最後に&で連結するようにすれば考えることが局所化され、実装がシンプルになるかと思います。

以下はパラメータの名前と値をフィールドに持つQueryParamクラスで、オーバーライドしたtoStringメソッドの実行時にエンコードした「パラメータ名=値」をStringで返し、複数のパラメータをString.joinで連結して全体のクエリ文字列を生成するサンプルコードです。ちなみに質問者さんご提示のコード中、URLCodecのコンストラクタで指定していたキャラクターセットは"URL-8"ではなく"UTF-8"の誤りだと思いましたので、この部分は修正しています。("URL-8"だと私の環境ではencodeメソッドの実行時に例外がスローされました)

import org.apache.commons.codec.EncoderException;
import org.apache.commons.codec.net.URLCodec;
import java.util.List;
import java.util.ArrayList;

public class QueryParam {
	private String name;
	private String value;

	public static final String CHARSET = "UTF-8";
	private static URLCodec codec = new URLCodec(CHARSET);
	
	public static void main(String[] args)
			throws EncoderException
	{
		System.out.println("start.");

		// 複数のクエリパラメータを格納するリスト
		List<String> parameters = new ArrayList<String>();

		// 1: "key1=value1"
		parameters.add(new QueryParam("key1", "value1").toString());

		// 2: "キー2=日本語値2"
		parameters.add(new QueryParam("キー2", "日本語値2").toString());

		// 3: パラメータ名と値に"=& "が含まれるパターン
		parameters.add(new QueryParam("k3=& ", "v3=& ").toString());

		// "&"でつなげて全体のクエリー文字列を生成
		String form = String.join("&", parameters);
		System.out.println("query string: " + form);
	}

	public QueryParam(String name, String value) {
		this.name = name;
		this.value = value;
	}

	/* パラメータ名と値をそれぞれエンコードして文字列化
	 */
	@Override
	public String toString() {
		String result = null;
		try {
			result = codec.encode(name) + "=" + codec.encode(value);
		} catch (EncoderException ex) {
			// ※ 実製品では適切に例外ハンドリングしましょう
			ex.printStackTrace();
			;
		}
		return result;
	}
}

これを実行すると以下のようになります。読みづらいかもしれませんが、パラメータ名と値はエンコードした後に=で繋ぎ、それぞれのパラメータは&で連結されていることが分かると思います。

start.
query string: key1=value1&%E3%82%AD%E3%83%BC2=%E6%97%A5%E6%9C%AC%E8%AA%9E%E5%80%A42&k3%3D%26+=v3%3D%26+

尚、Eclipse 上のJavaSE-11、Apache Commons Codec 1.15の「commons-codec-1.15.jar」で試しました。

Comments

[curveworks]

ご回答ありがとうございました。
自分の認識として、application/x-www/urlencodedでリクエストを送信する場合、=も&も含めてすべてエンコードする必要がある前提の頭になっていたことによる質問でした。
サンプルコードも丁寧に記載して頂き大変参考になりました。ありがとうございます。
（ご認識の通り"URL-8"は"UTF-8"の誤りでした。失礼いたしました。）

Answer 2

RFC のどこかには書いてあるわけですが、例えば
URLのクエリーパラメータでエスケープしなくていい文字はどれか？

Comments

[curveworks]

ご回答ありがとうございました。
自分の認識として、application/x-www/urlencodedでリクエストを送信する場合、=も&も含めてすべてエンコードする必要がある前提の頭になっていたことによる質問でした。