異常検知時の即時安全停止とクリーンアップ：`set -euo pipefail`と`trap`で実現する堅牢な外部APIデータ連携スクリプトの設計

Tech

本記事はGeminiの出力をプロンプト工学で整理した業務ドラフト（未検証）です。

異常検知時の即時安全停止とクリーンアップ：set -euo pipefailとtrapで実現する堅牢な外部APIデータ連携スクリプトの設計

【導入と前提】

外部APIからデータを取得・整形してシステムに配置する一連の処理を、エラー発生時に即時停止し副作用なく安全に終了する堅牢な自動化スクリプトとして実装します。

  • OS / 実行環境: GNU/Linux (Bash 4.4以降、Debian/Ubuntu/RHEL)

  • 依存ツール: curl (v7.68.0以降), jq (v1.6以降), systemd (v245以降)

【処理フローと設計】

graph TD
    A["スクリプト起動"] --> B["trap設定 & 一時ファイル作成"]
    B --> C["curlによるAPIデータ取得"]
    C -->|APIエラー/タイムアウト| D["trap発動: 一時ファイル削除 & 異常終了"]
    C -->|通信正常| E["jqによるJSON構文と値の検証"]
    E -->|パースエラー/不正データ| D
    E -->|バリデーション合格| F["アトミックな書き換え処理"]
    F --> G["trap発動: 一時ファイルをクリーンアップして正常終了"]

処理フローのポイント

  1. 初期安全シールド: 実行直後に set -euo pipefail を定義し、想定外の未定義変数やパイプライン途中でのエラーを検知した瞬間に処理を打ち切ります。

  2. 自動リソース回収: trap 機構を用いて、途中で処理がクラッシュした場合や、手動でシグナル（SIGINT/SIGTERM）を受け取った場合でも、必ず作成した一時ファイルを確実に削除します。

  3. アトミック更新: 書き込み対象ファイルを直接上書きするのではなく、一度一時ファイルに保存して整合性を検証した上で、mv（名前変更）によるアトミック（不可分）なファイル置換を行います。これにより、書き込み途中の破損ファイルをシステムが参照するリスクを防ぎます。

【実装：堅牢な自動化スクリプト】

1. 同期用シェルスクリプト (/usr/local/bin/sync_metrics.sh)

#!/usr/bin/env bash

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


# 堅牢なデータ同期スクリプト (APIデータ取得 & バリデーション & 配置)


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

# -e: コマンドの終了ステータスが非ゼロの場合に即時終了


# -u: 未定義の変数を使用しようとした場合にエラーとして終了


# -o pipefail: パイプライン内のいずれかのコマンドが失敗した段階でパイプ全体を失敗とみなす

set -euo pipefail

# ロギング用関数

log() {
    echo "[$(date +'%Y-%m-%dT%H:%M:%S%z')] [$0] $1"
}

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


# 環境変数・パス設定


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

API_URL="https://api.example.com/v1/metrics"
API_TOKEN_FILE="/etc/opt/myapp/api_token"
OUTPUT_DIR="/var/lib/myapp/data"
OUTPUT_FILE="${OUTPUT_DIR}/latest_metrics.json"
TMP_FILE=""

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


# トラップ (エラー処理 & クリーンアップ) の定義


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

cleanup() {

    # 直前のコマンドの終了ステータスを退避

    local exit_code=$?

    # 作成された一時ファイルがあれば確実に消去

    if [ -n "${TMP_FILE:-}" ] && [ -f "$TMP_FILE" ]; then
        log "INFO: 一時ファイルを安全に削除しています: ${TMP_FILE}"
        rm -f "$TMP_FILE"
    fi

    if [ "$exit_code" -ne 0 ]; then
        log "ERROR: 処理中にエラーが発生したため、異常終了しました (ステータス: ${exit_code})"
    else
        log "SUCCESS: すべての処理が正常に完了しました"
    fi
    exit "$exit_code"
}

# EXITシグナル（正常終了・シグナル・エラー停止問わず実行）でcleanupをコール

trap cleanup EXIT

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


# メイン処理開始


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

log "INFO: 処理を開始します"

# 必要な設定ファイルのチェック

if [ ! -f "$API_TOKEN_FILE" ]; then
    log "ERROR: APIトークンファイルが見つかりません: ${API_TOKEN_FILE}"
    exit 1
fi

# セキュアな一時ファイルの生成 (格納ディレクトリは /tmp)

TMP_FILE=$(mktemp /tmp/sync_metrics.XXXXXX)

# トークンの読み出し (不要な環境変数展開を避けるためファイルから直接取得)

API_TOKEN=$(cat "$API_TOKEN_FILE")

log "INFO: 外部APIからデータを取得中..."

# curlのオプション解説:


# -s: サイレントモード (進捗バー非表示)


# -S: エラー時のみエラーメッセージを表示


# -L: リダイレクトを追跡


# -f: HTTPレスポンスコードが400以上の場合にエラーとして処理を終了


# --retry: 一時エラー時の最大リトライ回数


# --retry-delay: リトライ間のウェイト(秒)


# --max-time: 最大許容タイムアウト時間(秒)

curl -s -S -L -f \
     --retry 3 \
     --retry-delay 2 \
     --max-time 15 \
     -H "Authorization: Bearer ${API_TOKEN}" \
     "${API_URL}" > "$TMP_FILE"

log "INFO: データの整合性を検証しています..."

# jqのオプション解説:


# -e: フィルタの出力が null または false の場合に終了ステータスを 1 にする


# .status: レスポンス内のステータスフラグ

if ! jq -e '.status == "success"' "$TMP_FILE" > /dev/null 2>&1; then
    log "ERROR: 取得データの検証に失敗しました。仕様に合致しないJSON、またはstatusがsuccessではありません。"
    exit 2
fi

# 必要箇所のフィルタリングとアトミック（不可分）なファイル移動

mkdir -p "$OUTPUT_DIR"

# 一時ファイルに中間出力を書き込んでから移動する (書込み中ファイルの読み出しを防ぐ)

jq '.data' "$TMP_FILE" > "${OUTPUT_FILE}.tmp"
mv "${OUTPUT_FILE}.tmp" "$OUTPUT_FILE"

log "INFO: データを正常に更新しました: ${OUTPUT_FILE}"

2. 定期実行用 systemd ユニットファイルの設定

cronに比べ、エラーの捕捉（ログ収集）や実行リトライ、環境隔離に優れた systemd によるタイマー起動を設定します。

サービス定義: /etc/systemd/system/myapp-sync.service

[Unit]
Description=My Application Data Synchronization Service
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User=myapp
Group=myapp
ExecStart=/usr/local/bin/sync_metrics.sh

# セキュリティ向上のためのサンドボックス設定

PrivateTmp=true
ProtectSystem=full
ProtectHome=true
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

タイマー定義: /etc/systemd/system/myapp-sync.timer

[Unit]
Description=Run My Application Data Synchronization Service hourly

[Timer]

# 毎時0分に起動

OnCalendar=hourly

# 前回システムダウン等でスキップされた場合は即座に実行

Persistent=true

[Install]
WantedBy=timers.target

【検証と運用】

1. 正常系確認

スクリプトに実行権限を付与し、正常系テストを実施します。

# 権限の付与

sudo chmod +x /usr/local/bin/sync_metrics.sh

# 手動によるシステム実行

sudo systemctl start myapp-sync.service

# 実行成否と成果物の確認

ls -la /var/lib/myapp/data/latest_metrics.json

2. 異常系テスト（テストケース）

スクリプトが正しく一時ファイルをクリーンアップし、エラーを補足して終了するか検証します。

  • ケースA: APIトークン未存在

    sudo mv /etc/opt/myapp/api_token /etc/opt/myapp/api_token.bak
sudo /usr/local/bin/sync_metrics.sh

# -> エラーログが出力され、一時ファイルが残らず即時終了(ステータス1)すること。

  • ケースB: 不正なJSONデータのインジェクション

    # 偽のAPI URLやダミーファイルを仕込むなどし、検証フェーズを通らない不正データを意図的に流す


# -> 「整合性を検証しています...」のフェーズで jq のエラーを捉え、異常終了(ステータス2)すること。

3. systemd経由のログ・動作確認

# 稼働ステータスと直近のログを表示

sudo systemctl status myapp-sync.service

# サービス詳細ログのリアルタイム監視

sudo journalctl -u myapp-sync.service -f

【トラブルシューティングと落とし穴】

1. 権限問題と sudo の落とし穴

trap でクリーンアップを行う一時ファイル（/tmp/* など）を sudo 経由で作成した場合、一時ファイルの所有権が root になることで、スクリプト実行ユーザーに削除権限がない場合に cleanup がパーミッションエラーを起こすことがあります。

  • 対策: スクリプトを実行するサービス用ユーザー（例: myapp）を固定し、systemd の User= および Group= 設定で制御します。

2. 環境変数漏洩の防止

set -x（コマンド実行追跡）を実行中に不用意に有効にすると、curl ヘッダーに含まれるAPIキーが標準エラー出力（ログファイル）に直接露出してしまいます。

  • 対策: set -x は本番稼働スクリプトでは絶対に使用しない。また、秘密情報は環境変数から渡すのではなく、権限を設定したトークンファイル（本例の API_TOKEN_FILE）から一時変数に閉じ込める形で読み込みます。

3. 多重起動と残存ロックファイル

高頻度で実行された場合、古いプロセスがロックを保持したままになる恐れがあります。

  • 対策: 必要に応じて、flock コマンドを使用し多重起動を防ぎます。

    # スクリプトの冒頭で排他ロックを確立する例

exec 9>/var/run/sync_metrics.lock
if ! flock -n 9; then
    log "ERROR: 別のデータ同期プロセスが既に実行中です。"
    exit 1
fi

【まとめ】

運用の冪等性（何度実行しても同じ安全な状態が維持される性質）を維持するための3つのポイント：

  1. アトミック更新の徹底: 宛先パスへ直接リダイレクトするのを避け、「一時ファイルの保存・検証 ➔ リネーム(mv)」のプロセスを一貫して守ること。

  2. 状態非依存・自動回収 (trap): エラー、強制終了、シグナル検出など、どのようなパスを辿っても残骸（ゴミファイル）を一切システムに残さない仕組みを作ること。

  3. エラー検出の即時化 (set -euo pipefail): 失敗を曖昧にせず、パイプの途中であろうが不整合が起きた段階で「即座に処理を諦めて知らせる」ことが、下流のデータ破損を防ぐ最良の防御壁となります。

ライセンス：本記事のテキスト/コードは特記なき限り CC BY 4.0 です。引用の際は出典URL（本ページ）を明記してください。
利用ポリシー もご参照ください。

コメント

タイトルとURLをコピーしました