<p><meta/> { “engine”: “gemini-1.5-pro”, “intent”: “technical_documentation_sre”, “style”: “professional_sre_guide”, “reliability”: “unverified_draft”, “focus”: “idempotency_and_atomic_updates” } </p> <p>本記事は<strong>Geminiの出力をプロンプト工学で整理した業務ドラフト（未検証）</strong>です。</p> <h1 class="wp-block-heading">外部API連携における実行状態の管理とアトミックな更新による冪等性の確保</h1> <h2 class="wp-block-heading">【導入と前提】</h2> <p>外部APIへの二重リクエストを防ぎ、障害発生時の安全な再試行を可能にするため、状態ファイルを用いた冪等な自動化スクリプトを構築します。</p> <ul class="wp-block-list"> <li><p><strong>実行環境</strong>: GNU/Linux (Bash 4.4+)</p></li> <li><p><strong>必須ツール</strong>: <code>jq</code> (JSON処理), <code>curl</code> (HTTPクライアント), <code>coreutils</code> (mv, rm等)</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 -->|存在| D["APIから最新データを取得"] C --> D D --> E["jqで未処理の差分を抽出"] E --> F{"未処理分はあるか?"} F -->|Yes| G["APIアクション実行"] G --> H["テンポラリファイルへ状態書込"] H --> I["mvコマンドによるアトミック更新"] F -->|No| J["終了処理"] I --> J </pre></div> <ol class="wp-block-list"> <li><p><strong>差分抽出</strong>: 前回の実行で保存した「処理済みIDリスト」と、APIから取得した最新リストを <code>jq</code> で比較し、新規項目のみを特定します。</p></li> <li><p><strong>アトミック更新</strong>: 状態ファイルへの書き込み中にクラッシュしてもデータが破損しないよう、別名で保存してから <code>mv</code> で置換します。</p></li> </ol> <h2 class="wp-block-heading">【実装：堅牢な自動化スクリプト】</h2> <div class="codehilite"> <pre data-enlighter-language="generic">#!/bin/bash # ============================================================================== # API Integration Script with Idempotency and Atomic State Updates # ============================================================================== set -euo pipefail IFS=$'\n\t' # 設定 readonly STATE_FILE="/var/lib/my-app/processed_ids.json" readonly TEMP_STATE_FILE="${STATE_FILE}.tmp" readonly API_ENDPOINT="https://api.example.com/v1/resources" readonly API_TOKEN_FILE="/etc/my-app/api_token" # クリーンアップ処理 trap 'rm -f "${TEMP_STATE_FILE}"' EXIT # 状態ファイルの初期化（存在しない場合） if [[ ! -f "${STATE_FILE}" ]]; then echo '[]' > "${STATE_FILE}" fi # 1. 最新データの取得 # -s: 進捗非表示, -S: エラー表示, -L: リダイレクト追従, -f: HTTPエラーで失敗 response=$(curl -sSLf -H "Authorization: Bearer $(cat "${API_TOKEN_FILE}")" "${API_ENDPOINT}") # 2. 未処理IDの抽出 (jqを使用した集合演算) # 状態ファイルにあるIDを除外して、新規IDのリストを作成 new_ids=$(echo "${response}" | jq -r --argfile old "${STATE_FILE}" \ '.[] | select(.id as $id | $old | index($id) | not) | .id') if [[ -z "${new_ids}" ]]; then echo "処理すべき新規項目はありません。" exit 0 fi # 3. 各項目に対するアクションの実行 for id in ${new_ids}; do echo "Processing ID: ${id}..." # APIアクション実行例 (POST) # --retry: 接続失敗時のリトライ回数 curl -sSLf -X POST "${API_ENDPOINT}/${id}/activate" \ -H "Authorization: Bearer $(cat "${API_TOKEN_FILE}")" \ --retry 3 # 4. 状態ファイルのアトミックな更新 # 処理が成功するたびに、既存の状態にIDを追加して一時ファイルへ出力 jq --arg id "${id}" '. += [$id]' "${STATE_FILE}" > "${TEMP_STATE_FILE}" # POSIXシステムにおけるmvはアトミックな操作であるため、 # 書き込み途中の不完全なファイルで上書きされるリスクを排除できる mv "${TEMP_STATE_FILE}" "${STATE_FILE}" done echo "全ての処理が正常に完了しました。" </pre> </div> <h3 class="wp-block-heading">systemdによる自動実行（タイマー設定）</h3> <p>定期実行を行う場合は、Cronよりも詳細なログ管理が可能な <code>systemd.timer</code> を推奨します。</p> <div class="codehilite"> <pre data-enlighter-language="generic"># /etc/systemd/system/api-sync.service [Unit] Description=API Sync Task with Idempotency [Service] Type=oneshot ExecStart=/usr/local/bin/api-sync.sh User=appuser Group=appuser # /etc/systemd/system/api-sync.timer [Unit] Description=Run API Sync every 15 minutes [Timer] OnCalendar=*:0/15 Persistent=true [Install] WantedBy=timers.target </pre> </div> <h2 class="wp-block-heading">【検証と運用】</h2> <h3 class="wp-block-heading">正常系の確認</h3> <p>実行後、状態ファイルにIDが記録されているか、APIログ（またはスクリプトの標準出力）を確認します。</p> <div class="codehilite"> <pre data-enlighter-language="generic"># 状態ファイルの中身を確認 jq '.' /var/lib/my-app/processed_ids.json # 次回の実行で「処理すべき項目はありません」と表示されるか確認 sudo /usr/local/bin/api-sync.sh </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-sync.service -f </pre> </div> <h2 class="wp-block-heading">【トラブルシューティングと落とし穴】</h2> <ol class="wp-block-list"> <li><p><strong>権限問題</strong>: 状態ファイルを保存するディレクトリに、実行ユーザーの書き込み権限が必要です。<code>sudo</code> で実行する場合は <code>set -e</code> によりエラー発生時に即停止することに注意してください。</p></li> <li><p><strong>APIトークンの秘匿</strong>: スクリプト内に直接トークンを書かず、環境変数または読み取り制限のかかったファイル（<code>600</code>）から読み込むようにします。</p></li> <li><p><strong>部分的な失敗</strong>: ループ内で特定のIDの処理が失敗した場合、<code>set -e</code> によりスクリプト全体が停止します。その際、失敗したIDは状態ファイルに記録されないため、次回実行時に再度処理対象となり、冪等性が維持されます。</p></li> <li><p><strong>ディスクフル</strong>: <code>mv</code> 前の <code>jq</code> 出力時にディスク容量が不足していると、不完全な一時ファイルが作成されます。この際、<code>set -o pipefail</code> が設定されていれば、エラーとして検知可能です。</p></li> </ol> <h2 class="wp-block-heading">【まとめ】</h2> <p>運用の冪等性を維持するための3つのポイント：</p> <ol class="wp-block-list"> <li><p><strong>外部の状態管理</strong>: スクリプトのメモリ上ではなく、外部ファイルに処理済みフラグを保持する。</p></li> <li><p><strong>アトミックな置換</strong>: ファイル更新時は「一時ファイル作成 ＋ <code>mv</code>」のパターンを徹底する。</p></li> <li><p><strong>jqによる厳密なフィルタリング</strong>: APIレスポンスを直接ループに回さず、既存の状態との差分のみを抽出する。</p></li> </ol>

graph TD
A["スクリプト開始"] --> B{"状態ファイルの確認"}
B -->|存在しない| C["空の状態ファイルを初期化"]
B -->|存在| D["APIから最新データを取得"]
C --> D
D --> E["jqで未処理の差分を抽出"]
E --> F{"未処理分はあるか?"}
F -->|Yes| G["APIアクション実行"]
G --> H["テンポラリファイルへ状態書込"]
H --> I["mvコマンドによるアトミック更新"]
F -->|No| J["終了処理"]
I --> J

#!/bin/bash


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


# API Integration Script with Idempotency and Atomic State Updates


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

set -euo pipefail
IFS=$'\n\t'

# 設定

readonly STATE_FILE="/var/lib/my-app/processed_ids.json"
readonly TEMP_STATE_FILE="${STATE_FILE}.tmp"
readonly API_ENDPOINT="https://api.example.com/v1/resources"
readonly API_TOKEN_FILE="/etc/my-app/api_token"

# クリーンアップ処理

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

# 状態ファイルの初期化（存在しない場合）

if [[ ! -f "${STATE_FILE}" ]]; then
    echo '[]' > "${STATE_FILE}"
fi

# 1. 最新データの取得


# -s: 進捗非表示, -S: エラー表示, -L: リダイレクト追従, -f: HTTPエラーで失敗

response=$(curl -sSLf -H "Authorization: Bearer $(cat "${API_TOKEN_FILE}")" "${API_ENDPOINT}")

# 2. 未処理IDの抽出 (jqを使用した集合演算)


# 状態ファイルにあるIDを除外して、新規IDのリストを作成

new_ids=$(echo "${response}" | jq -r --argfile old "${STATE_FILE}" \
    '.[] | select(.id as $id | $old | index($id) | not) | .id')

if [[ -z "${new_ids}" ]]; then
    echo "処理すべき新規項目はありません。"
    exit 0
fi

# 3. 各項目に対するアクションの実行

for id in ${new_ids}; do
    echo "Processing ID: ${id}..."

    # APIアクション実行例 (POST)


    # --retry: 接続失敗時のリトライ回数

    curl -sSLf -X POST "${API_ENDPOINT}/${id}/activate" \
        -H "Authorization: Bearer $(cat "${API_TOKEN_FILE}")" \
        --retry 3

    # 4. 状態ファイルのアトミックな更新


    # 処理が成功するたびに、既存の状態にIDを追加して一時ファイルへ出力

    jq --arg id "${id}" '. += [$id]' "${STATE_FILE}" > "${TEMP_STATE_FILE}"

    # POSIXシステムにおけるmvはアトミックな操作であるため、


    # 書き込み途中の不完全なファイルで上書きされるリスクを排除できる

    mv "${TEMP_STATE_FILE}" "${STATE_FILE}"
done

echo "全ての処理が正常に完了しました。"

# /etc/systemd/system/api-sync.service

[Unit]
Description=API Sync Task with Idempotency

[Service]
Type=oneshot
ExecStart=/usr/local/bin/api-sync.sh
User=appuser
Group=appuser

# /etc/systemd/system/api-sync.timer

[Unit]
Description=Run API Sync every 15 minutes

[Timer]
OnCalendar=*:0/15
Persistent=true

[Install]
WantedBy=timers.target

# 状態ファイルの中身を確認

jq '.' /var/lib/my-app/processed_ids.json

# 次回の実行で「処理すべき項目はありません」と表示されるか確認

sudo /usr/local/bin/api-sync.sh

# 実行ログの確認

journalctl -u api-sync.service -f