Windowsのシェルで日本語の引数が壊れる｜APIが効かないと誤診した

01 / 本文

APIが効いていないと思った

商品検索のAPIに日本語のキーワードを渡したら、結果が0件で返ってきた。別のキーワードでは、まったく関係のない商品が並んだ。

「このAPIはキーワード検索が効かない」と結論づけた。 仕様書を読み直し、別のパラメータを試し、半日を使った。

同じ日に、問い合わせフォームのテスト送信でも日本語の値が空になり、入力エラーで弾かれていた。別の現象だと思っていた。

02 / 本文

両方とも同じ原因だった

APIもフォームも正常だった。壊れていたのは渡す側で、コマンドの引数に直接書いた日本語が、シェルを通る間に別の文字コードに変換されていた。

# 届かない
curl -s 'https://api.example.com/search' \n  --data-urlencode 'keyword=ハロウィン'

03 / 本文

受け取った側には別の文字列が届く

送信側のログには正しく見える。受信側のログを見ない限り、何が届いたのかは分からない。0件という結果だけが手元に残る。

これは環境の問題なので、同じコマンドを別のPCで打つと通ることがある。「自分の環境だけ」の違いは原因として最後に疑いがちで、そのぶん遠回りになる。

04 / 本文

Pythonから直接呼ぶのが確実

日本語を渡すときは、シェルの引数を経由させない。

import urllib.request, urllib.parse

q = urllib.parse.urlencode({'keyword': 'ハロウィン'})
url = 'https://api.example.com/search?' + q
with urllib.request.urlopen(url, timeout=20) as r:
    body = r.read().decode('utf-8')

05 / 本文

ファイル経由でも渡せる

multipart のフォーム送信なら、UTF-8のファイルに書いてから渡す。

printf '%s' 'ハロウィン' > /tmp/kw.txt
curl -s -F 'keyword=</tmp/kw.txt' https://example.jp/form

06 / 本文

疑う順番を変える

「効かない」「壊れている」と判断する前に、渡した文字列が届いているかを疑う。 0件やおかしな結果が返ったときの第一容疑者はこれになる。

確かめ方は簡単で、受け取った値をそのまま返すエンドポイントに同じコマンドを投げるか、取得したURLを print して目で見る。

APIの仕様書を読み直す前に、1回これをやる。 半日が5分で終わる。

07 / 本文

まとめ

- Windows のシェルでは、引数に直接書いた日本語が壊れることがある - 送信側のログは正しく見えるので、結果だけでは原因に辿り着けない - Python から直接呼ぶ。または UTF-8 のファイル経由で渡す - 「APIが効かない」と結論づける前に、届いた文字列を確かめる