ServBay での cURL の使い方

cURL（カール）は、HTTP・HTTPS・FTP など様々なプロトコルでデータ転送を行うためのパワフルなコマンドラインツールおよびライブラリです。Web 開発においては、HTTP リクエストの発行、API の呼び出し、ファイルのダウンロードやアップロード、サービスの接続テストなど、多くのシーンで不可欠なツールとなっています。

ServBay は開発者向けローカル Web 開発環境として、最新の cURL ツールをインストール時に標準搭載しており、追加のインストール作業は不要です。ServBay の提供するターミナル環境では、curl コマンドをすぐそのまま利用でき、ネットワーク関連の操作やテストを簡単に実施できます。

本ドキュメントでは、ServBay 環境での cURL の基本的な使い方から応用例、高度なテクニックまで詳しく解説します。

インストールと設定

cURL のインストール

ServBay には cURL ツールが標準で組み込まれているため、開発者が個別にインストールする必要はありません。ServBay のターミナルでそのまま curl コマンドを使えます。

cURL の利用可否やバージョンを確認するには、ServBay のターミナルで以下のコマンドを入力してください：

curl --version

このコマンドを実行すると、cURL のバージョン情報とサポートするプロトコル・機能一覧が表示され、cURL の準備が整っていることが確認できます。

cURL の設定

日常のほとんどの用途において、cURL は追加設定なしで問題なく動作します。細かい挙動は豊富なコマンドラインオプションを通じて柔軟に制御でき、さまざまなデータ転送要件に対応可能です。

基本的な使い方の例

cURL では多様なコマンドオプションを活用して、幅広いデータ転送業務に対応できます。主な Web 開発シーンでの利用例をご紹介します。

HTTP GET リクエストを送信する

GET リクエスト送信は cURL の最も一般的な使い方の一つで、指定した URL からリソースを取得する際に利用します。

curl -X GET https://api.servbay.demo/data

なお、GET はデフォルトメソッドなので、下記のように省略できます：

curl https://api.servbay.demo/data

HTTP POST リクエストを送信する

POST リクエストは、フォームデータや JSON など、サーバーにデータを送信する際に使われます。-d（または --data）オプションで送信内容を指定します。

curl -X POST -d "param1=value1&param2=value2" https://api.servbay.demo/data

ファイルをダウンロードする

cURL でのファイルダウンロードも簡単です。-O オプションを使うと、リモートファイル名のまま現在のディレクトリへ保存されます。

curl -O https://servbay.demo/file.zip

保存先のファイル名を指定したい場合は -o オプションを使用します：

curl -o local_filename.zip https://servbay.demo/file.zip

ファイルをアップロードする

cURL を使ってファイルアップロードも容易に行えます。-F（--form）オプションで、name=@/path/to/file 形式でファイルを指定します。

curl -X POST -F "file=@/Applications/ServBay/www/servbay.demo/upload/document.pdf" https://api.servbay.demo/upload

/Applications/ServBay/www/servbay.demo/upload/document.pdf は実際にアップロードしたいファイルパスに置き換えてください。

高度な活用テクニック

cURL には基本機能の他にも、多数の進んだオプションがあり、ネットワークツールとして非常に柔軟な運用が可能です。

HTTP ヘッダーの設定

-H（または --header）オプションで、独自の HTTP ヘッダーをリクエストに追加できます。JSON など特定の Content-Type の指定、API キーや Bearer token 送信などの用途で便利です。

curl -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" https://api.servbay.demo/data

JSON データの取り扱い

現代 API 開発では JSON フォーマットが主流です。cURL では JSON の送信や受信も簡単に行えます。

JSON データ送信

JSON データ送信時は Content-Type: application/json ヘッダーを指定し、-d オプションで JSON 文字列を渡します。

curl -X POST -H "Content-Type: application/json" -d '{"key1":"value1", "key2":"value2"}' https://api.servbay.demo/data

JSON レスポンスの取得と整形（jq との組み合わせ）

cURL で取得したレスポンスはプレーンテキストです。きれいに JSON を閲覧・パースしたい場合は、強力な CLI ツール jq と組み合わせて使うと便利です。

curl -s https://api.servbay.demo/data | jq .

注意： jq は ServBay に標準では含まれていません。別途インストールする必要があります。macOS で Homebrew をお使いの場合は brew install jq で導入できます。-s オプションは静音（進行状況やエラー非表示）を意味し、レスポンスのみ jq に渡します。詳細は jq 公式サイト をご参照ください。

クッキーの取り扱い

cURL ではクッキーの保存・送信も容易で、セッション管理が必要な Web アプリのテストに役立ちます。

クッキーをファイルに保存

-c（または --cookie-jar）オプションで、サーバーから受け取ったクッキーを指定ファイルへ保存できます。

curl -c cookies.txt https://servbay.demo

クッキーファイルを利用

-b（または --cookie）オプションを使うと、保存済みクッキーを次のリクエストで利用できます。

curl -b cookies.txt https://servbay.demo/profile

プロキシの利用

プロキシサーバー経由でネットワークアクセスが必要な場合は、-x（--proxy）オプションでサーバーアドレスを指定します。

curl -x http://proxy.servbay.demo:8080 https://api.servbay.demo/data

転送帯域の制限

--limit-rate オプションを使うと、データ転送速度を制限できます（単位はバイト/秒、後ろに k, m, g を付けても可）。ネットワーク帯域試験や帯域消費制限時に便利です。

curl --limit-rate 100K https://servbay.demo/largefile.zip -O

レジューム（途中からのダウンロード再開）

大きなファイルをダウンロードする際、-C - オプションを用いると、部分ダウンロード済みファイルを認識し、続きから再取得できます。

curl -C - -O https://servbay.demo/largefile.zip

SSL 証明書の検証

cURL は標準で HTTPS の SSL 証明書を検証します。特定の CA 証明書ファイルを指定して検証したい場合は --cacert オプションを使います。

curl --cacert /path/to/custom_ca.crt https://secure.servbay.demo

ServBay で HTTPS サイトを構成し、ServBay 発行のルート証明書（ServBay User CA や ServBay Public CA）でサーバー証明書を作った場合は、ServBay の CA 証明書バンドルを指定してローカルの SSL 証明書検証が可能です。CA 証明書バンドルの正確な場所は ServBay の SSL/HTTPS ドキュメントを参照してください。通常は ServBay インストールディレクトリ下の etc/ssl に存在します。

警告： テスト用途等で --insecure（または -k）オプションを用いると、SSL 証明書検証エラーを無視します。本番環境や機密データを扱う用途では絶対に利用しないでください。 重要なセキュリティチェックが無効化されます。

curl --insecure https://secure.servbay.demo

よくある質問（FAQ）

1. ServBay ターミナルで curl コマンドが認識されない場合

• 原因：現在のターミナル環境で、ServBay の実行パスが正しく設定されていない可能性があります。
• 対処法：ServBay の環境変数設定を確認してください。問題が解消しない場合は、ServBay の「設定」-「コマンドラインツール」メニューから zsh・bash それぞれ設定を行い、ターミナルを再起動してください。

2. リクエスト時に接続エラーやタイムアウトが発生する場合

• 原因：対象サーバーが到達不可・ネットワーク障害・ファイアウォール遮断・URL の誤入力等が考えられます。
• 対処法：
  • 入力した URL が正しいか確認してください。
  • ネットワーク接続が正常か確認してください。
  • ローカルの ServBay サイト（servbay.demo 等）にアクセスしている場合は、ServBay が稼働中で、Web サーバー（Caddy/Nginx など）が起動しているかを確認。
  • cURL のアウトバウンド接続がファイアウォールやセキュリティソフトにより阻害されていないか確認。
  • HTTPS 接続の場合は SSL 証明書の有効性も確認（上記 SSL 証明書の検証を参照）。

3. ファイルのダウンロードやアップロードに失敗する場合

• 原因：ファイルパスの誤り・ファイル権限不足・サーバー側の対応未設定・サーバーエラー等が考えられます。
• 対処法：
  • コマンドで指定したファイルパスが正しく存在するかを確認。
  • ServBay 実行ユーザーや現在のターミナルユーザーが該当ファイルを読み書きできるか確認。
  • ローカル ServBay サイトへアップロードの場合は、サーバー側設定でアップロード許可や保存先ディレクトリの権限が適切かを確認。
  • cURL のエラーメッセージも参考にし、より具体的な原因を特定してください。

4. SSL 証明書エラーで検証に失敗する場合

• 原因：証明書の無効化・期限切れ・ドメイン不一致・証明書チェーン不完全・cURL が信頼できる CA 証明書を見つけられない、などが原因です。
• 対処法：
  • 対象サイトの証明書が有効かを確認してください。
  • ローカル ServBay サイトへのアクセスで ServBay 発行 CA を使用している場合は、本ドキュメントや ServBay の SSL 証明書ガイドに従って --cacert オプションで適切な CA 証明書バンドルを指定してください。
  • テストなど機密性の低い一時用途に限り --insecure オプションで認証を無視できます（本番では非推奨）。

まとめ

cURL は Web 開発者にとって欠かせない、強力かつ柔軟なコマンドラインツールです。ServBay の組み込み cURL を活用すれば、ローカル開発環境でのデータ転送やネットワークテストが簡単かつ効率的に行えます。シンプルな HTTP リクエストから、高度な API 操作やファイル管理まで——cURL の基本・応用を習得し、開発作業の生産性・トラブルシューティング能力を高めましょう。