「curl って結局どのオプションだっけ」と、API を叩くたびに手が止まっていた時期が私にはあります。
-X や -d をなんとなく並べて、動かなければ順番を疑う、という行き当たりばったりな使い方でした。
とはいえ実際に使うのは数個だけで、そこを一度整理してからは毎回ググらずに済んでいます。
今回は REST API を叩くときに私がよく使う curl オプションを、用途別にまとめた早見メモです。
まずは一番シンプルな形
curl は URL を渡すだけで、その中身を取ってきて標準出力に流します。
curl https://api.example.com/usersこれは GET リクエストで、メソッドを指定しなければ自動的に GET になります。
ブラウザのアドレスバーに URL を打ち込むのと、やっていることはほぼ同じですね。
-H・-d・-X ｜ 送信でよく使う三つ
データを送る側に回ると、この三つが主役になります。
-H はヘッダを一つ足すオプションで、複数付けたいときは -H を並べます。
-d はリクエストボディを送るためのオプションです。
-d を付けると curl は自動で POST になり、Content-Type も application/x-www-form-urlencoded が既定で入ります。
JSON を送るなら、この既定ヘッダを自分で上書きする必要があります。
curl -X POST \
-H "Content-Type: application/json" \
-d '{"name":"kamome"}' \
https://api.example.com/users-X はメソッドを明示したいときに使うオプションです。
-d があれば POST は自動なので、上の -X POST は省いても動きは変わりません。
DELETE や PUT を投げるときにこそ、-X の出番になります。
-o・-i・-L・-s ｜ 取得と挙動を整える
中身を画面で確かめたいのか、ファイルに落としたいのかで、添えるオプションは変わってきます。
-o はレスポンスをファイルに保存するオプションで、-O を使えば URL 末尾のファイル名がそのまま名前になります。
レスポンスヘッダを本文ごと表示したいときの相棒が -i。
-L はリダイレクトを追いかけるオプションです。
301 や 302 で中身が空に見えるときは、たいてい -L の付け忘れが原因です。
-s は進捗表示を黙らせるオプションで、スクリプトの中ではほぼ必須ですね。
# ステータスコードだけを取り出す
curl -w '%{http_code}\n' -o /dev/null -s https://example.com-w は出力の書式を決めるオプションで、%{http_code} と書けばステータスコードだけを抜き出せます。
–json ｜ JSON を投げるなら一番短い
毎回 -H "Content-Type: application/json" を書くのが面倒なら、curl 7.82 以降で使える --json が近道です。
–json は、-d と Content-Type、Accept の三つをまとめて面倒みてくれるショートカットです。
curl --json '{"model":"llama3.2","prompt":"hello"}' \
http://localhost:11434/api/generate頭に @ を付ければファイルから読み込め、--json @body.json のように書けます。
古い curl には –json が無いので、環境が混在するなら従来の -H と -d で書いておく方が無難ですね。
送受信の詳しい挙動は、everything curl の解説が正確でおすすめです。
最後に
curl には数えきれないほどオプションがありますが、API を叩く日常で触るのは今回の数個にほぼ収まります。
まずこの型を手に馴染ませて、足りなくなったら公式マニュアルを引く、という順番で私はだいたい困っていません。
ローカル LLM を curl で叩く具体例は別の記事にまとめているので、手を動かしたい方はそちらもどうぞ。
以上です。
コメントを残す