<p><meta/> { “system_role”: “SRE / DevOps Engineer”, “technical_stack”: [“curl”, “jq”, “Bash”, “systemd”], “objective”: “Design a robust API validation workflow with error handling.”, “style”: “Professional, Tactical, Practical” } </p> <p>本記事は<strong>Geminiの出力をプロンプト工学で整理した業務ドラフト（未検証）</strong>です。</p> <h1 class="wp-block-heading">curlとjqを用いたREST API自動検証の堅牢化：エラーハンドリングと再試行戦略</h1> <h2 class="wp-block-heading">【導入と前提】</h2> <p>curlで取得したJSONをjqでパースし、再試行と異常検知を組み込んだ堅牢なAPI自動検証の仕組みを構築します。</p> <ul class="wp-block-list"> <li><p><strong>OS</strong>: GNU/Linux (Ubuntu 22.04 LTS / RHEL 9 等)</p></li> <li><p><strong>ツール</strong>: curl (7.64+), jq (1.6+), bash (4.0+)</p></li> </ul> <h2 class="wp-block-heading">【処理フローと設計】</h2> <div class="wp-block-merpress-mermaidjs diagram-source-mermaid"><pre class="mermaid"> graph TD A["開始"] --> B{"curl実行"} B -->|失敗/タイムアウト| C["再試行ロジック"] C -->|上限到達| D["エラー終了/通知"] B -->|成功| E["HTTPステータス確認"] E -->|200以外| D E -->|200 OK| F["jqによるスキーマ/値検証"] F -->|不正データ| D F -->|正常データ| G["成功処理/クリーンアップ"] G --> H["終了"] </pre></div> <ol class="wp-block-list"> <li><p><strong>取得フェーズ</strong>: <code>curl</code> の組み込みリトライ機能とタイムアウト設定を活用し、一時的なネットワーク断に対応。</p></li> <li><p><strong>検証フェーズ</strong>: <code>jq</code> の終了コード (<code>-e</code>) を利用し、特定のフィールドの存在や期待される値を厳密にチェック。</p></li> <li><p><strong>終了フェーズ</strong>: 一時ファイルの確実な削除と、標準エラー出力へのログ集約。</p></li> </ol> <h2 class="wp-block-heading">【実装：堅牢な自動化スクリプト】</h2> <div class="codehilite"> <pre data-enlighter-language="generic">#!/usr/bin/env bash # set -e: エラー発生時に即座に終了 # set -u: 未定義変数の参照時にエラー # set -o pipefail: パイプライン途中のエラーも検知 set -euo pipefail # --------------------------------------------------------- # 設定・変数定義 # --------------------------------------------------------- readonly API_URL="https://api.example.com/v1/health" readonly EXPECTED_VERSION="1.2.0" readonly TEMP_FILE=$(mktemp /tmp/api_res.XXXXXX.json) # 終了時に必ず一時ファイルを削除 trap 'rm -f "${TEMP_FILE}"' EXIT echo "[INFO] API検証開始: ${API_URL}" # --------------------------------------------------------- # 1. APIリクエスト実行 (curl) # --------------------------------------------------------- # -s: 進捗表示非表示 # -S: エラー時はメッセージ出力 # -L: リダイレクト追従 # --retry: 通信失敗時の再試行回数 # --retry-delay: 再試行の間隔(秒) # --max-time: 全体のタイムアウト(秒) # -w: レスポンスコードのみを変数に格納 HTTP_STATUS=$(curl -sSL \ --retry 3 \ --retry-delay 2 \ --max-time 10 \ -o "${TEMP_FILE}" \ -w "%{http_code}" \ "${API_URL}") # ステータスコードが200かチェック if [ "$HTTP_STATUS" -ne 200 ]; then echo "[ERROR] APIリクエスト失敗 ステータスコード: ${HTTP_STATUS}" >&2 exit 1 fi # --------------------------------------------------------- # 2. JSON構造・値の検証 (jq) # --------------------------------------------------------- # -e: 抽出結果が null または false の場合に終了コード 1 を返す # .status == "ok" かつ .version が期待値か確認 if ! jq -e ".status == \"ok\" and .version == \"${EXPECTED_VERSION}\"" "${TEMP_FILE}" > /dev/null; then echo "[ERROR] レスポンス内容が不正です" >&2 echo "内容: $(cat "${TEMP_FILE}")" >&2 exit 1 fi echo "[SUCCESS] API検証正常終了 (Version: ${EXPECTED_VERSION})" </pre> </div> <h3 class="wp-block-heading">補足：systemdによる定期実行の構成例</h3> <p>API監視をデーモン化または定期実行する場合、以下のユニットファイルを <code>/etc/systemd/system/api-check.service</code> として配置します。</p> <div class="codehilite"> <pre data-enlighter-language="generic">[Unit] Description=API Health Checker After=network.target [Service] Type=oneshot ExecStart=/usr/local/bin/api-check.sh User=monitoring-user # 環境変数の漏洩を防ぐため、認証情報はファイルから読み込む EnvironmentFile=-/etc/default/api-check [Install] WantedBy=multi-user.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">bash api-check.sh echo $? # 0 であれば成功 </pre> </div> <h3 class="wp-block-heading">エラー時の確認</h3> <p><code>systemd</code> 経由で実行している場合、<code>journalctl</code> を使用して原因を特定します。</p> <div class="codehilite"> <pre data-enlighter-language="generic"># 失敗した直近のログを確認 journalctl -u api-check.service -n 50 --no-pager </pre> </div> <h2 class="wp-block-heading">【トラブルシューティングと落とし穴】</h2> <ul class="wp-block-list"> <li><p><strong>権限問題</strong>: <code>mktemp</code> で作成するディレクトリに実行ユーザーの書込権限があるか確認してください。<code>sudo</code> で実行する場合は <code>trap</code> による削除が適切に行われるよう注意が必要です。</p></li> <li><p><strong>環境変数の漏洩</strong>: APIキーなどの機密情報はスクリプト内にハードコードせず、<code>EnvironmentFile</code> や <code>export</code> 済みの変数から読み込み、<code>set -x</code>（デバッグ実行）を使用する際は機密情報が出力されないよう保護してください。</p></li> <li><p><strong>jqの互換性</strong>: 古いディストリビューション（CentOS 7等）では <code>jq 1.5</code> が使われている場合があり、一部の関数（<code>any</code>, <code>all</code>等）の挙動が異なる可能性があります。</p></li> </ul> <h2 class="wp-block-heading">【まとめ】</h2> <p>運用の冪等性と堅牢性を維持するためのポイント：</p> <ol class="wp-block-list"> <li><p><strong>異常終了の早期化</strong>: <code>set -euo pipefail</code> により、予期せぬ挙動を未然に防ぐ。</p></li> <li><p><strong>再試行の標準化</strong>: <code>curl</code> 自体のリトライ機能を使い、シェル側で複雑なループを書かない。</p></li> <li><p><strong>状態の局所化</strong>: <code>trap</code> と <code>mktemp</code> を活用し、実行環境にゴミ（一時ファイル）を残さない。</p></li> </ol>

graph TD
A["開始"] --> B{"curl実行"}
B -->|失敗/タイムアウト| C["再試行ロジック"]
C -->|上限到達| D["エラー終了/通知"]
B -->|成功| E["HTTPステータス確認"]
E -->|200以外| D
E -->|200 OK| F["jqによるスキーマ/値検証"]
F -->|不正データ| D
F -->|正常データ| G["成功処理/クリーンアップ"]
G --> H["終了"]

#!/usr/bin/env bash

# set -e: エラー発生時に即座に終了


# set -u: 未定義変数の参照時にエラー


# set -o pipefail: パイプライン途中のエラーも検知

set -euo pipefail

# ---------------------------------------------------------


# 設定・変数定義


# ---------------------------------------------------------

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

# 終了時に必ず一時ファイルを削除

trap 'rm -f "${TEMP_FILE}"' EXIT

echo "[INFO] API検証開始: ${API_URL}"

# ---------------------------------------------------------


# 1. APIリクエスト実行 (curl)


# ---------------------------------------------------------


# -s: 進捗表示非表示


# -S: エラー時はメッセージ出力


# -L: リダイレクト追従


# --retry: 通信失敗時の再試行回数


# --retry-delay: 再試行の間隔(秒)


# --max-time: 全体のタイムアウト(秒)


# -w: レスポンスコードのみを変数に格納

HTTP_STATUS=$(curl -sSL \
    --retry 3 \
    --retry-delay 2 \
    --max-time 10 \
    -o "${TEMP_FILE}" \
    -w "%{http_code}" \
    "${API_URL}")

# ステータスコードが200かチェック

if [ "$HTTP_STATUS" -ne 200 ]; then
    echo "[ERROR] APIリクエスト失敗 ステータスコード: ${HTTP_STATUS}" >&2
    exit 1
fi

# ---------------------------------------------------------


# 2. JSON構造・値の検証 (jq)


# ---------------------------------------------------------


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


# .status == "ok" かつ .version が期待値か確認

if ! jq -e ".status == \"ok\" and .version == \"${EXPECTED_VERSION}\"" "${TEMP_FILE}" > /dev/null; then
    echo "[ERROR] レスポンス内容が不正です" >&2
    echo "内容: $(cat "${TEMP_FILE}")" >&2
    exit 1
fi

echo "[SUCCESS] API検証正常終了 (Version: ${EXPECTED_VERSION})"

[Unit]
Description=API Health Checker
After=network.target

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

# 環境変数の漏洩を防ぐため、認証情報はファイルから読み込む

EnvironmentFile=-/etc/default/api-check

[Install]
WantedBy=multi-user.target

bash api-check.sh
echo $?  # 0 であれば成功

# 失敗した直近のログを確認

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