[META] { “role”: “SRE/DevOps Engineer”, “topic”: “Idempotent External API Integration with CLI & State Management”, “keywords”: [“Bash”, “jq”, “curl”, “Idempotency”, “Atomic Update”, “systemd”], “security”: [“Secret Masking”, “Atomic Writes”, “Error Handling”], “version”: “1.1” } [/META]
本記事はGeminiの出力をプロンプト工学で整理した業務ドラフト（未検証）です。
外部API連携における状態管理の自動化：冪等性を担保する堅牢なCLIスクリプト設計
【導入と前提】
外部APIとの連携において、二重実行の防止と障害復旧の簡略化は不可欠です。本稿では、状態ファイルを用いた「冪等性（Idempotency）」を保証するシェルスクリプトの設計手法を解説します。
OS/実行環境: GNU/Linux (Ubuntu 22.04 LTS等)
必須ツール:
curl(7.68+),jq(1.6+),systemd
【処理フローと設計】
graph TD
A["開始"] --> B{"状態ファイル確認"}
B -->|未処理/要更新| C["一時ファイル作成"]
B -->|完了済み| Z["終了"]
C --> D["外部API呼び出し: curl"]
D --> E{"レスポンス検証: jq"}
E -->|成功| F["状態ファイルのアトミック更新: mv"]
E -->|失敗| G["エラー処理/クリーンアップ"]
F --> Z
G --> Z
この設計の核心は、「一時ファイルへの書き込み」と「mvコマンドによるリネーム」を組み合わせたアトミック（原子性）な更新にあります。これにより、書き込み中のクラッシュによる状態ファイルの破損を防ぎます。
【実装：堅牢な自動化スクリプト】
1. 冪等性制御スクリプト (sync-api.sh)
#!/usr/bin/env bash
# set -e: エラーで即時停止, -u: 未定義変数の参照禁止, -o pipefail: パイプ内のエラーも拾う
set -euo pipefail
# 環境設定
STATE_FILE="/var/lib/my-app/sync_state.json"
TEMP_FILE=$(mktemp)
API_ENDPOINT="https://api.example.com/v1/resource"
API_KEY="${API_TOKEN:-}" # 環境変数から取得
# クリーンアップ処理
trap 'rm -f "$TEMP_FILE"' EXIT
# 0. APIキーの存在確認
if [[ -z "$API_KEY" ]]; then
echo "Error: API_TOKEN is not set." >&2
exit 1
fi
# 1. 現在の状態を確認 (jqの-rでクォート除去, -eで終了コード制御)
if [[ -f "$STATE_FILE" ]]; then
LAST_SYNC=$(jq -r '.last_sync' "$STATE_FILE")
echo "Found state file. Last sync: $LAST_SYNC"
fi
# 2. APIリクエスト実行
# -s: 進捗非表示, -S: エラー表示, -L: リダイレクト追従, --retry: ネットワーク一時エラー時再試行
RESPONSE=$(curl -sSL --retry 3 --fail \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
"$API_ENDPOINT")
# 3. レスポンスの検証と一時保存
# jqで構造を整えつつ、タイムスタンプを付与して一時ファイルへ
echo "$RESPONSE" | jq --arg now "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
'. + {last_sync: $now, status: "success"}' > "$TEMP_FILE"
# 4. アトミックな更新
# 同一ファイルシステム内でのmvはアトミックな操作となる
mv "$TEMP_FILE" "$STATE_FILE"
echo "Sync completed successfully."
2. 定期実行設定 (systemd.timer)
cronよりも詳細なログ記録とリトライ制御が可能なsystemdタイマーを利用します。
/etc/systemd/system/api-sync.service
[Unit] Description=External API Sync Job After=network-online.target [Service] Type=oneshot User=syncuser EnvironmentFile=/etc/default/api-sync-env ExecStart=/usr/local/bin/sync-api.sh # 実行失敗時の簡単なリトライ設定 Restart=on-failure RestartSec=30s [Install] WantedBy=multi-user.target
【検証と運用】
正常系の確認
スクリプトを実行し、状態ファイルが正しく更新されているか確認します。
# スクリプトの手動実行 sudo -u syncuser ./sync-api.sh # 状態ファイルの確認 cat /var/lib/my-app/sync_state.json | jq .
エラー確認
systemd経由で実行している場合、標準出力・標準エラー出力はすべてJournaldに集約されます。
# 直近の実行ログを確認 journalctl -u api-sync.service -n 50 --no-pager
【トラブルシューティングと落とし穴】
ファイルパーミッション:
mv操作を行う際、宛先ディレクトリへの書き込み権限が必要です。STATE_FILE自体の権限だけでなく、ディレクトリ権限を適切に設定（例:chown syncuser:syncuser /var/lib/my-app）してください。APIレート制限: 短時間でのリトライは429 Too Many Requestsを招きます。
curl --retry-delayオプションで指数バックオフを検討してください。環境変数の露出: APIトークンなどの機密情報は、スクリプト内にハードコードせず、
systemdのEnvironmentFile（パーミッション 600 推奨）から読み込むようにします。ディスクフル: 一時ファイル作成時にディスク容量が不足していると
mktempが失敗します。監視対象に/tmpや/var/libを含めることが重要です。
【まとめ】
運用の冪等性を維持するための3つのポイント：
一貫性の保証:
mktempとmvを使い、不完全な書き込み状態を作らない。失敗の可視化:
set -euo pipefailとjournalctlを活用し、サイレントな失敗を防ぐ。状態の外部化: 処理済みフラグを外部ファイル（JSON等）で管理し、スクリプトの再入を安全にする。
