<p>[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]</p> <p>本記事は<strong>Geminiの出力をプロンプト工学で整理した業務ドラフト（未検証）</strong>です。</p> <h1 class="wp-block-heading">外部API連携における状態管理の自動化：冪等性を担保する堅牢なCLIスクリプト設計</h1> <h2 class="wp-block-heading">【導入と前提】</h2> <p>外部APIとの連携において、二重実行の防止と障害復旧の簡略化は不可欠です。本稿では、状態ファイルを用いた「冪等性（Idempotency）」を保証するシェルスクリプトの設計手法を解説します。</p> <ul class="wp-block-list"> <li><p><strong>OS/実行環境</strong>: GNU/Linux (Ubuntu 22.04 LTS等)</p></li> <li><p><strong>必須ツール</strong>: <code>curl</code> (7.68+), <code>jq</code> (1.6+), <code>systemd</code></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{"状態ファイル確認"} B -->|未処理/要更新| C["一時ファイル作成"] B -->|完了済み| Z["終了"] C --> D["外部API呼び出し: curl"] D --> E{"レスポンス検証: jq"} E -->|成功| F["状態ファイルのアトミック更新: mv"] E -->|失敗| G["エラー処理/クリーンアップ"] F --> Z G --> Z </pre></div> <p>この設計の核心は、<strong>「一時ファイルへの書き込み」と「mvコマンドによるリネーム」を組み合わせたアトミック（原子性）な更新</strong>にあります。これにより、書き込み中のクラッシュによる状態ファイルの破損を防ぎます。</p> <h2 class="wp-block-heading">【実装：堅牢な自動化スクリプト】</h2> <h3 class="wp-block-heading">1. 冪等性制御スクリプト (<code>sync-api.sh</code>)</h3> <div class="codehilite"> <pre data-enlighter-language="generic">#!/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." </pre> </div> <h3 class="wp-block-heading">2. 定期実行設定 (<code>systemd.timer</code>)</h3> <p>cronよりも詳細なログ記録とリトライ制御が可能なsystemdタイマーを利用します。</p> <p><strong><code>/etc/systemd/system/api-sync.service</code></strong></p> <div class="codehilite"> <pre data-enlighter-language="generic">[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 </pre> </div> <h2 class="wp-block-heading">【検証と運用】</h2> <h3 class="wp-block-heading">正常系の確認</h3> <p>スクリプトを実行し、状態ファイルが正しく更新されているか確認します。</p> <div class="codehilite"> <pre data-enlighter-language="generic"># スクリプトの手動実行 sudo -u syncuser ./sync-api.sh # 状態ファイルの確認 cat /var/lib/my-app/sync_state.json | jq . </pre> </div> <h3 class="wp-block-heading">エラー確認</h3> <p>systemd経由で実行している場合、標準出力・標準エラー出力はすべてJournaldに集約されます。</p> <div class="codehilite"> <pre data-enlighter-language="generic"># 直近の実行ログを確認 journalctl -u api-sync.service -n 50 --no-pager </pre> </div> <h2 class="wp-block-heading">【トラブルシューティングと落とし穴】</h2> <ol class="wp-block-list"> <li><p><strong>ファイルパーミッション</strong>: <code>mv</code> 操作を行う際、宛先ディレクトリへの書き込み権限が必要です。<code>STATE_FILE</code> 自体の権限だけでなく、ディレクトリ権限を適切に設定（例: <code>chown syncuser:syncuser /var/lib/my-app</code>）してください。</p></li> <li><p><strong>APIレート制限</strong>: 短時間でのリトライは429 Too Many Requestsを招きます。<code>curl --retry-delay</code> オプションで指数バックオフを検討してください。</p></li> <li><p><strong>環境変数の露出</strong>: APIトークンなどの機密情報は、スクリプト内にハードコードせず、<code>systemd</code> の <code>EnvironmentFile</code>（パーミッション 600 推奨）から読み込むようにします。</p></li> <li><p><strong>ディスクフル</strong>: 一時ファイル作成時にディスク容量が不足していると <code>mktemp</code> が失敗します。監視対象に <code>/tmp</code> や <code>/var/lib</code> を含めることが重要です。</p></li> </ol> <h2 class="wp-block-heading">【まとめ】</h2> <p>運用の冪等性を維持するための3つのポイント：</p> <ol class="wp-block-list"> <li><p><strong>一貫性の保証</strong>: <code>mktemp</code> と <code>mv</code> を使い、不完全な書き込み状態を作らない。</p></li> <li><p><strong>失敗の可視化</strong>: <code>set -euo pipefail</code> と <code>journalctl</code> を活用し、サイレントな失敗を防ぐ。</p></li> <li><p><strong>状態の外部化</strong>: 処理済みフラグを外部ファイル（JSON等）で管理し、スクリプトの再入を安全にする。</p></li> </ol>

graph TD
    A["開始"] --> B{"状態ファイル確認"}
    B -->|未処理/要更新| C["一時ファイル作成"]
    B -->|完了済み| Z["終了"]
    C --> D["外部API呼び出し: curl"]
    D --> E{"レスポンス検証: jq"}
    E -->|成功| F["状態ファイルのアトミック更新: mv"]
    E -->|失敗| G["エラー処理/クリーンアップ"]
    F --> Z
    G --> Z

#!/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."

[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 .

# 直近の実行ログを確認

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