REST API監視の自動化：curlとjqによる堅牢なレスポンス検証の実装

Tech

{ “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

【トラブルシューティングと落とし穴】

  1. 環境変数の漏洩防止: APIキーやトークンが必要な場合、スクリプト内にハードコードせず、systemd の EnvironmentFile= を使用してパーミッションを制限したファイルから読み込んでください。

  2. jqのバージョン差異: jq -e オプションは古いバージョンでは動作が異なる場合があります。jq --version で 1.5 以上であることを確認してください。

  3. 巨大なJSONレスポンス: メモリ消費を抑えるため、jq で処理する前に curl の --max-filesize オプションで取得サイズを制限することを推奨します。

  4. 一時ファイルの削除: trap コマンドを使用することで、スクリプトが途中で強制終了された場合でも /tmp 下の残骸を確実に削除します。

【まとめ】

運用の冪等性と堅牢性を維持するための3つのポイント：

  1. パイプラインの保護: set -o pipefail により、curl の失敗を jq が隠蔽するのを防ぐ。

  2. リトライ戦略の実装: curl --retry を活用し、瞬間的なネットワークの揺らぎによる誤検知を最小化する。

  3. 論理検証の自動化: HTTP 200 だけを信じず、jq でアプリケーションレベルのステータス（例：{"status": "UP"}）まで検証する。

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

コメント

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