技術資料

REST APIを使うとき、いきなりアプリケーションへ組み込むより、まずはリクエストだけを送って確認したいことがあります。URLや送信データが違うのか、PHPなどの実装に問題があるのかを分けて調べたいときにも便利です。

今回は、WindowsのPowerShellからコマンドライン版curlを使い、GETとJSON POSTを試してみます。レスポンスの本文だけでなく、HTTPステータスとcurlの終了コードも確認します。

PowerShellから使うcurlを確認する

curlは、URLを指定してデータを送受信するコマンドラインツールです。PHPのcURL拡張とは別に実行するプログラムなので、PHPのコードを書かずにHTTPリクエストを送れます。

PowerShellでは、コマンドの別名と外部プログラムを区別します。例えばWindows PowerShell 5.1では、curlがInvoke-WebRequestの別名になっています。この記事では、外部プログラムを呼び出すことが分かるようにcurl.exeと書きます。

$PSVersionTable.PSVersion
Get-Command curl -All
Get-Command curl.exe
curl.exe --version

今回確認した環境は、WindowsのOSビルド10.0.26300、PowerShell 7.6.9、curl 8.21.0です。curlのTLSバックエンドはSchannelでした。

以下で使う--jsonはcurl 7.82.0以降のオプションです。古いcurlでは使えないため、手元のバージョンも確認してください。

GETでAPIへリクエストを送る

ここからは、商品を扱う説明用APIを例にします。以下のサンプルコード内のhttps://api.example.comは実行可能なサンプルAPIではありません。接続先、パス、パラメーターは、利用するAPIの仕様へ置き換えてください。

POSTはデータを登録する場合があるので、まずは自分で操作してよいテスト環境を使いましょう。後ほどファイルも保存するため、空の作業用フォルダーで試してください。

$baseUrl = 'https://api.example.com'

例えば、商品の一覧を取得するGET /productsなら、次の形です。

curl.exe --silent --show-error --connect-timeout 5 --max-time 15 "$baseUrl/products"

データ送信用のオプションなどを付けなければ、HTTPでは基本的にGETになります。返された本文は画面へ出力されますが、curlが自動でJSONを整形するわけではありません。

進捗だけ消したつもりでエラーまで見えなくならないよう、ここでは--silentと--show-errorをセットで指定しています。

クエリパラメーターとヘッダーを付ける

検索語や件数を指定する例です。--getと--data-urlencodeを組み合わせると、値をURLエンコードしてクエリへ追加できます。

curl.exe --silent --show-error `
    --connect-timeout 5 --max-time 15 `
    --get `
    --data-urlencode 'q=入門 PHP' `
    --data-urlencode 'limit=2' `
    --header 'Accept: application/json' `
    "$baseUrl/products"

この例では、qに「入門 PHP」、limitに「2」を渡します。--getを外すと、このデータ指定はPOSTになるので注意してください。Acceptは、レスポンスとしてJSONを受け取りたいという指定です。実際の応答はAPIの仕様によります。

PowerShellでコマンドを複数行に分けるときは、上の例のように行末へバッククォート`を置けます。バッククォートの後ろに空白を入れると、行の継続になりません。実行できないときは、いったん1行に戻してみると切り分けやすいです。

本文・ヘッダー・HTTPステータスを分けて確認する

本文だけでは、成功したのか、APIのエラーメッセージなのか判断しにくい場合があります。本文とレスポンスヘッダーを別ファイルへ保存し、画面にはHTTPステータスを表示してみます。

curl.exe --silent --show-error `
    --connect-timeout 5 --max-time 15 `
    --dump-header '.\response-headers.txt' `
    --output '.\response.json' `
    --write-out 'HTTP=%{http_code}\n' `
    "$baseUrl/products"
$curlExitCode = $LASTEXITCODE
"curl exit=$curlExitCode"

--dump-headerは受信ヘッダー、--outputは本文の保存先です。--write-outは転送後に情報を出力する指定で、%{http_code}がHTTPステータス、\nが改行になります。

$LASTEXITCODEには最後に実行した外部プログラムの終了コードが入ります。別のプログラムを動かす前に、curlの実行直後で保存します。

Get-Content -LiteralPath '.\response-headers.txt'
Get-Content -LiteralPath '.\response.json' -Raw -Encoding utf8

ここではJSONの応答を想定したファイル名にしていますが、保存しただけでは内容がJSONかどうかは検証されません。通信に失敗した場合は、保存ファイルが今回の完全な応答とは限らないので、先に終了コードを確認してください。同名の保存ファイルは上書きされます。

JSONファイルをPOSTする

JSONをコマンドへ直接書くと、JSONのダブルクォートとシェルの引用符が重なります。まずはファイルへ保存して送る方が、送信内容を確認しやすいかと思います。

例えば、nameとpriceを受け取るAPIなら、次のようにJSONを作れます。PowerShell 7系で、BOMなしのUTF-8として保存します。

$requestBody = @{
    name = 'テスト商品'
    price = 1200
}
$requestBody | ConvertTo-Json | Set-Content -LiteralPath '.\request.json' -Encoding utf8NoBOM

このファイルを、商品登録のPOST /productsへ送ります。

curl.exe --silent --show-error `
    --connect-timeout 5 --max-time 15 `
    --json '@request.json' `
    --output '.\post-response.json' `
    --write-out 'HTTP=%{http_code}\n' `
    "$baseUrl/products"
$curlExitCode = $LASTEXITCODE
"curl exit=$curlExitCode"
Get-Content -LiteralPath '.\post-response.json' -Raw -Encoding utf8

@request.jsonの@は、curlへファイルから読み込むよう指示する記号です。PowerShell側の解釈と混ざらないよう、引数全体を引用符で囲んでいます。空白を含むパスでも、'@.\request files\request.json'のように全体を囲みます。

--jsonは、ファイルなどのデータをPOSTし、Content-Type: application/jsonとAccept: application/jsonを指定するためのオプションです。この例では-X POSTを追加する必要はありません。ただし、JSON構文の検証は行わないので、ファイルを手で編集した場合などは内容も確認してください。

Content-Typeは送る本文の形式、Acceptは受け取りたい形式です。名前は似た場面で登場しますが、役割は別です。

Bearerトークンを付ける場合

Bearer認証を使うAPIでは、Authorizationヘッダーを追加します。次の例は、利用するAPIのテスト用トークンが環境変数API_TOKENへ設定されている前提です。

if ([string]::IsNullOrWhiteSpace($env:API_TOKEN)) {
    throw 'API_TOKENが設定されていません。'
}
curl.exe --silent --show-error `
    --connect-timeout 5 --max-time 15 `
    --header "Authorization: Bearer $env:API_TOKEN" `
    --json '@request.json' `
    "$baseUrl/products"

実トークンをコマンドへ直接書くと、履歴に残る可能性があります。ただ、環境変数を使っても、展開された値がプロセスの引数へ渡る点は変わりません。共有端末での扱いや、詳細ログ・画面・レスポンスを共有するときの漏えいにも注意してください。今回の検証ではダミー文字列だけを送っています。

HTTPエラーとcurlの失敗を分ける

HTTP 404や500が返っても、通常のcurlは終了コード0になることがあります。サーバーから応答を受け取れたことと、APIの処理が成功したことは別だからです。

HTTP 400以上をcurlの失敗としても扱い、エラー本文を残したい場合は、--fail-with-bodyを付けます。例えば、存在しない商品へアクセスして404を返すAPIなら、次のように確認できます。

curl.exe --silent --show-error `
    --connect-timeout 5 --max-time 15 `
    --fail-with-body `
    --output '.\error-response.json' `
    --write-out 'HTTP=%{http_code}\n' `
    "$baseUrl/products/999999"
$curlExitCode = $LASTEXITCODE
"curl exit=$curlExitCode"

ローカルのテスト用APIで404を返した場合、画面にはHTTPステータス404と終了コード22が表示され、本文はerror-response.jsonへ保存されました。curlのエラーメッセージは標準エラーへ出ます。

--failでもHTTPエラーを失敗扱いにできますが、エラー本文の出力は抑えられます。APIが返した理由を調べたい場合は、本文を残す--fail-with-bodyが便利です。こちらはcurl 7.76.0以降で使えます。

表の000はサーバーが返したHTTPステータスではなく、HTTP応答コードを取得できなかった場合の表示です。また、curlの終了コード0でも、API独自の成功条件は本文や仕様を見て判断します。

タイムアウトも同じように、実行直後の終了コードで確認できます。

curl.exe --silent --show-error `
    --connect-timeout 1 --max-time 1 `
    --output '.\timeout-response.txt' `
    --write-out 'HTTP=%{http_code}\n' `
    "$baseUrl/products"
$curlExitCode = $LASTEXITCODE
"curl exit=$curlExitCode"

このコマンドが必ずタイムアウトするわけではありません。検証では、ローカルサーバーが応答を返す前に2秒待つようにして、終了コード28を確認しました。特にPOSTのタイムアウトでは、サーバー側の登録処理は完了している場合もあるので、結果を確認せず繰り返し送らないようにしましょう。

接続できない場合は、URL、ネットワーク、プロキシ、証明書などをエラーメッセージから切り分けます。HTTPSの証明書エラーを消すために--insecure（-k）を付けるのは避け、原因を確認します。

なお、CLI版curlで成功しても、PHPのcURLが同じTLSバックエンドやCAを使っているとは限りません。PHP側の証明書エラーは、証明書検証とCAバンドルの設定を扱う記事も参考にしてください。

補足：Bashの例をPowerShellへ持ってくるとき

Bashで同じJSONファイルを送るなら、例えば次の形です。これはBash用の記法で、今回の実行検証の対象はPowerShell側です。

curl --silent --show-error \
    --connect-timeout 5 --max-time 15 \
    --json '@request.json' \
    'https://api.example.com/products'

Bashの行末の\を、そのままPowerShellの行継続には使えません。PowerShellではバッククォートを使うか、コマンドを1行にまとめます。変数の書き方や引用符の扱いも同一ではないため、Web上の例は「どのシェルで実行するものか」を確認しましょう。

今回のPowerShellの例は、URLをローカルのテスト用APIへ差し替えて確認しました。日本語を含むクエリ、JSONの内容、ヘッダーの受信と、表にあるHTTPエラー・タイムアウトを検証しています。実サービスの認証、HTTPS接続、プロキシ環境での動作は今回の検証には含めていません。

まずはGETで疎通を確認し、送信内容を増やしていくと、APIとのやり取りを追いやすくなります。リクエスト単体で確認できたら、PHPのcURLによる外部API連携など、アプリケーション側の実装へ進めばOKです。

参考資料

• curl公式マニュアル：オプションと終了コード
• Microsoft Learn：PowerShellの引数解析と行継続
• Microsoft Learn：LASTEXITCODEなどの自動変数
• Microsoft Learn：PowerShellの文字エンコーディング