<p><sre_hardening_v1.0></sre_hardening_v1.0></p> <p>本記事は<strong>Geminiの出力をプロンプト工学で整理した業務ドラフト（未検証）</strong>です。</p> <h1 class="wp-block-heading">curlとjqを用いた堅牢なREST API監視自動化とエラーハンドリング</h1> <p>【導入と前提】 APIの応答ステータスとJSON内部値を検証し、異常検知時に自己修復や通知へ繋げる堅牢なシェルスクリプト運用を自動化します。</p> <ul class="wp-block-list"> <li><p>OS: Ubuntu 22.04 LTS / RHEL 9 (POSIX準拠シェル)</p></li> <li><p>ツール: curl 7.76+, jq 1.6+</p></li> </ul> <p>【処理フローと設計】</p> <div class="wp-block-merpress-mermaidjs diagram-source-mermaid"><pre class="mermaid"> graph TD A["開始"] --> B["curlでAPI実行"] B --> C{"HTTPステータス確認"} C -->|200以外| D["リトライ/異常終了"] C -->|200 OK| E["jqによるペイロード検証"] E --> F{"特定フィールドの期待値比較"} F -->|不一致| G["警告ログ出力"] F -->|一致| H["正常終了"] </pre></div> <p>API呼び出しにおける一時的なネットワーク瞬断を<code>curl</code>のリトライ機能で吸収し、<code>jq</code>の終了ステータスを利用してデータ整合性を保証する設計をとります。</p> <p>【実装：堅牢な自動化スクリプト】</p> <div class="codehilite"> <pre data-enlighter-language="generic">#!/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." </pre> </div> <h3 class="wp-block-heading">systemdによる定時実行の構成例</h3> <p><code>/etc/systemd/system/api-check.timer</code></p> <div class="codehilite"> <pre data-enlighter-language="generic">[Unit] Description=Run API Health Check every 5 minutes [Timer] OnCalendar=*:0/5 Persistent=true [Install] WantedBy=timers.target </pre> </div> <p>【検証と運用】</p> <ol class="wp-block-list"> <li><p><strong>正常系の確認</strong>: スクリプトを手動実行し、<code>echo $?</code> が <code>0</code> であることを確認。 <code>journalctl -u api-check.service</code> で過去の実行ログを閲覧可能。</p></li> <li><p><strong>異常系のシミュレーション</strong>: URLを存在しないドメインに書き換え、リトライ処理が走り最終的に非ゼロで終了することを確認。</p></li> </ol> <p>【トラブルシューティングと落とし穴】</p> <ul class="wp-block-list"> <li><p><strong>PIPESTATUSの考慮</strong>: <code>pipefail</code>を有効にしているため、パイプ途中のエラーは即座にトラップされますが、複雑なパイプラインでは <code>${PIPESTATUS[@]}</code> で各段階の成否をデバッグする必要があります。</p></li> <li><p><strong>権限問題</strong>: <code>mktemp</code> で作成されるファイルのパーミッションに注意。特に <code>systemd</code> で実行する場合、実行ユーザーが <code>/tmp</code> への書き込み権限を持っているか確認してください。</p></li> <li><p><strong>秘密情報の漏洩</strong>: APIキーをコマンドライン引数に渡すと <code>ps</code> コマンドで露出するため、環境変数または読み取り専用のコンフィグファイルから取得することを推奨します。</p></li> </ul> <p>【まとめ】 運用の冪等性を維持するための3つのポイント：</p> <ol class="wp-block-list"> <li><p><strong>ステータスとコンテンツの両面検証</strong>: HTTP 200であっても中身がエラーメッセージであるケースを<code>jq -e</code>で防ぐ。</p></li> <li><p><strong>一時ファイルの確実な破棄</strong>: <code>trap</code>命令により、スクリプトが途中で強制終了されてもゴミを残さない。</p></li> <li><p><strong>指数バックオフリトライ</strong>: 一時的な負荷上昇時に、過剰な再試行でAPIサーバーに追い打ちをかけない設定を行う。</p></li> </ol>

graph TD
A["開始"] --> B["curlでAPI実行"]
B --> C{"HTTPステータス確認"}
C -->|200以外| D["リトライ/異常終了"]
C -->|200 OK| E["jqによるペイロード検証"]
E --> F{"特定フィールドの期待値比較"}
F -->|不一致| G["警告ログ出力"]
F -->|一致| H["正常終了"]

#!/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."

[Unit]
Description=Run API Health Check every 5 minutes

[Timer]
OnCalendar=*:0/5
Persistent=true

[Install]
WantedBy=timers.target