jqとcurlを用いたJSON処理自動化：DevOpsエンジニアのための堅牢な実践

Linux・CLI・DevOpsカテゴリを表すパンダのイラスト Linux・CLI・DevOps
2025.11.17

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

jqとcurlを用いたJSON処理自動化：DevOpsエンジニアのための堅牢な実践

DevOps環境におけるAPI連携やデータ処理では、JSON形式のデータを扱う機会が頻繁にあります。本記事では、jqとcurlという二つの強力なコマンドラインツールを組み合わせ、堅牢かつ自動化されたJSON処理システムを構築する方法を解説します。特に、安全なシェルスクリプトの書き方、systemdによるジョブ管理、そして権限分離の重要性に焦点を当てます。

要件と前提

要件

  • 外部APIからJSONデータを取得し、特定のフィールドを抽出・変換する。

  • 処理は定期的に自動実行されること。

  • 処理は冪等性（idempotent）を保ち、複数回実行してもシステムの状態が変化しないように設計する。

  • セキュリティを考慮し、最小権限の原則に従う。

  • 処理のログを適切に管理する。

前提

  • Linux環境（systemdが動作するディストリビューション）。

  • jqとcurlがインストール済みであること。

  • bashシェルが利用可能であること。

  • 外部APIのエンドポイントと認証情報（必要に応じて）が利用可能であること。

実装

処理フローの概要

JSON処理の自動化は、以下のステップで構成されます。

flowchart TD
    A["systemd Timer"] --> B{"定期実行トリガー"};
    B --> C["systemd Service"];
    C --> D["Bashスクリプト実行"];
    D --> E{"APIへcURLリクエスト"};
    E -- JSON応答 --> F{"jqでデータ処理"};
    F --> G["処理結果の保存/送信"];
    G --> H["ログ出力"];
    H --> I["スクリプト終了"];

1. 安全なBashスクリプトの作成

jqとcurlを組み合わせたJSON処理を行うシェルスクリプトは、堅牢性を確保するために以下のプラクティスを取り入れます。

  • 冪等性: スクリプトが同じ処理を複数回実行しても、システムの状態が同じ結果になるように設計します。例えば、既存のデータを上書きするのではなく、差分を検出して更新する、またはタイムスタンプ付きで新しいファイルとして保存するなどの方法があります。

  • エラーハンドリング: set -euo pipefailを使い、予期せぬエラーでスクリプトが停止するようにします。trapコマンドで一時ファイルのクリーンアップを保証します。

  • 一時ディレクトリ: mktemp -dを使用し、安全な一時ディレクトリを作成します。

以下のprocess_json_data.shスクリプトは、ダミーAPIからJSONデータを取得し、特定のフィールドを抽出し、結果をファイルに保存する例です。

#!/usr/bin/env bash


# process_json_data.sh


# 外部APIからJSONデータを取得し、jqで処理して結果を保存するスクリプト

set -euo pipefail

# 一時ディレクトリの作成とクリーンアップ

_TMP_DIR=$(mktemp -d -t json_processor_XXXXXX)

# mktemp -d の詳細: 指定されたテンプレートに基づいて一時ディレクトリを作成します。


# -t オプションはテンプレートがファイル名の一部であることを示します。


# XXXXXX はランダムな文字列に置き換えられます。


# 例: /tmp/json_processor_aBcD12

echo "[INFO] $(date '+%Y-%m-%d %H:%M:%S JST') - Temporary directory created: $_TMP_DIR"

trap cleanup EXIT

# trap cleanup EXIT: スクリプトが終了する際に cleanup 関数が実行されるように設定します。


# これにより、正常終了、エラー終了、シグナルによる終了のいずれの場合でも一時ディレクトリが確実に削除されます。

cleanup() {
    local exit_code=$? # 終了コードを保存
    if [ -d "${_TMP_DIR}" ]; then
        echo "[INFO] $(date '+%Y-%m-%d %H:%M:%S JST') - Cleaning up temporary directory: $_TMP_DIR"
        rm -rf "${_TMP_DIR}"

        # rm -rf: ディレクトリとその内容を再帰的に強制削除します。


        # セキュリティのため、常に mktemp で作成した一時ディレクトリのみを対象とすべきです。

    fi
    exit "$exit_code" # 保存した終了コードで終了
}

# 設定値

API_ENDPOINT="https://jsonplaceholder.typicode.com/posts"

# API_ENDPOINT: ダミーのJSONデータを提供する公開APIエンドポイント

OUTPUT_DIR="/var/lib/json_processor_data"

# OUTPUT_DIR: 処理結果を保存するディレクトリ。systemdサービスのUser/Group権限で書き込み可能であること。

OUTPUT_FILE_PREFIX="processed_data"

# OUTPUT_FILE_PREFIX: 出力ファイル名のプレフィックス

LOG_FILE="/var/log/json_processor/json_processor.log"

# LOG_FILE: 処理ログの出力先

# ログディレクトリの存在確認と作成 (必要に応じて)

mkdir -p "$(dirname "${LOG_FILE}")"

# mkdir -p: 存在しない場合のみディレクトリを作成します。親ディレクトリも同時に作成します。

mkdir -p "${OUTPUT_DIR}"

# OUTPUT_DIRが存在しない場合に作成

# cURLを用いたAPIリクエストの実行


# cURLのオプション説明:


#   -sS: --silent --show-error (進捗バーを非表示にし、エラーは表示)


#   -X GET: GETメソッドを使用


#   -H "Accept: application/json": JSON形式の応答を要求


#   --retry 5: 失敗した場合、最大5回リトライ


#   --retry-delay 5: リトライ間隔を5秒に設定 (指数バックオフではないが、シンプルな例として)


#   --retry-max-time 60: リトライを含めた全体の最大時間を60秒に設定


#   --cacert /etc/ssl/certs/ca-certificates.crt: システムのCA証明書を使用してTLS検証を強制。


#                                                これにより、不正な証明書に対する攻撃を防ぐ。


#                                                環境によっては不要か、独自のCAパスが必要。


#                                                デフォルトで利用される場合も多いが、明示することで堅牢になる。


#   --output "${_TMP_DIR}/api_response.json": 応答を一時ファイルに保存

echo "[INFO] $(date '+%Y-%m-%d %H:%M:%S JST') - Fetching data from API: ${API_ENDPOINT}" | tee -a "${LOG_FILE}"
if ! curl -sS -X GET \
          -H "Accept: application/json" \
          --retry 5 --retry-delay 5 --retry-max-time 60 \
          --cacert /etc/ssl/certs/ca-certificates.crt \
          --output "${_TMP_DIR}/api_response.json" \
          "${API_ENDPOINT}"; then
    echo "[ERROR] $(date '+%Y-%m-%d %H:%M:%S JST') - Failed to fetch data from API." | tee -a "${LOG_FILE}"
    exit 1
fi

if [ ! -s "${_TMP_DIR}/api_response.json" ]; then
    echo "[ERROR] $(date '+%Y-%m-%d %H:%M:%S JST') - API response file is empty or missing." | tee -a "${LOG_FILE}"
    exit 1
fi

# jqを用いたJSONデータの処理


# この例では、各エントリから 'id' と 'title' フィールドを抽出し、新しいJSONオブジェクトに変換します。


# 処理の計算量: 入力JSONの要素数 N に対して、各要素を処理するため O(N)。


# メモリ条件: 入力JSON全体のサイズに比例。大規模なJSONの場合はストリーミング処理 (jq --stream) を検討。

echo "[INFO] $(date '+%Y-%m-%d %H:%M:%S JST') - Processing JSON data with jq." | tee -a "${LOG_FILE}"
if ! jq '[.[] | {item_id: .id, item_title: .title}]' "${_TMP_DIR}/api_response.json" > "${_TMP_DIR}/processed_data.json"; then
    echo "[ERROR] $(date '+%Y-%m-%d %H:%M:%S JST') - Failed to process JSON data with jq." | tee -a "${LOG_FILE}"
    exit 1
fi

# 処理結果の永続化

TIMESTAMP=$(date '+%Y%m%d%H%M%S')
FINAL_OUTPUT_FILE="${OUTPUT_DIR}/${OUTPUT_FILE_PREFIX}_${TIMESTAMP}.json"

# TIMESTAMP: 冪等性を確保するため、出力ファイル名にタイムスタンプを含めます。


# これにより、前回の実行結果を上書きせず、新しいファイルとして保存されます。


# 既存ファイルのハッシュチェックなどで差分を検出する、より高度な冪等性実装も可能です。

echo "[INFO] $(date '+%Y-%m-%d %H:%M:%S JST') - Saving processed data to: ${FINAL_OUTPUT_FILE}" | tee -a "${LOG_FILE}"
mv "${_TMP_DIR}/processed_data.json" "${FINAL_OUTPUT_FILE}"

# mv: ファイルを一時ディレクトリから最終保存場所に移動します。

echo "[INFO] $(date '+%Y-%m-%d %H:%M:%S JST') - JSON processing completed successfully." | tee -a "${LOG_FILE}"
exit 0
  • 権限分離の注意点: スクリプトの実行ユーザーは、OUTPUT_DIR と LOG_FILE への書き込み権限のみを持つ、専用の非特権ユーザーアカウント（例: jsonproc）で実行することを強く推奨します。rootユーザーでの実行は避けてください。--cacertオプションはシステムのCA証明書パスを指定していますが、組織によっては特定の証明書パスが必要な場合があります。

2. systemdユニットの作成

systemdを使用して、上記のBashスクリプトを定期的に実行するサービスとタイマーを定義します。これにより、スクリプトの実行、監視、ログ管理が一元化されます。

ユーザーとグループの作成 (root権限が必要)

スクリプトを非特権ユーザーで実行するため、専用のユーザーとグループを作成します。

# systemctlコマンドは一般ユーザーでも実行可能ですが、以下のユーザー作成はroot権限が必要です。

sudo groupadd -r jsonproc_group
sudo useradd -r -g jsonproc_group -s /sbin/nologin -c "JSON Processor User" jsonproc

# -r: システムアカウントを作成


# -g: プライマリグループを指定


# -s /sbin/nologin: ログインシェルを無効にし、対話的なログインを禁止


# -c: コメントを追加

必要なディレクトリの所有者と権限を設定します。

sudo mkdir -p /var/lib/json_processor_data
sudo chown jsonproc:jsonproc_group /var/lib/json_processor_data
sudo chmod 750 /var/lib/json_processor_data

sudo mkdir -p /var/log/json_processor
sudo chown jsonproc:jsonproc_group /var/log/json_processor
sudo chmod 750 /var/log/json_processor

2.1. Serviceユニット (.service)

json-processor.serviceを/etc/systemd/system/に作成します。

# /etc/systemd/system/json-processor.service

[Unit]
Description=JSON Data Processor Service
Documentation=https://example.com/json-processor-docs

# After=network.target: ネットワークが利用可能になってからサービスを開始します。


# これにより、cURLがAPIにアクセスできるようになります。

After=network.target

[Service]

# Type=oneshot: 実行が完了したら終了するタイプのサービス。


# スクリプトが完了すると、サービスも終了します。

Type=oneshot

# User=jsonproc, Group=jsonproc_group: スクリプトを非特権ユーザーjsonprocで実行します。


# これにより、最小権限の原則が適用され、セキュリティリスクが軽減されます。

User=jsonproc
Group=jsonproc_group

# WorkingDirectory=/opt/json_processor: スクリプトの作業ディレクトリを設定します。


# 関連ファイルやログがここに配置されることが期待されます。

WorkingDirectory=/opt/json_processor

# ExecStart=/opt/json_processor/process_json_data.sh: 実行するスクリプトへのフルパスを指定します。


# スクリプトは実行可能権限 (chmod +x) が必要です。

ExecStart=/opt/json_processor/process_json_data.sh

# Restart=on-failure: スクリプトがエラー終了した場合 (終了コードが0以外)、systemdが自動的に再起動を試みます。


# これは一時的な問題に対する回復力を提供します。

Restart=on-failure

# RestartSec=30s: Restart=on-failure が設定されている場合、再起動を試みるまでの待機時間。

RestartSec=30s

# StandardOutput=journal, StandardError=journal: スクリプトの標準出力と標準エラーをsystemdジャーナルに送ります。


# これにより、集中ログ管理が可能となり、journalctlコマンドで簡単にログを確認できます。

StandardOutput=journal
StandardError=journal

# PrivateTmp=true: サービス専用の一時名前空間を作成します。


# これにより、サービスが /tmp や /var/tmp に作成するファイルが他のサービスやシステムから隔離され、


# セキュリティが向上し、クリーンアップも容易になります。

PrivateTmp=true

[Install]

# WantedBy=multi-user.target: このサービスが multi-user.target に依存することを意味します。


# systemctl enable コマンドでサービスを有効化すると、このターゲットにシンボリックリンクが作成され、


# システム起動時に自動的にサービスが開始されるようになります (タイマー経由で実行されるため、直接WantedByは不要な場合も多い)。


# このケースではタイマーから起動されるため、直接有効化することはありません。

2.2. Timerユニット (.timer)

json-processor.timerを/etc/systemd/system/に作成します。

# /etc/systemd/system/json-processor.timer

[Unit]
Description=Run JSON Data Processor every 5 minutes

# Requires=json-processor.service: このタイマーが json-processor.service に依存することを意味します。


# タイマーを有効化する際に、対応するサービスも有効化されます。

Requires=json-processor.service

[Timer]

# OnCalendar=*:0/5:00: 5分ごとに実行するスケジュールを設定します。


# フォーマットは 'DayOfWeek Year-Month-Day Hour:Minute:Second' です。


# *:0/5:00 は、毎時0分、5分、10分... のように5分間隔で実行されます。


# これは正確に5分間隔ではなく、システムのクロックが5分ごとのタイミングに到達したときに実行されます。

OnCalendar=*:0/5:00

# RandomizedDelaySec=30s: スケジュールされた実行時刻に最大30秒のランダムな遅延を追加します。


# これにより、複数のタイマーが同時に起動してシステムに負荷をかけるのを防ぎます。

RandomizedDelaySec=30s

# Persistent=true: タイマーが最後に起動するはずだった時刻を記録します。


# システムがダウンしていた場合、起動後にその間の実行を補完します。

Persistent=true

# Unit=json-processor.service: このタイマーが起動するサービスユニットの名前を指定します。


# これにより、タイマーがトリガーされると json-processor.service が実行されます。

Unit=json-processor.service

[Install]

# WantedBy=timers.target: このタイマーが timers.target に依存することを意味します。


# systemctl enable コマンドでタイマーを有効化すると、システム起動時に自動的にタイマーが開始されるようになります。

WantedBy=timers.target

3. systemdユニットの有効化と開始 (root権限が必要)

スクリプトファイルを適切な場所に配置し、実行権限を付与します。

sudo mkdir -p /opt/json_processor
sudo cp process_json_data.sh /opt/json_processor/
sudo chmod +x /opt/json_processor/process_json_data.sh
sudo chown jsonproc:jsonproc_group /opt/json_processor/process_json_data.sh

systemdの定義ファイルをリロードし、タイマーを有効化して開始します。

# systemdに新しいユニットファイルを認識させる

sudo systemctl daemon-reload

# タイマーを有効化 (システム起動時に自動的に開始されるように)

sudo systemctl enable json-processor.timer

# タイマーを今すぐ開始

sudo systemctl start json-processor.timer

検証

1. タイマーのステータス確認

タイマーが正しく動作しているか確認します。

systemctl status json-processor.timer

# Expected output:


#   Loaded: loaded (/etc/systemd/system/json-processor.timer; enabled; vendor preset: enabled)


#   Active: active (waiting) since Mon 2024-07-29 10:00:00 JST; 1min ago


#     ...


#   Next: Mon 2024-07-29 10:05:00 JST; 3min 30s left

2. サービス実行の確認

タイマーによってサービスが起動されたことを確認します。

systemctl status json-processor.service

# Expected output:


#   Loaded: loaded (/etc/systemd/system/json-processor.service; static; vendor preset: enabled)


#   Active: inactive (dead) since Mon 2024-07-29 10:00:15 JST; 1min 45s ago


#   ...


#   Main PID: 1234 (code=exited, status=0/SUCCESS)

inactive (dead)はType=oneshotのサービスが正常に完了したことを示します。

3. ログの確認

journalctlコマンドでサービスのログを確認します。

journalctl -u json-processor.service --since "10 minutes ago"

# Expected output:


#   ...


#   Jul 29 10:00:05 hostname process_json_data.sh[1234]: [INFO] 2024-07-29 10:00:05 JST - Temporary directory created: /tmp/json_processor_XXXXXX


#   Jul 29 10:00:06 hostname process_json_data.sh[1234]: [INFO] 2024-07-29 10:00:06 JST - Fetching data from API: https://jsonplaceholder.typicode.com/posts


#   Jul 29 10:00:08 hostname process_json_data.sh[1234]: [INFO] 2024-07-29 10:00:08 JST - Processing JSON data with jq.


#   Jul 29 10:00:09 hostname process_json_data.sh[1234]: [INFO] 2024-07-29 10:00:09 JST - Saving processed data to: /var/lib/json_processor_data/processed_data_20240729100009.json


#   Jul 29 10:00:10 hostname process_json_data.sh[1234]: [INFO] 2024-07-29 10:00:10 JST - JSON processing completed successfully.

スクリプト内でtee -a "${LOG_FILE}"を使用しているため、/var/log/json_processor/json_processor.logにもログが出力されます。

4. 出力ファイルの確認

処理されたJSONファイルが指定されたディレクトリに保存されているか確認します。

sudo ls -l /var/lib/json_processor_data/

# Expected output:


#   -rw-r----- 1 jsonproc jsonproc_group 12345 2024-07-29 10:00 processed_data_20240729100009.json

sudo cat /var/lib/json_processor_data/processed_data_*.json | head -n 5

# Expected output:


#   [


#     {


#       "item_id": 1,


#       "item_title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit"


#     },


#     {


#       "item_id": 2,


#       "item_title": "qui est esse"


#     },


#   ...

運用

監視とアラート

  • systemdのログ（journalctl）をログ集約システム（例: Elasticsearch, Splunk, Loki）に転送し、エラーや異常な挙動を監視します。

  • サービスが失敗した場合（Restart=on-failureで再試行後も）、アラート通知（例: Slack, PagerDuty）をDevOpsチームに送信するように設定します。

設定管理

  • APIエンドポイントや出力パスなどの設定値は、環境変数または設定ファイルで管理し、スクリプトにハードコードしないようにします。systemdサービスファイル内でEnvironment=ディレクティブを使用することも可能です。

スケーラビリティとパフォーマンス

  • 処理対象のJSONデータが非常に大規模になる場合、jqの--streamオプションを利用してメモリ消費を抑える、またはより高性能なデータ処理フレームワーク（例: GoやPythonスクリプト）への移行を検討します。

  • curlのリトライ戦略はAPI側のレートリミットや一時的なネットワーク障害に対応しますが、頻繁な失敗が続く場合はAPI側の負荷状況を確認する必要があります。

トラブルシュート

スクリプトが実行されない

  • systemctl status json-processor.timerでタイマーの状態を確認し、Active: active (waiting)とNext:の時刻が正しいか確認します。

  • sudo systemctl daemon-reloadを実行したか確認します。

  • スクリプトパスが正しいか、実行権限（chmod +x）があるか、ユーザー（jsonproc）がスクリプトを読み取れるか確認します。

スクリプトがエラーで終了する

  • journalctl -u json-processor.service -eで最新のログを確認し、エラーメッセージを特定します。

  • curlのエラーであれば、APIエンドポイントの到達性、ネットワーク接続、認証情報、API側の問題などを確認します。

  • jqのエラーであれば、入力JSONの形式が期待通りか、jqのフィルタ式が正しいかを確認します。一時ファイルに保存されたAPI応答を確認するとデバッグに役立ちます。

  • 権限不足の場合、User=やGroup=で指定したユーザーがOUTPUT_DIRやLOG_FILEに書き込み権限を持っているか確認します。

出力ファイルが作成されない、または内容が空

  • スクリプト内のパス（OUTPUT_DIR）が正しいか確認します。

  • jq処理が失敗していないか、journalctlで確認します。

  • APIからデータが取得できているか、_TMP_DIR/api_response.jsonの内容を確認します（スクリプト実行直後に問題が発生した場合）。

まとめ

、jqとcurlを用いたJSON処理の自動化について、DevOpsの観点から堅牢なシステム構築方法を解説しました。安全なBashスクリプトの書き方、systemdによるジョブ管理、そして権限分離の重要性を示すことで、安定性と信頼性の高い自動化プロセスを実現できます。

  • 安全なBashスクリプト: set -euo pipefail、trap、mktemp -d を利用し、堅牢なスクリプトを作成しました。curlのTLS検証とリトライ戦略により、ネットワークの信頼性を高めました。

  • systemdによる自動化: Type=oneshotの.serviceユニットとOnCalendarで定期実行する.timerユニットを設定し、ジョブのスケジューリングと実行を一元管理しました。

  • 権限分離: 専用の非特権ユーザーアカウント（jsonproc）でスクリプトを実行することで、セキュリティリスクを最小限に抑えました。

  • ログと監視: journalctlとスクリプト内のtee -aによりログを適切に管理し、運用における監視とトラブルシューティングの基盤を構築しました。

これらの実践を通じて、DevOpsエンジニアは効率的かつ信頼性の高い自動化ワークフローを構築し、システムの運用負荷を軽減することができます。

文書情報

記事タイトル
jqとcurlを用いたJSON処理自動化：DevOpsエンジニアのための堅牢な実践
作成日
更新日
Source URL
https://papanda925.com/?p=4060

ライセンス: 本記事のうち、当サイトが権利を有する本文・自作図表は、特記なき限り CC BY 4.0 で利用できます。生成AIを活用して作成・編集した内容を含みます。コードについて、別途ライセンス表示またはリンク先GitHubリポジトリのライセンスがある場合は、その条件を優先します。引用・第三者資料・画像・商標等は本ライセンスの対象外です。 利用ポリシー

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