PowerShellの Invoke-WebRequest や Invoke-RestMethod を使ってREST APIへアクセスすると、時々思い通りに動かないケースがあります。
同じURLをブラウザやcurlでは叩けるのに、PowerShellだけエラーというケースもよくあります。
この記事では、APIリクエストが失敗する典型原因と解決策をまとめました。初めてAPI連携に挑戦する方にも、トラブルシューティングの指針になる内容です。
🧭 この記事の対象読者
-
PowerShell で REST API を扱い始めた人
-
API 呼び出しが失敗し原因不明で困っている人
-
Invoke-WebRequestとInvoke-RestMethodの挙動差を理解したい人 -
社内ネットワーク・プロキシ環境で通信している人
🔍 よくある失敗パターンと原因一覧
| 原因カテゴリ | 具体例 | 典型エラー例 |
|---|---|---|
| 認証・ヘッダー不備 | APIキー、Bearer Token不足、Content-Type不一致 | 400 Bad Request / 401 Unauthorized |
| SSL・TLS問題 | 古いTLS設定、証明書検証失敗 | The request was aborted: Could not create SSL/TLS secure channel |
| プロキシ設定・ネットワーク制約 | 社内Proxy、Firewall、VPN制限 | タイムアウト / 接続拒否 |
| JSON送信形式ミス | Strings で送信してしまう、不正データ | 415 Unsupported Media Type |
| PowerShellのバージョン差異 | Windows PowerShell vs PowerShell 7 の挙動差 | Invoke-WebRequest 処理結果が違う |
1. 🔐 認証情報・ヘッダー不足
REST APIの多くは認証ヘッダー必須です。特に以下が抜けると失敗します。
-
Authorization: Bearer XXXXX -
Content-Type: application/json -
独自APIキー (
x-api-key,Ocp-Apim-Subscription-Keyなど)
✔ 正しい例
2. 🔒 TLS/SSL の問題
古いPowerShell（Windows PowerShell 5.1）ではTLS1.0/1.1がデフォルトで使われる場合があり、現代のREST API（AWS/Azure/GCPなど）はTLS1.2以上を要求します。
✔ 解決策（最初に書くやつ）
PowerShell 7 では不要ですが、Windows PowerShell ではほぼ必須です。
3. 🏢 プロキシ環境や Firewall の影響
企業ネットワークやVPN環境では、Proxy越しの通信制御がかかっている場合があります。
✔ Proxy指定例
PowerShell 7では、既定でOS設定のProxyを引き継ぎますが、Windows PowerShell では手動設定が必要な場合があります。
4. 📦 JSON Body の形式ミス
-Body に文字列を渡す際、単なる "{"key":"value"}" では認識されないケースがあります。
❌ よくある間違い
✔ 正しい例
5. 🧪 Invoke-WebRequest / Invoke-RestMethod の挙動差
同じREST APIでも、使うコマンドで結果が異なることがあります。
| 項目 | Invoke-WebRequest | Invoke-RestMethod |
|---|---|---|
| 戻り値 | 生HTML・JSON文字列そのまま | JSONなら自動でオブジェクト化 |
| 効果的な用途 | Webスクレイピング、ファイルDL | REST API通信向け |
PowerShellでREST APIを使うなら、基本は**Invoke-RestMethod が推奨**です。
🔧 トラブルシューティングチェックリスト
| チェック項目 | 確認 |
|---|---|
| APIキー・Bearer Token は正しいか | ✔ |
| Content-Type が API仕様に一致しているか | ✔ |
| TLS1.2以上が有効か | ✔ |
| JSONを正しく整形し ConvertTo-Json を使っているか | ✔ |
| Proxy設定やFirewallでブロックされていないか | ✔ |
| PowerShell 7 で再現するか（互換性確認） | ✔ |
まとめ
PowerShellでREST APIが失敗する原因は、認証・TLS・JSON形式・ネットワーク環境のいずれかに分類できることがほとんどです。
特に企業ネットワークや古いPowerShell環境では、TLS設定やProxy設定が原因で失敗しやすい傾向があります。
エラー内容だけ見ても解決できない場合は、まずこの記事のチェックリストを基準に原因を切り分けてみてください。