<p><style_prompt></style_prompt></p> <ul class="wp-block-list"> <li><p>語り口: プロフェッショナルかつ簡潔なエンジニア向け技術ドキュメント</p></li> <li><p>表記: 専門用語は正確に、説明は最小限で意図を伝える</p></li> <li><p>構成: 指示されたセクション順守、論理的フローの重視</p></li> <li><p>視覚的工夫: コードブロック、Mermaid、箇条書きの活用</p></li> <li><p>価値提供: 現場で即利用可能な「ベストプラクティス」を提示 </p></li> </ul> <p>本記事は<strong>Geminiの出力をプロンプト工学で整理した業務ドラフト（未検証）</strong>です。</p> <h1 class="wp-block-heading">ShellスクリプトによるREST APIレスポンス検証の堅牢化と自動化</h1> <h2 class="wp-block-heading">【導入と前提】</h2> <p>APIヘルスチェックやデータ抽出を自動化し、異常検知時に確実な終了ステータスを返す堅牢な運用フローを構築します。</p> <ul class="wp-block-list"> <li><p><strong>実行環境</strong>: GNU/Linux (bash 4.0+), curl, jq 1.6+</p></li> <li><p><strong>前提条件</strong>: APIエンドポイントへの疎通権限、およびjqのインストール</p></li> </ul> <h2 class="wp-block-heading">【処理フローと設計】</h2> <div class="wp-block-merpress-mermaidjs diagram-source-mermaid"><pre class="mermaid"> graph TD A[Start] --> B["curl: API Request"] B --> C{"HTTP Status 200?"} C -- No --> D["Error Exit / Retry"] C -- Yes --> E["jq: Parse & Validate JSON"] E --> F{"Target Value Exists?"} F -- No --> G["Validation Error"] F -- Yes --> H["Process Success / Output"] H --> I[End] </pre></div> <p>APIリクエスト、HTTPステータス確認、JSON構造バリデーションの3段階でフィルタリングを行い、後続処理に不正なデータを渡さない「Fail-fast」設計を採用します。</p> <h2 class="wp-block-heading">【実装：堅牢な自動化スクリプト】</h2> <h3 class="wp-block-heading">1. 堅牢なバリデーションスクリプト (<code>api_check.sh</code>)</h3> <div class="codehilite"> <pre data-enlighter-language="generic">#!/usr/bin/env bash # --- 安全設定 --- set -euo pipefail # エラーで停止、未定義変数禁止、パイプ内のエラー捕捉 IFS=$'\n\t' # スペースを含むファイル名の誤動作防止 # --- 定数 --- readonly API_URL="https://api.example.com/v1/health" readonly TEMP_FILE=$(mktemp /tmp/api_res.XXXXXX) # --- クリーンアップ --- trap 'rm -f "$TEMP_FILE"' EXIT # 終了時に必ず一時ファイルを削除 echo "Fetching API status..." # --- 実行 --- # -s: 進捗非表示, -S: エラー表示, -L: リダイレクト追従 # --retry: 通信失敗時の再試行, --fail: 4xx/5xxで終了コードを返す if ! curl -sSL --retry 3 --retry-delay 2 --max-time 10 \ -o "$TEMP_FILE" -w "%{http_code}" "$API_URL" | grep -q "200"; then echo "Error: API request failed or returned non-200 status." >&2 exit 1 fi # --- jqによる検証 --- # -e: 結果がnullまたはfalseの場合に終了ステータス1を返す if ! jq -e '.status == "UP" and .components.db.status == "OK"' "$TEMP_FILE" > /dev/null; then echo "Error: JSON validation failed. Unexpected API response structure." >&2 cat "$TEMP_FILE" >&2 exit 1 fi echo "API Health Check Passed." </pre> </div> <h3 class="wp-block-heading">2. 定期実行設定 (<code>systemd</code>)</h3> <p><code>/etc/systemd/system/api-healthcheck.service</code></p> <div class="codehilite"> <pre data-enlighter-language="generic">[Unit] Description=API Health Check Automation [Service] Type=oneshot ExecStart=/usr/local/bin/api_check.sh User=nobody Group=nogroup [Install] WantedBy=multi-user.target </pre> </div> <p><code>/etc/systemd/system/api-healthcheck.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> <h2 class="wp-block-heading">【検証と運用】</h2> <h3 class="wp-block-heading">正常系の確認</h3> <p>スクリプトを直接実行し、終了コードを確認します。</p> <div class="codehilite"> <pre data-enlighter-language="generic">./api_check.sh echo $? # 0 であれば正常 </pre> </div> <h3 class="wp-block-heading">異常系のログ確認</h3> <p>systemd経由で実行している場合、<code>journalctl</code> で詳細を確認可能です。</p> <div class="codehilite"> <pre data-enlighter-language="generic">journalctl -u api-healthcheck.service -f </pre> </div> <h2 class="wp-block-heading">【トラブルシューティングと落とし穴】</h2> <ul class="wp-block-list"> <li><p><strong>権限問題</strong>: <code>mktemp</code> を使用する際、実行ユーザーに <code>/tmp</code> への書込権限があるか確認してください。systemdで <code>User=nobody</code> を指定する場合、プライベートな一時ディレクトリ設定 (<code>PrivateTmp=true</code>) の活用を検討してください。</p></li> <li><p><strong>環境変数の漏洩</strong>: APIトークン等の機密情報はスクリプト内にハードコードせず、<code>systemd</code> の <code>EnvironmentFile</code> または環境変数から読み込むように設計してください。</p></li> <li><p><strong>jqのパースエラー</strong>: 不完全なJSON（ネットワーク断による途切れ等）を <code>jq</code> に渡すとエラーを吐いて停止します。<code>set -e</code> により即座にスクリプトが止まるため、ログに原因を残す工夫が必要です。</p></li> </ul> <h2 class="wp-block-heading">【まとめ】</h2> <p>運用の冪等性を維持するための3つのポイント：</p> <ol class="wp-block-list"> <li><p><strong>Fail-fastの実装</strong>: <code>set -euo pipefail</code> と <code>curl --fail</code> を組み合わせ、異常発生時に即座に停止させる。</p></li> <li><p><strong>一時リソースの自動破棄</strong>: <code>trap</code> コマンドで作業用ファイルを確実にクリーンアップし、ディスク圧迫を防ぐ。</p></li> <li><p><strong>スキーマ検証の厳格化</strong>: <code>jq -e</code> を活用し、単なる通信成功だけでなくデータ構造が期待通りであることを保証する。</p></li> </ol>

graph TD
A[Start] --> B["curl: API Request"]
B --> C{"HTTP Status 200?"}
C -- No --> D["Error Exit / Retry"]
C -- Yes --> E["jq: Parse & Validate JSON"]
E --> F{"Target Value Exists?"}
F -- No --> G["Validation Error"]
F -- Yes --> H["Process Success / Output"]
H --> I[End]

#!/usr/bin/env bash

# --- 安全設定 ---

set -euo pipefail # エラーで停止、未定義変数禁止、パイプ内のエラー捕捉
IFS=$'\n\t'       # スペースを含むファイル名の誤動作防止

# --- 定数 ---

readonly API_URL="https://api.example.com/v1/health"
readonly TEMP_FILE=$(mktemp /tmp/api_res.XXXXXX)

# --- クリーンアップ ---

trap 'rm -f "$TEMP_FILE"' EXIT # 終了時に必ず一時ファイルを削除

echo "Fetching API status..."

# --- 実行 ---


# -s: 進捗非表示, -S: エラー表示, -L: リダイレクト追従


# --retry: 通信失敗時の再試行, --fail: 4xx/5xxで終了コードを返す

if ! curl -sSL --retry 3 --retry-delay 2 --max-time 10 \
     -o "$TEMP_FILE" -w "%{http_code}" "$API_URL" | grep -q "200"; then
    echo "Error: API request failed or returned non-200 status." >&2
    exit 1
fi

# --- jqによる検証 ---


# -e: 結果がnullまたはfalseの場合に終了ステータス1を返す

if ! jq -e '.status == "UP" and .components.db.status == "OK"' "$TEMP_FILE" > /dev/null; then
    echo "Error: JSON validation failed. Unexpected API response structure." >&2
    cat "$TEMP_FILE" >&2
    exit 1
fi

echo "API Health Check Passed."

[Unit]
Description=API Health Check Automation

[Service]
Type=oneshot
ExecStart=/usr/local/bin/api_check.sh
User=nobody
Group=nogroup

[Install]
WantedBy=multi-user.target

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

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

[Install]
WantedBy=timers.target

./api_check.sh
echo $? # 0 であれば正常

journalctl -u api-healthcheck.service -f