{ “role”: “SRE/DevOps Engineer”, “focus”: “Robust CLI Automation & Idempotency”, “technologies”: [“bash”, “jq”, “curl”, “systemd”, “atomic-file-ops”], “security”: “Credential management & Temp file cleanup”, “version”: “1.1” }
本記事はGeminiの出力をプロンプト工学で整理した業務ドラフト（未検証）です。
外部API連携における冪等性を担保する状態管理CLIスクリプトの実装ガイド
【導入と前提】
APIリクエストの二重実行を防止し、中断後の再開を可能にする「状態ファイル方式」の自動化スクリプトを構築します。
OS: GNU/Linux (POSIX準拠のシェル環境)
ツール:
curl(API通信),jq(JSON処理),flock(排他制御)
【処理フローと設計】
graph TD
A["スクリプト開始"] --> B{"ロックファイル確認"}
B -- ロック取得失敗 --> C["終了: 二重起動防止"]
B -- ロック取得成功 --> D["状態ファイル読み込み"]
D --> E{"対象タスクは完了済?"}
E -- YES --> F["スキップして正常終了"]
E -- NO --> G["APIリクエスト実行"]
G --> H{"レスポンス確認"}
H -- 成功 --> I["一時状態ファイル作成"]
I --> J["アトミックな移動 mv"]
J --> K["終了"]
H -- 失敗 --> L["エラー処理/リトライ"]
この設計の核心は、「API成功」と「ローカルの状態更新」の乖離を最小限にするアトミックなファイル操作にあります。mv コマンドは同一ファイルシステム内においてシステムコールレベルで原子性が保証されるため、不完全な状態ファイルが作成されるリスクを排除できます。
【実装：堅牢な自動化スクリプト】
#!/usr/bin/env bash
# --- 設定・定数 ---
set -euo pipefail # エラーで停止、未定義変数禁止、パイプ途中のエラーを拾う
readonly LOCK_FILE="/tmp/api_sync.lock"
readonly STATE_FILE="./state.json"
readonly API_ENDPOINT="https://api.example.com/v1/resource"
readonly API_KEY_FILE="./.api_key" # 認証情報はファイルから読み込む
# --- トラップ設定 (クリーンアップ) ---
# スクリプト終了時に一時ファイルを削除し、ロックを解放する
TEMP_STATE=$(mktemp ./state.json.XXXXXX)
trap 'rm -f "$TEMP_STATE" "$LOCK_FILE"' EXIT
# --- 二重起動の防止 ---
# flockを用いて、同一スクリプトが複数走らないように制御
exec 9>"$LOCK_FILE"
if ! flock -n 9; then
echo "Error: Another instance is running." >&2
exit 1
fi
# --- 冪等性の確認 ---
# jqを使用して現在のステータスを確認
if [[ -f "$STATE_FILE" ]]; then
LAST_STATUS=$(jq -r '.status // "none"' "$STATE_FILE")
if [[ "$LAST_STATUS" == "completed" ]]; then
echo "Task already completed. Skipping."
exit 0
fi
fi
# --- APIリクエスト実行 ---
echo "Sending request to API..."
RESPONSE=$(curl -s -f -L \
--retry 3 \
--retry-delay 2 \
-H "Authorization: Bearer $(cat "$API_KEY_FILE")" \
-X POST "$API_ENDPOINT" \
-d '{"action": "sync"}')
# -s: 進捗非表示, -f: HTTPエラー時に異常終了, -L: リダイレクト追従, --retry: 一時エラー時リトライ
# --- 状態のアトミックな更新 ---
# 新しい状態を一度一時ファイルに書き込み、mvで置換（アトミック更新）
echo "$RESPONSE" | jq '. + {status: "completed", timestamp: (now | strftime("%Y-%m-%dT%H:%M:%SZ"))}' > "$TEMP_STATE"
mv "$TEMP_STATE" "$STATE_FILE"
echo "Sync completed successfully."
定期実行のための systemd Timer 設定例
/etc/systemd/system/api-sync.service
[Unit] Description=API Sync Task with Idempotency [Service] Type=oneshot User=sre-user WorkingDirectory=/opt/scripts ExecStart=/usr/bin/bash /opt/scripts/api_sync.sh
/etc/systemd/system/api-sync.timer
[Unit] Description=Run API Sync every 5 minutes [Timer] OnCalendar=*:0/5 Persistent=true [Install] WantedBy=timers.target
【検証と運用】
正常系の確認
スクリプトを初動させ、
state.jsonが生成されることを確認。再度実行し、”Task already completed.” と表示されAPIが呼ばれないことを確認。
異常系の確認
- APIエンドポイントを無効なURLに変え、リトライ処理とスクリプトの停止（
set -e）を確認。
- APIエンドポイントを無効なURLに変え、リトライ処理とスクリプトの停止（
ログの確認
# systemd経由で実行している場合 journalctl -u api-sync.service -f
【トラブルシューティングと落とし穴】
ファイルシステムの境界:
mvコマンドをアトミックに動作させるため、一時ファイル（mktemp）は必ずSTATE_FILEと同じパーティション（ディレクトリ）内に作成してください。権限エラー: 実行ユーザーがディレクトリに対して書き込み権限を持っているか確認してください。特に
systemdで実行する場合はUser=の設定が重要です。環境変数の露出:
curlの引数に直接トークンを書かず、上記例のようにファイル読み込みや環境変数経由（export）にし、psコマンドで見えないように配慮しています。
【まとめ】
運用の冪等性を維持するための3つのポイント：
実行前チェック: APIを叩く前に、ローカルの状態ファイルで「やるべき仕事が残っているか」を判定する。
アトミックな更新: 中途半端な書き込みを避けるため、一時ファイルに書き出してから
mvで置換する。確実なクリーンアップ:
trapを使い、異常終了時でも一時ファイルやロックファイルが残らないようにする。
