<p>[META] STYLE: SRE_ENGINEER_TECHNICAL_DRAFT FOCUS: SHELL_AUTOMATION_ERROR_HANDLING TOOLS: CURL, JQ, SYSTEMD, BASH [/META]</p> <p>本記事は<strong>Geminiの出力をプロンプト工学で整理した業務ドラフト（未検証）</strong>です。</p> <h1 class="wp-block-heading">REST API 監視の堅牢化：curl と jq による高度な自動検証スクリプトの構築</h1> <h2 class="wp-block-heading">【導入と前提】</h2> <p>マイクロサービスのヘルスチェックとデータ整合性検証を自動化し、異常検知時の即時復旧を支える堅牢なシェルスクリプトの構築手法を解説します。</p> <ul class="wp-block-list"> <li><p><strong>前提環境</strong>: GNU/Linux (Ubuntu 22.04+ / RHEL 9+), <code>curl</code> 7.70+, <code>jq</code> 1.6+</p></li> <li><p><strong>対象</strong>: APIの死活監視および特定フィールドの値に基づく条件分岐が必要な運用環境。</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: Script Execution"] --> B["Environment Check"] B --> C["HTTP Request: curl"] C --> D{"HTTP Status Code"} D -->|200 OK| E["JSON Validation: jq"] D -->|Error/Timeout| H["Error Handler: Trap/Log"] E --> F{"Logic: Expected Value?"} F -->|Match| G["Success: Output Result"] F -->|Mismatch| H G --> I["Cleanup: Remove Temp Files"] H --> I I --> J[End] </pre></div> <p>このフローでは、単なる接続確認に留まらず、レスポンスボディに含まれる特定のJSONフィールドが期待値（例：<code>status: "UP"</code> や <code>version</code>）を満たしているかを厳密に検証します。</p> <h2 class="wp-block-heading">【実装：堅牢な自動化スクリプト】</h2> <div class="codehilite"> <pre data-enlighter-language="generic">#!/usr/bin/env bash # ============================================================================== # API Validation Script # 堅牢なシェル記述（set -euo pipefail）により、途中のエラーで停止させ、 # 不正な状態で後続処理が実行されるのを防ぐ。 # ============================================================================== set -euo pipefail IFS=$'\n\t' # 設定 API_URL="${API_URL:-https://api.example.com/v1/health}" EXPECTED_STATUS="UP" TIMEOUT_SEC=10 TMP_RESPONSE=$(mktemp) # クリーンアップ処理の定義 # 異常終了時でも一時ファイルを確実に削除する cleanup() { rm -f "$TMP_RESPONSE" } trap cleanup EXIT echo "Starting API validation for: $API_URL" # APIリクエストの実行 # -s: 進捗非表示, -S: エラー表示, -f: 4xx/5xxで失敗, -L: リダイレクト追従, --retry: 失敗時の再試行 RESPONSE_CODE=$(curl -s -S -L -f \ --max-time "$TIMEOUT_SEC" \ --retry 3 \ --retry-delay 2 \ --write-out "%{http_code}" \ -o "$TMP_RESPONSE" \ "$API_URL") # ステータスコードの検証（curl -f で既に2xx以外はエラーになるが、念のため） if [[ "$RESPONSE_CODE" -ne 200 ]]; then echo "Error: API returned HTTP $RESPONSE_CODE" >&2 exit 1 fi # jqを用いたJSON検証 # -e: 抽出結果がnullまたはfalseの場合に終了ステータス1を返す # -r: クォートなしの生出力 ACTUAL_STATUS=$(jq -e -r '.status' "$TMP_RESPONSE") if [[ "$ACTUAL_STATUS" != "$EXPECTED_STATUS" ]]; then echo "Validation Failed: Expected $EXPECTED_STATUS but got $ACTUAL_STATUS" >&2 # エラー詳細をログ出力 jq '.' "$TMP_RESPONSE" >&2 exit 1 fi echo "Success: API is $ACTUAL_STATUS" </pre> </div> <h3 class="wp-block-heading">補足：Systemdによる定期実行（Timer）</h3> <p>Cronの代替として、実行履歴が <code>journalctl</code> で管理しやすい <code>systemd timer</code> の利用を推奨します。</p> <div class="codehilite"> <pre data-enlighter-language="generic"># /etc/systemd/system/api-health-check.service [Unit] Description=API Health Check Job [Service] Type=oneshot ExecStart=/usr/local/bin/api-check.sh User=monitor-user # 環境変数の漏洩防止 EnvironmentFile=/etc/default/api-check-env </pre> </div> <h2 class="wp-block-heading">【検証と運用】</h2> <h3 class="wp-block-heading">正常系の確認</h3> <p>スクリプトを実行し、終了ステータス <code>$?</code> が <code>0</code> であることを確認します。</p> <div class="codehilite"> <pre data-enlighter-language="generic">./api-check.sh echo $? # 0が表示されれば成功 </pre> </div> <h3 class="wp-block-heading">エラー時のログ確認</h3> <p><code>systemd</code> を利用している場合、以下のコマンドでエラーログの履歴を詳細に追跡可能です。</p> <div class="codehilite"> <pre data-enlighter-language="generic"># 失敗した直近のログを抽出 journalctl -u api-health-check.service -n 50 --no-pager </pre> </div> <h2 class="wp-block-heading">【トラブルシューティングと落とし穴】</h2> <ol class="wp-block-list"> <li><p><strong>jqのバージョン差異</strong>: <code>jq -e</code> オプションは古いバージョンでは挙動が異なる場合があります。環境導入前に <code>jq --version</code> で 1.6 以上であることを確認してください。</p></li> <li><p><strong>一時ファイルの権限</strong>: <code>mktemp</code> で作成されるファイルは実行ユーザーのみ読み書き可能ですが、<code>umask</code> 設定が緩い環境では注意が必要です。</p></li> <li><p><strong>環境変数の秘匿</strong>: APIキーをスクリプト内にハードコードせず、<code>EnvironmentFile</code>（systemd）や CI/CD の Secret 変数から注入してください。</p></li> </ol> <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> を用い、予期せぬエラーが発生した瞬間に処理を停止させる。</p></li> <li><p><strong>リソースの自動クリーンアップ</strong>: <code>trap</code> コマンドで一時ファイルやロックファイルを確実に処理する。</p></li> <li><p><strong>詳細な診断情報の出力</strong>: 失敗時には <code>jq</code> を活用してレスポンスボディ全体を標準エラー出力(stderr)へ流し、デバッグを容易にする。</p></li> </ol>

graph TD
A["Start: Script Execution"] --> B["Environment Check"]
B --> C["HTTP Request: curl"]
C --> D{"HTTP Status Code"}
D -->|200 OK| E["JSON Validation: jq"]
D -->|Error/Timeout| H["Error Handler: Trap/Log"]
E --> F{"Logic: Expected Value?"}
F -->|Match| G["Success: Output Result"]
F -->|Mismatch| H
G --> I["Cleanup: Remove Temp Files"]
H --> I
I --> J[End]

#!/usr/bin/env bash

# ==============================================================================


# API Validation Script


# 堅牢なシェル記述（set -euo pipefail）により、途中のエラーで停止させ、


# 不正な状態で後続処理が実行されるのを防ぐ。


# ==============================================================================

set -euo pipefail
IFS=$'\n\t'

# 設定

API_URL="${API_URL:-https://api.example.com/v1/health}"
EXPECTED_STATUS="UP"
TIMEOUT_SEC=10
TMP_RESPONSE=$(mktemp)

# クリーンアップ処理の定義


# 異常終了時でも一時ファイルを確実に削除する

cleanup() {
  rm -f "$TMP_RESPONSE"
}
trap cleanup EXIT

echo "Starting API validation for: $API_URL"

# APIリクエストの実行


# -s: 進捗非表示, -S: エラー表示, -f: 4xx/5xxで失敗, -L: リダイレクト追従, --retry: 失敗時の再試行

RESPONSE_CODE=$(curl -s -S -L -f \
  --max-time "$TIMEOUT_SEC" \
  --retry 3 \
  --retry-delay 2 \
  --write-out "%{http_code}" \
  -o "$TMP_RESPONSE" \
  "$API_URL")

# ステータスコードの検証（curl -f で既に2xx以外はエラーになるが、念のため）

if [[ "$RESPONSE_CODE" -ne 200 ]]; then
  echo "Error: API returned HTTP $RESPONSE_CODE" >&2
  exit 1
fi

# jqを用いたJSON検証


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


# -r: クォートなしの生出力

ACTUAL_STATUS=$(jq -e -r '.status' "$TMP_RESPONSE")

if [[ "$ACTUAL_STATUS" != "$EXPECTED_STATUS" ]]; then
  echo "Validation Failed: Expected $EXPECTED_STATUS but got $ACTUAL_STATUS" >&2

  # エラー詳細をログ出力

  jq '.' "$TMP_RESPONSE" >&2
  exit 1
fi

echo "Success: API is $ACTUAL_STATUS"

# /etc/systemd/system/api-health-check.service

[Unit]
Description=API Health Check Job

[Service]
Type=oneshot
ExecStart=/usr/local/bin/api-check.sh
User=monitor-user

# 環境変数の漏洩防止

EnvironmentFile=/etc/default/api-check-env

./api-check.sh
echo $?  # 0が表示されれば成功

# 失敗した直近のログを抽出

journalctl -u api-health-check.service -n 50 --no-pager