curl 実践リファレンス｜API疎通・ヘルスチェック・デバッグのユースケース逆引き

curl はHTTPの「何でも屋」。ブラウザやGUIツールを開かなくても、コマンド1行でAPIの応答・ステータス・ヘッダ・TLSの中身まで確認できます。この記事は「やりたいこと→コマンド→注意点」のユースケース逆引きで、疎通確認・認証・ヘルスチェック・CDN確認の実務断片をまとめました。最後に1画面で引ける逆引き早見表も付けています。

01なぜcurlか — HTTPの「何でも屋」

curl（カール）は、HTTPリクエストをコマンド1本で送れるツールです。ブラウザやPostmanのようなGUIを開かなくても、API・Webサーバ・ロードバランサが返す「生の応答」をその場で確認できます。

「つながらない」「500が返る」「なぜか遅い」——こうしたときの疎通確認の第一手がcurlです。名前解決（DNS）・TCP接続・TLSハンドシェイク・HTTPステータスのどこで詰まっているのかを、1コマンドずつ切り分けられます。

• ほぼ全てのLinux／macに標準搭載。最近のWindowsにも入っており、SSHで入った先でもすぐ使える。
• ヘッダ・ステータス・本文・TLS情報まで、見たいものだけを取り出せる。
• スクリプトやCI、デプロイ後のヘルスチェックにそのまま組み込める。

02基本オプション — まずこれだけ

最初に覚えるのはこの7つで十分です。組み合わせるだけで大半の確認ができます。

# ヘッダ＋本文を表示（-i）
curl -i https://api.example.com/health

# ヘッダだけ＝HEAD（-I）。生死とリダイレクト先の確認に
curl -I https://example.com/

# 詳細（-v）：接続・TLS・送受信ヘッダまで全部見える
curl -v https://api.example.com/health

# 静かに本文だけ（-s は進捗バーを消す）
curl -s https://api.example.com/health

# 保存：-o は指定名で、-O はURL末尾のファイル名で保存
curl -s -o result.json https://api.example.com/data
curl -O https://example.com/archive.tar.gz

# リダイレクト（3xx）を自動で追う（-L）
curl -L https://example.com/

03ユースケース：APIを叩く

REST APIの疎通確認は、メソッド（-X）・ヘッダ（-H）・ボディ（-d）の3点セットで組み立てます。

# POST（JSONボディ）
curl -X POST https://api.example.com/v1/items \
  -H 'Content-Type: application/json' \
  -d '{"name":"widget","qty":3}'

# 大きい/厳密なボディはファイルから（改行や空白をそのまま送る）
curl -X POST https://api.example.com/v1/items \
  -H 'Content-Type: application/json' \
  --data-binary @body.json

# GET（クエリ付き。&を含むのでURL全体をクォートで囲う）
curl -s 'https://api.example.com/v1/items?limit=10&sort=desc'

# PUT / DELETE
curl -X PUT https://api.example.com/v1/items/42 \
  -H 'Content-Type: application/json' -d '{"qty":5}'
curl -X DELETE https://api.example.com/v1/items/42

04ユースケース：認証を付ける

多くのAPIはトークンやBasic認証を要求します。認証情報はヘッダ（-H）かユーザ指定（-u）で渡します。

# Bearer トークン（一番よく使う）
curl -H 'Authorization: Bearer YOUR_TOKEN' https://api.example.com/v1/me

# トークンは環境変数に置いてコマンド履歴に残さない
export TOKEN="YOUR_TOKEN"
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/me

# Basic 認証（user:pass）。パスワードを省略すると対話入力にできる
curl -u alice:YOUR_PASSWORD https://api.example.com/private
curl -u alice https://api.example.com/private

# APIキーを独自ヘッダで
curl -H 'X-API-Key: YOUR_KEY' https://api.example.com/v1/data

AWSのAPIを直接叩きたい場合、curlには --aws-sigv4 によるSigV4署名オプションがあります。ただしリージョン・サービス名・認証情報の指定が細かく、鍵の取り回しも自前になります。AWS APIを叩くなら、署名と一時認証情報の更新を自動でやってくれる AWS CLI を推奨します。curlのSigV4は「CLIが入れられない最小環境での確認」など限定用途に留めるのが安全です。

05ユースケース：疎通とデバッグ

「どこで詰まっているか」を切り分けるのがcurlの真骨頂です。ステータス・所要時間・DNS・TLSを一つずつ確認します。

# ステータスと所要時間だけ知りたい（本文は捨てる）
curl -w '%{http_code} %{time_total}\n' -o /dev/null -s https://example.com/

# DNSを上書きして特定サーバに直接当てる（LB配下の1台を検証）
curl --resolve api.example.com:443:10.0.1.23 https://api.example.com/health

# タイムアウトを付けてハングを防ぐ
curl --connect-timeout 3 --max-time 10 https://api.example.com/health

# TLSの中身（証明書・プロトコル）を確認
curl -v https://example.com/ 2>&1 | grep -Ei 'SSL|TLS|subject|issuer|expire'

06ユースケース：運用（ヘルスチェック・メタデータ）

AWS運用では、ロードバランサや監視スクリプトからの疎通確認にcurlが活躍します。

ヘルスチェックの確認：ALB経由の応答と、ターゲット（EC2）を直接叩いた応答を見比べると、問題がLBとアプリのどちらにあるか切り分けられます。

# ターゲット（アプリ）を直接叩いて 200 を返すか確認
curl -i http://10.0.2.15:8080/healthz

# ALB経由の応答（ステータス行だけ）
curl -sI https://app.example.com/ | head -n 1

IMDSv2でメタデータ取得：EC2ではトークン必須の IMDSv2 が既定・推奨です。まず PUT でトークンを取得し、次にそのトークンをヘッダに付けて GET する2段階が現行の正しい手順です。

# 1) PUTでトークンを取得（TTL付き、最大21600秒）
TOKEN=$(curl -sX PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

# 2) トークンをヘッダに付けてGET
curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/instance-id

スクリプトでの失敗検知：監視やデプロイ後チェックでは、HTTPエラーを終了コードに反映させます。

# 4xx/5xx を「失敗」として終了コードに反映（-f）
if curl -fsS https://api.example.com/health > /dev/null; then
  echo "healthy"
else
  echo "unhealthy (exit=$?)"; exit 1
fi

07ユースケース：CDN・キャッシュ確認

CDNが効いているか、キャッシュがHIT/MISSのどちらかは、レスポンスヘッダを見れば分かります。本体をダウンロードせずHEADで確認するのがコツです。

# キャッシュ関連ヘッダだけ抜き出す
curl -sI https://cdn.example.com/assets/app.js | grep -iE 'cache|age|etag|x-cache|cf-'

# 部分取得（Range）：先頭1KBだけ取得して確認
curl -r 0-1023 -o head.bin https://cdn.example.com/large.bin

08つまずきポイント

• -d を付けると自動でPOSTになり、Content-Type: application/x-www-form-urlencoded が既定で付く。JSONを送るなら -H 'Content-Type: application/json' を明示する。
• -d @file / --data-binary @file の @ は「ファイルの中身を読む」という意味。@ を付け忘れると、文字列 body.json がそのまま送られてしまう。
• -d は改行を落とす。改行込みで送りたいなら --data-binary @file を使う。
• -k（--insecure）はTLS証明書の検証を無効化する。原因を隠すだけなので本番スクリプトには残さない。証明書エラーは基本「直す」もの。

スペースや記号を含むクエリは、自前で組み立てず --data-urlencode にエンコードさせます。

# フォーム値を安全にURLエンコードして送る
curl -G https://api.example.com/search \
  --data-urlencode 'q=hello world & more' \
  --data-urlencode 'lang=ja'
# -G を付けると --data-* をボディではなくクエリ文字列に回す（GETになる）

09逆引き早見表（1画面チートシート）

「やりたいこと」から引けるようにまとめました。ブックマークして、そのままコピペで使えます。

10よくある質問（FAQ）