{ “version”: “1.1”, “persona”: “SRE/DevOps Engineer”, “strategy”: “RESEARCH-FIRST, PLAN-DRIVEN”, “tools”: [“curl”, “jq”, “systemd”, “bash”], “focus”: “Robust API Validation & Error Handling” }
本記事はGeminiの出力をプロンプト工学で整理した業務ドラフト（未検証）です。
REST API監視の自動化：curlとjqによる堅牢なレスポンス検証の実装
【導入と前提】
REST APIのヘルスチェックとレスポンスの整合性検証を自動化し、SLA監視の信頼性を向上させます。
前提：Linux環境（Bash 4.4+）、curl、jqがインストールされていること。
【処理フローと設計】
graph TD
A["開始"] --> B["curlでAPIリクエスト実行"]
B --> C{"HTTPステータス確認"}
C -->|非200| D["エラーログ記録と終了"]
C -->|200 OK| E["jqによるペイロード検証"]
E --> F{"期待する値が含まれるか"}
F -->|No| G["検証失敗アラート"]
F -->|Yes| H["成功ログ記録"]
H --> I["終了"]
このフローでは、ネットワーク層（curl）とアプリケーション層（jq）の二段構えで検証を行います。単なる死活監視ではなく、期待したデータ構造が返却されているかを保証します。
【実装：堅牢な自動化スクリプト】
#!/bin/bash
# ==============================================================================
# API Health Check & Validation Script
# ==============================================================================
# 厳格なエラーハンドリング設定
# -e: エラー発生時に即座に終了
# -u: 未定義変数の参照でエラー
# -o pipefail: パイプライン途中のエラーを伝播
set -euo pipefail
# 設定
API_URL="https://api.example.com/v1/health"
EXPECTED_STATUS="UP"
LOG_TAG="api-monitor"
# 一時ファイルの管理
TMP_RESPONSE=$(mktemp)
trap 'rm -f "$TMP_RESPONSE"' EXIT
echo "Starting API validation for $API_URL"
# 1. APIリクエストの実行
# -s: サイレントモード
# -S: エラー時はエラーメッセージを表示
# -L: リダイレクトを追跡
# --retry: 一時的なネットワークエラー時に3回リトライ
# -w: HTTPステータスコードのみを取得
HTTP_CODE=$(curl -sSL --retry 3 \
-o "$TMP_RESPONSE" \
-w "%{http_code}" \
"$API_URL")
# 2. HTTPステータスコードの検証
if [ "$HTTP_CODE" -ne 200 ]; then
logger -t "$LOG_TAG" -p user.err "CRITICAL: API returned HTTP $HTTP_CODE"
exit 1
fi
# 3. jqによるJSONペイロードの深層検証
# -e: フィルタの結果がfalseまたはnullの場合、終了コード1を返す
if ! jq -e ".status == \"$EXPECTED_STATUS\"" "$TMP_RESPONSE" > /dev/null; then
ACTUAL_STATUS=$(jq -r '.status // "unknown"' "$TMP_RESPONSE")
logger -t "$LOG_TAG" -p user.warn "WARNING: Invalid payload status. Expected: $EXPECTED_STATUS, Got: $ACTUAL_STATUS"
exit 1
fi
logger -t "$LOG_TAG" -p user.info "SUCCESS: API validation passed."
exit 0
定期実行を行う場合は、以下の systemd ユニットファイルを作成し、信頼性を高めます。
# /etc/systemd/system/api-monitor.service [Unit] Description=API Integrity Monitor [Service] Type=oneshot ExecStart=/usr/local/bin/api-check.sh User=monitor-user # /etc/systemd/system/api-monitor.timer [Unit] Description=Run API Integrity Monitor every 5 minutes [Timer] OnCalendar=*:0/5 Persistent=true [Install] WantedBy=timers.target
【検証と運用】
正常系の確認コマンド：
# スクリプトを直接実行し、終了コードを確認 ./api-check.sh && echo "OK" || echo "FAILED"
エラー時のログ確認方法：
systemd 経由で実行している場合、標準出力および logger の内容はジャーナルに集約されます。
# 過去1時間分のエラーログを抽出 journalctl -u api-monitor.service --since "1 hour ago" -p err
【トラブルシューティングと落とし穴】
環境変数の漏洩防止: APIキーやトークンが必要な場合、スクリプト内にハードコードせず、
systemdのEnvironmentFile=を使用してパーミッションを制限したファイルから読み込んでください。jqのバージョン差異:
jq -eオプションは古いバージョンでは動作が異なる場合があります。jq --versionで 1.5 以上であることを確認してください。巨大なJSONレスポンス: メモリ消費を抑えるため、
jqで処理する前にcurlの--max-filesizeオプションで取得サイズを制限することを推奨します。一時ファイルの削除:
trapコマンドを使用することで、スクリプトが途中で強制終了された場合でも/tmp下の残骸を確実に削除します。
【まとめ】
運用の冪等性と堅牢性を維持するための3つのポイント：
パイプラインの保護:
set -o pipefailにより、curlの失敗をjqが隠蔽するのを防ぐ。リトライ戦略の実装:
curl --retryを活用し、瞬間的なネットワークの揺らぎによる誤検知を最小化する。論理検証の自動化: HTTP 200 だけを信じず、
jqでアプリケーションレベルのステータス（例：{"status": "UP"}）まで検証する。
