curlでHTTPリクエストを完全に制御するDevOpsプラクティス

Mermaid
2025.09.26

DevOpsエンジニアとして、HTTPリクエストの完全に制御は日常業務において不可欠です。curlはその強力なツールであり、この記事ではその高度な利用法から、systemdと連携した運用、そしてトラブルシューティングまでを網羅します。特に、安全で冪等なスクリプトの書き方と権限管理に焦点を当てます。

curlでHTTPリクエストを完全に制御するDevOpsプラクティス

1. 要件と前提

このプラクティスでは、以下の要件を満たすHTTPリクエスト処理スクリプトを構築し、運用します。

  • 安全なスクリプト: set -euo pipefail、trap、一時ディレクトリの利用による冪等性と堅牢性の確保。
  • 高度なcurl利用: TLSクライアント認証、再試行メカニズム、JSONデータの送受信。
  • jqによるJSON処理: curlからのレスポンスを効率的に処理。
  • systemd連携: 定期実行のためのsystemd unitとtimerの導入。
  • 権限管理: root権限の適切な扱いと、最小権限の原則に基づく運用。

前提として、Linux環境（Ubuntu/CentOSなど）とcurl、jqがインストールされていることを想定します。また、APIエンドポイントとしてhttps://httpbin.org/を使用し、擬似的なTLS認証用の証明書ファイルパスを例示します。

2. 実装

HTTPリクエストを制御するためのシェルスクリプトを実装します。ここでは、JSONデータをPOSTし、レスポンスを処理する例を示します。

#!/usr/bin/env bash

# -----------------------------------------------------------------------------
# スクリプトの堅牢性と冪等性のための設定
# -----------------------------------------------------------------------------
set -euo pipefail

# 一時ディレクトリの作成と終了時のクリーンアップ
# これにより、スクリプトが冪等性を保ちやすくなる
TMP_DIR=$(mktemp -d)
trap 'rm -rf "$TMP_DIR"; echo "Temporary directory $TMP_DIR removed."' EXIT HUP INT QUIT TERM

echo "Using temporary directory: $TMP_DIR"

# -----------------------------------------------------------------------------
# 設定変数
# -----------------------------------------------------------------------------
API_ENDPOINT="https://httpbin.org/post"
# TLS設定 (例: クライアント証明書認証が必要な場合)
# 実際の環境ではこれらのファイルは厳重に管理し、適切なパーミッションを設定する
CLIENT_CERT="/etc/pki/client/client.pem" # クライアント証明書
CLIENT_KEY="/etc/pki/client/client.key"   # クライアント秘密鍵
CA_BUNDLE="/etc/pki/tls/certs/ca-bundle.crt" # サーバー証明書検証用CAバンドル

# curl 再試行設定
MAX_RETRIES=5          # 最大再試行回数
RETRY_DELAY_SEC=5      # 再試行間の待機秒数
MAX_RETRY_TIME_SEC=60  # 再試行を継続する最大時間

# 送信するJSONデータ
REQUEST_DATA=$(jq -n \
  --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --arg service "devops-agent" \
  --arg status "healthy" \
  '{timestamp: $timestamp, service: $service, status: $status}'
)

OUTPUT_FILE="$TMP_DIR/api_response.json"

# -----------------------------------------------------------------------------
# HTTPリクエスト処理フロー (Mermaid Graph)
# -----------------------------------------------------------------------------
echo "### HTTPリクエスト処理フロー"
cat << EOF
\`\`\`mermaid
graph TD
    A[スクリプト開始] --> B{一時ディレクトリ作成};
    B --> C{curlでHTTPリクエスト実行};
    C -- 成功 (HTTP 2xx) --> D{JSONレスポンス処理 (jq)};
    C -- 失敗 (HTTP 4xx/5xx, ネットワークエラー) --> E{再試行/エラーハンドリング};
    D --> F[結果ログ/保存];
    E --> G[エラーログ出力];
    F --> H[一時ディレクトリ削除];
    G --> H;
\`\`\`
EOF

# -----------------------------------------------------------------------------
# curl コマンド実行
# -----------------------------------------------------------------------------
echo "Sending POST request to $API_ENDPOINT with data: $REQUEST_DATA"

# curl の高度な利用例
# -sS: サイレントモード (-s) かつエラーを表示 (-S)
# -X POST: POSTメソッド
# -H "Content-Type: application/json": JSONデータを送ることを宣言
# --data-raw: RAWデータをそのまま送信 (ファイルから読み込む場合は --data @filename)
# --cert, --key, --cacert: TLSクライアント認証とサーバー証明書検証
# --retry, --retry-delay, --retry-max-time, --retry-all-errors: 再試行設定
# -o: レスポンスボディをファイルに保存
# -w "%{http_code}\n": HTTPステータスコードを標準出力に表示
HTTP_STATUS=$(curl -sS -X POST \
  -H "Content-Type: application/json" \
  --data-raw "$REQUEST_DATA" \
  --cert "$CLIENT_CERT" \
  --key "$CLIENT_KEY" \
  --cacert "$CA_BUNDLE" \
  --retry "$MAX_RETRIES" \
  --retry-delay "$RETRY_DELAY_SEC" \
  --retry-max-time "$MAX_RETRY_TIME_SEC" \
  --retry-all-errors \
  -o "$OUTPUT_FILE" \
  -w "%{http_code}\n" \
  "$API_ENDPOINT" || { echo "ERROR: curl command failed." >&2; exit 1; })

echo "HTTP Status: $HTTP_STATUS"

# HTTPステータスコードのチェック
if [[ "$HTTP_STATUS" -ge 200 && "$HTTP_STATUS" -lt 300 ]]; then
  echo "API request successful. Response saved to $OUTPUT_FILE"
  echo "Processing response with jq..."

  # jqでレスポンスJSONを処理
  # .json: httpbin.orgのレスポンスから、POSTされたJSONデータ部分を抽出
  # .args: クエリパラメータ部分 (今回は使用しないが例として)
  # .headers: リクエストヘッダー部分
  PROCESSED_DATA=$(jq -r '.json' "$OUTPUT_FILE" || { echo "ERROR: jq processing failed." >&2; exit 1; })

  if [[ -z "$PROCESSED_DATA" ]]; then
      echo "ERROR: jq extracted empty data." >&2
      exit 1
  fi

  echo "Extracted JSON data:"
  echo "$PROCESSED_DATA" | jq . # 整形して表示

  # ここで抽出したデータに対する追加の処理を行う

else
  echo "ERROR: API request failed with HTTP status $HTTP_STATUS." >&2
  echo "Response body:" >&2
  cat "$OUTPUT_FILE" >&2 # エラー時にはレスポンスボディも出力
  exit 1
fi

echo "Script finished successfully."

CLIENT_CERT, CLIENT_KEY, CA_BUNDLEに関する注意点: これらのファイルは機密情報であり、適切な権限設定（例: chmod 400）と、スクリプト実行ユーザーのみが読み取れるようにすることが必須です。rootでしかアクセスできない場所に配置する場合は、後述の権限分離を慎重に考慮する必要があります。

3. 検証

上記のスクリプトをapi_processor.shとして保存し、実行権限を与えます。

chmod +x api_processor.sh
./api_processor.sh

期待される出力:

Using temporary directory: /tmp/tmp.XXXXXX
### HTTPリクエスト処理フロー
```mermaid
graph TD
    A["スクリプト開始"] --> B{"一時ディレクトリ作成"};
    B --> C{"curlでHTTPリクエスト実行"};
    C -- 成功 (HTTP 2xx) --> D{"JSONレスポンス処理 (jq)"};
    C -- 失敗 (HTTP 4xx/5xx, ネットワークエラー) --> E{"再試行/エラーハンドリング"};
    D --> F["結果ログ/保存"];
    E --> G["エラーログ出力"];
    F --> H["一時ディレクトリ削除"];
    G --> H;

Sending POST request to https://httpbin.org/post with data: {“timestamp”:”2023-10-27T00:00:00Z”,”service”:”devops-agent”,”status”:”healthy”} HTTP Status: 200 API request successful. Response saved to /tmp/tmp.XXXXXX/api_response.json Processing response with jq… Extracted JSON data: { “timestamp”: “2023-10-27T00:00:00Z”, “service”: “devops-agent”, “status”: “healthy” } Script finished successfully. Temporary directory /tmp/tmp.XXXXXX removed.

(注: タイムスタンプは実行時に応じて変化します。)

もしTLS証明書関連のエラーが発生した場合、それは`httpbin.org`がクライアント証明書を要求しないためであり、テスト目的では`--cert`, `--key`, `--cacert`オプションを一時的にコメントアウトして動作を確認してください。

## 4. 運用

定期的なAPIリクエストが必要な場合、`systemd unit`と`timer`を使用して自動化します。

### 権限分離とroot権限の扱い

スクリプトは可能な限り**非rootユーザー**で実行すべきです。`systemd`の`User=`ディレクティブを使用することで、サービスを特定の非rootユーザーとして実行できます。これにより、スクリプトが誤動作してもシステム全体への影響を最小限に抑えられます。

*   **機密情報**: クライアント証明書やAPIキーは、スクリプトを実行するユーザーのみが読み取れるように厳しくファイルパーミッションを設定します。`root`ユーザーでしか配置できない場合は、スクリプトがそれらのファイルを安全に読み取れるように`systemd`の`User=`設定とSELinux/AppArmorポリシーを検討します。
*   **最小権限の原則**: スクリプトに与える権限は、その機能を実行するために必要最小限に留めます。

### systemd Unit の例

`/etc/systemd/system/api-processor.service`

```ini
[Unit]
Description=Periodically process API data
Documentation=https://example.com/docs/api-processor
After=network-online.target

[Service]
Type=simple
User=apiuser             # ★スクリプトを実行する非rootユーザーを指定
Group=apiuser            # ★スクリプトを実行するグループを指定
WorkingDirectory=/opt/api-processor # スクリプトの作業ディレクトリ
ExecStart=/opt/api-processor/api_processor.sh # スクリプトのパス
# スクリプトのログをjournalctlにリダイレクト
StandardOutput=journal
StandardError=journal
Restart=on-failure       # 失敗時に自動再起動
RestartSec=30s           # 再起動までの待機時間

[Install]
WantedBy=multi-user.target

systemd Timer の例

/etc/systemd/system/api-processor.timer

[Unit]
Description=Run API processor every 5 minutes

[Timer]
OnCalendar=*:0/5         # 5分ごとに実行 (例: 00:05, 00:10, ...)
Persistent=true          # タイマーが非アクティブな間に発生したイベントを追いつく

[Install]
WantedBy=timers.target

配置と有効化

  1. スクリプトを適切な場所に配置し、実行権限を与えます。 
    sudo mkdir -p /opt/api-processor
sudo cp api_processor.sh /opt/api-processor/
sudo chown apiuser:apiuser /opt/api-processor/api_processor.sh
sudo chmod 700 /opt/api-processor/api_processor.sh # 実行ユーザーのみ読み書き実行
# 証明書ファイルも同様に適切なパーミッションと所有者を設定
# sudo chown apiuser:apiuser /etc/pki/client/client.pem /etc/pki/client/client.key
# sudo chmod 400 /etc/pki/client/client.pem /etc/pki/client/client.key
    注意: apiuserユーザーが存在しない場合は作成してください。sudo useradd -r -s /bin/false apiuser
  2. systemd unitとtimerファイルを配置します。 
    sudo cp api-processor.service /etc/systemd/system/
sudo cp api-processor.timer /etc/systemd/system/
  3. systemdデーモンをリロードし、タイマーを有効化して起動します。 
    sudo systemctl daemon-reload
sudo systemctl enable api-processor.timer
sudo systemctl start api-processor.timer
  4. ステータスの確認 
    systemctl status api-processor.timer
systemctl status api-processor.service
    api-processor.timerがアクティブになり、次回の実行時刻が表示されていれば成功です。api-processor.serviceはタイマーによって起動されるまでinactiveであるべきです。
  5. ログの確認 
    journalctl -u api-processor.service -f
    これにより、スクリプトの標準出力と標準エラーがjournaldに記録されていることを確認できます。

5. トラブルシュート

  • curlエラー:
    • 詳細なログ: curl -v を追加して詳細な通信ログを確認します。TLSハンドシェイク、リクエストヘッダー、レスポンスヘッダーなど、多くの情報が得られます。
    • ネットワーク: pingやtracerouteでAPIエンドポイントへの接続性を確認します。プロキシ設定が必要な場合はhttp_proxy/https_proxy環境変数を設定するか、curl -xオプションを使用します。
    • TLSエラー: curl: (60) Peer's Certificate issuer is not recognized など。--cacertのパスが正しいか、CAバンドルが最新かを確認します。クライアント証明書認証の場合、--cert/--keyのパスとパーミッションを確認します。
  • jqエラー:
    • JSON形式: jqがエラーを出す場合、curlからのレスポンスが有効なJSON形式でない可能性があります。cat $OUTPUT_FILEで生データを表示し、形式を確認します。
  • systemdエラー:
    • サービスステータス: systemctl status api-processor.service でエラーメッセージを確認します。
    • ログ: journalctl -u api-processor.service --since "1 hour ago" などで、サービス起動時の詳細なログを確認します。ExecStartパスの誤り、権限不足、環境変数の設定ミスなどがよくある原因です。
    • ユーザー権限: User=で指定したユーザーが、スクリプトや関連ファイル（証明書など）にアクセスできるか確認します。
  • 冪等性の問題:
    • スクリプトを複数回実行しても、外部の状態が期待通りに変化しない（または変化しすぎない）かを確認します。一時ファイルが正しくクリーンアップされているか、APIへのリクエストが重複しても問題ない設計になっているかなどを考慮します。

6. まとめ

この記事では、curlを用いたHTTPリクエストの完全な制御について、DevOpsエンジニアが実践すべきプラクティスを網羅的に解説しました。

  • set -euo pipefail、trap、一時ディレクトリを組み合わせることで、安全で冪等なシェルスクリプトの基盤を築きました。
  • curlの--cert, --key, --cacertによるTLSクライアント認証、--retryオプション群による堅牢な再試行メカニズムを組み込み、不安定なネットワークやAPIへの対応力を高めました。
  • jqを活用し、JSONレスポンスを効率的に処理する方法を示しました。
  • systemd unitとtimerを用いることで、スクリプトの定期的な自動実行と監視を実装し、運用上の負担を軽減しました。
  • root権限の扱いと権限分離の重要性を強調し、User=ディレクティブを通じてセキュリティを強化するアプローチを提示しました。

これらのプラクティスは、複雑なAPI連携や外部システムとの統合において、DevOpsチームが信頼性、安全性、効率性を確保するための強力な基盤となるでしょう。HTTPリクエストの挙動を完全に制御し、システム運用における課題を解決するために、ぜひこれらの技術を活用してください。

ライセンス：本記事のテキスト/コードは特記なき限り CC BY 4.0 です。引用の際は出典URL（本ページ）を明記してください。
利用ポリシー もご参照ください。

コメント

タイトルとURLをコピーしました