本記事はGeminiの出力をプロンプト工学で整理した業務ドラフト（未検証）です。
curlとjqを用いた堅牢なREST API監視自動化とエラーハンドリング
【導入と前提】 APIの応答ステータスとJSON内部値を検証し、異常検知時に自己修復や通知へ繋げる堅牢なシェルスクリプト運用を自動化します。
OS: Ubuntu 22.04 LTS / RHEL 9 (POSIX準拠シェル)
ツール: curl 7.76+, jq 1.6+
【処理フローと設計】
graph TD
A["開始"] --> B["curlでAPI実行"]
B --> C{"HTTPステータス確認"}
C -->|200以外| D["リトライ/異常終了"]
C -->|200 OK| E["jqによるペイロード検証"]
E --> F{"特定フィールドの期待値比較"}
F -->|不一致| G["警告ログ出力"]
F -->|一致| H["正常終了"]
API呼び出しにおける一時的なネットワーク瞬断をcurlのリトライ機能で吸収し、jqの終了ステータスを利用してデータ整合性を保証する設計をとります。
【実装：堅牢な自動化スクリプト】
#!/bin/bash
# ==============================================================================
# API Health Check & Validation Script
# ==============================================================================
set -euo pipefail
IFS=$'\n\t'
# 1. 環境変数・定数の定義
API_URL="https://api.example.com/v1/health"
EXPECTED_STATUS="UP"
TMP_FILE=$(mktemp)
# 2. 終了時のクリーンアップ処理
trap 'rm -f "$TMP_FILE"' EXIT
echo "Starting API validation for: $API_URL"
# 3. リトライ機能付きcurl実行
# -s: 進捗表示を抑制 / -S: エラー時は表示 / -L: リダイレクト追従
# --retry: 失敗時の試行回数 / --retry-delay: 間隔(秒) / -w: HTTPコード抽出
HTTP_CODE=$(curl -s -S -L \
--retry 3 \
--retry-delay 2 \
--max-time 10 \
-o "$TMP_FILE" \
-w "%{http_code}" \
"$API_URL")
# 4. HTTPステータスコードの検証
if [ "$HTTP_CODE" -ne 200 ]; then
echo "Error: API returned status $HTTP_CODE" >&2
exit 1
fi
# 5. jqを用いたペイロード（JSON）の検証
# -e: 結果がnullまたはfalseの場合に終了コード1を返す
if ! jq -e ".status == \"$EXPECTED_STATUS\"" "$TMP_FILE" > /dev/null; then
echo "Error: Unexpected API response content." >&2
cat "$TMP_FILE" >&2
exit 1
fi
echo "Success: API is healthy and payload is valid."
systemdによる定時実行の構成例
/etc/systemd/system/api-check.timer
[Unit] Description=Run API Health Check every 5 minutes [Timer] OnCalendar=*:0/5 Persistent=true [Install] WantedBy=timers.target
【検証と運用】
正常系の確認: スクリプトを手動実行し、
echo $?が0であることを確認。journalctl -u api-check.serviceで過去の実行ログを閲覧可能。異常系のシミュレーション: URLを存在しないドメインに書き換え、リトライ処理が走り最終的に非ゼロで終了することを確認。
【トラブルシューティングと落とし穴】
PIPESTATUSの考慮:
pipefailを有効にしているため、パイプ途中のエラーは即座にトラップされますが、複雑なパイプラインでは${PIPESTATUS[@]}で各段階の成否をデバッグする必要があります。権限問題:
mktempで作成されるファイルのパーミッションに注意。特にsystemdで実行する場合、実行ユーザーが/tmpへの書き込み権限を持っているか確認してください。秘密情報の漏洩: APIキーをコマンドライン引数に渡すと
psコマンドで露出するため、環境変数または読み取り専用のコンフィグファイルから取得することを推奨します。
【まとめ】 運用の冪等性を維持するための3つのポイント：
ステータスとコンテンツの両面検証: HTTP 200であっても中身がエラーメッセージであるケースを
jq -eで防ぐ。一時ファイルの確実な破棄:
trap命令により、スクリプトが途中で強制終了されてもゴミを残さない。指数バックオフリトライ: 一時的な負荷上昇時に、過剰な再試行でAPIサーバーに追い打ちをかけない設定を行う。
