jqコマンドを活用したDevOpsにおけるJSONデータ処理と自動化

Tech

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

jqコマンドを活用したDevOpsにおけるJSONデータ処理と自動化

DevOpsの現場では、API連携、設定管理、ログ解析など、様々な場面でJSONデータを扱う機会が頻繁に発生します。本記事では、強力なJSONプロセッサであるjqコマンドを中心に、安全で冪等なBashスクリプト、堅牢なAPI通信のためのcurl、そして定期実行のためのsystemdを組み合わせたJSONデータ処理の自動化手法について解説します。

要件と前提

本記事で解説する自動化スクリプトおよび設定は、以下の要件と前提に基づいています。

  1. 冪等性: スクリプトは何回実行されても同じ結果を返し、システムの現在の状態に影響を与えないように設計されます。

  2. 安全性: 不意のエラーやパイプラインの失敗にも対応し、一時ファイルの適切な管理や、root権限の乱用を防ぐ設計をします。

  3. 可読性と保守性: スクリプトや設定ファイルは明確で理解しやすいように記述します。

  4. 必要なツール: jq、curl、systemdが対象システムにインストールされていることを前提とします。

実装

処理フローの概要（Mermaid図）

JSONデータの取得から処理、結果の出力/送信までの一連のフローを以下に示します。

graph TD
    A["開始"] --> B{"JSONデータの取得"};
    B -- HTTPS/Retry --> C("curlでAPIから取得");
    C --> D{"取得データの検証/整形"};
    D -- jqでフィルタリング/変換 --> E("処理済みJSONデータ");
    E -- ログ出力/ファイル保存 --> F("結果の永続化");
    F --> G["終了"];

安全なBashスクリプトのフレームワーク

set -euo pipefailを使い、エラーが発生した場合にスクリプトが即座に終了するようにします。また、一時ディレクトリを安全に作成し、trapを用いてスクリプト終了時に必ずクリーンアップするようにします。

#!/bin/bash


# process_json_data.sh

# 厳格なエラーハンドリングとパイプラインの失敗検出

set -euo pipefail

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


# JST 2024年7月29日時点の一般的な方法 [1]

TMP_DIR=$(mktemp -d -t json_proc_XXXXXXXX)
log_file="${TMP_DIR}/process_log.txt"
output_file="${TMP_DIR}/processed_data.json"

# スクリプト終了時に一時ファイルを削除するためのトラップ

trap 'echo "Cleaning up temporary directory: ${TMP_DIR}"; rm -rf "${TMP_DIR}"' ERR EXIT

echo "$(date '+%Y-%m-%d %H:%M:%S JST') - INFO: Script started." | tee -a "${log_file}"
echo "$(date '+%Y-%m-%d %H:%M:%S JST') - INFO: Temporary directory created: ${TMP_DIR}" | tee -a "${log_file}"

# ここに具体的なJSON処理ロジックを記述


# ...

echo "$(date '+%Y-%m-%d %H:%M:%S JST') - INFO: Script finished successfully." | tee -a "${log_file}"

# 例として最終的なログと出力ファイルを表示 (本番では不要な場合が多い)

echo "--- Log Content ---"
cat "${log_file}"
echo "--- Output Content (if any) ---"
[ -f "${output_file}" ] && cat "${output_file}" || echo "No output file generated."

curlを用いたAPI連携

curlコマンドでJSONデータを取得する際、TLS検証を適切に行い、ネットワークの一時的な問題に対応するための再試行（リトライ）と指数バックオフを実装します。

#!/bin/bash


# fetch_data_with_curl.sh (上記のprocess_json_data.sh内で使用する想定)

# APIからJSONデータを安全に取得する関数


# 引数: URL, 出力ファイルパス

fetch_json_data() {
    local url="$1"
    local output_path="$2"
    local max_retries=5
    local delay_seconds=2 # 初期遅延秒数

    echo "$(date '+%Y-%m-%d %H:%M:%S JST') - INFO: Fetching data from: ${url}" | tee -a "${log_file}"

    # curlの主要オプション [2][3]


    # --fail-with-body: HTTPエラー時にレスポンスボディも表示


    # --location: リダイレクトを追跡


    # --retry: リトライ回数


    # --retry-delay: リトライ間の初期遅延（秒）


    # --retry-max-time: リトライ試行の合計最大時間（秒）


    # --cacert: CA証明書バンドルのパス (システムデフォルトを使う場合は省略可)


    # --connect-timeout: 接続試行の最大時間


    # --max-time: 全処理の最大時間

    if ! curl -sS \
              --fail-with-body \
              --location \
              --retry "${max_retries}" \
              --retry-delay "${delay_seconds}" \
              --retry-max-time $((delay_seconds * max_retries * 2)) \
              --connect-timeout 10 \
              --max-time 30 \
              --header "Accept: application/json" \
              --cacert /etc/ssl/certs/ca-certificates.crt \
              "${url}" -o "${output_path}" 2>> "${log_file}"; then
        echo "$(date '+%Y-%m-%d %H:%M:%S JST') - ERROR: Failed to fetch data from ${url} after multiple retries." | tee -a "${log_file}"
        return 1
    fi

    echo "$(date '+%Y-%m-%d %H:%M:%S JST') - INFO: Data successfully fetched to: ${output_path}" | tee -a "${log_file}"
    return 0
}

# 使用例 (この部分はprocess_json_data.shの「具体的なJSON処理ロジック」内に記述)


# API_URL="https://api.example.com/data"


# RAW_DATA_FILE="${TMP_DIR}/raw_data.json"


# if ! fetch_json_data "${API_URL}" "${RAW_DATA_FILE}"; then


#    echo "Data fetching failed. Exiting." | tee -a "${log_file}"


#    exit 1


# fi

curlのリリースは 2024年6月12日にv8.8.0が公開されていますが、上記のオプションは長期にわたり安定しています [4]。

jqを用いたJSONデータ処理

取得したJSONデータから必要な情報を抽出し、変換する例です。

#!/bin/bash


# process_data_with_jq.sh (上記のprocess_json_data.sh内で使用する想定)

# JSONデータをjqで処理する関数


# 引数: 入力ファイルパス, 出力ファイルパス

process_json_with_jq() {
    local input_path="$1"
    local output_path="$2"

    echo "$(date '+%Y-%m-%d %H:%M:%S JST') - INFO: Processing JSON data from: ${input_path}" | tee -a "${log_file}"

    # jqコマンドの例 [5]


    # 1. 特定のキーを抽出し、新しいオブジェクトの配列を生成


    #    入力: [{"id": 1, "name": "A", "value": 10}, {"id": 2, "name": "B", "value": 20}]


    #    出力: [{"item_id": 1, "item_name": "A"}, {"item_id": 2, "item_name": "B"}]

    #


    # 2. 条件に基づいてフィルタリングし、特定のフィールドの合計を計算


    #    入力: 上記と同じ


    #    出力: 30 (valueが15未満の合計)

    if ! jq '[ .[] | {item_id: .id, item_name: .name} ]' "${input_path}" > "${output_path}"; then
        echo "$(date '+%Y-%m-%d %H:%M:%S JST') - ERROR: jq processing failed for extraction." | tee -a "${log_file}"
        return 1
    fi
    echo "$(date '+%Y-%m-%d %H:%M:%S JST') - INFO: Initial jq processing completed. Output to ${output_path}" | tee -a "${log_file}"

    # 例: フィルタリングと合計

    local total_value
    total_value=$(jq '[ .[] | select(.value < 15) | .value ] | add' "${input_path}")
    echo "$(date '+%Y-%m-%d %H:%M:%S JST') - INFO: Total value for items less than 15: ${total_value}" | tee -a "${log_file}"

    return 0
}

# 使用例 (この部分はprocess_json_data.shの「具体的なJSON処理ロジック」内に記述)


# RAW_DATA_FILE="${TMP_DIR}/raw_data.json"


# PROCESSED_DATA_FILE="${TMP_DIR}/processed_data.json"

#


# # ダミーデータ作成（テスト用）


# echo '[{"id": 1, "name": "ItemA", "value": 10}, {"id": 2, "name": "ItemB", "value": 20}, {"id": 3, "name": "ItemC", "value": 5}]' > "${RAW_DATA_FILE}"

#


# if ! process_json_with_jq "${RAW_DATA_FILE}" "${PROCESSED_DATA_FILE}"; then


#     echo "JSON processing failed. Exiting." | tee -a "${log_file}"


#     exit 1


# fi

systemdによる自動化

上記のスクリプトを定期的に実行するためにsystemdのUnitとTimerファイルを活用します。systemdは 2024年5月30日にv256がリリースされましたが、基本的な設定方法は安定しています [6]。

ここでは、json_processor.serviceとjson_processor.timerを作成します。

1. サービスファイル (/etc/systemd/system/json_processor.service)

[Unit]
Description=JSON Data Processor Service
Documentation=https://example.com/docs/json_processor
After=network.target

[Service]

# このサービスを実行するユーザーを指定。セキュリティ強化のためroot以外を推奨。

User=json_processor_user
Group=json_processor_group

# スクリプトの作業ディレクトリを指定

WorkingDirectory=/opt/json_processor

# サービスタイプをoneshotに設定 (コマンドが終了するとサービスも終了)

Type=oneshot

# コマンドの実行パス。安全なBashスクリプトへのフルパスを指定。

ExecStart=/bin/bash /opt/json_processor/process_json_data.sh

# サービスが終了してもsystemdがその状態を保持 (timerとの連携に便利)

RemainAfterExit=yes

# 標準出力と標準エラーをjournaldにリダイレクト

StandardOutput=journal
StandardError=journal

[Install]

# このサービスはタイマーによって起動されるため、WantedByにはtimers.targetを指定

WantedBy=timers.target

2. タイマーファイル (/etc/systemd/system/json_processor.timer)

[Unit]
Description=Run JSON Data Processor every 15 minutes
Requires=json_processor.service

[Timer]

# サービスの起動頻度を設定 (例: 15分ごと) [7]

OnCalendar=*:0/15

# システム起動時の過去の実行を見逃しても、起動時にすぐに実行する

Persistent=true

# 起動するサービスユニット

Unit=json_processor.service

[Install]

# タイマーを有効化することで、システム起動時に自動的に起動される

WantedBy=multi-user.target

配置と有効化

  1. 上記のスクリプトファイル (process_json_data.sh、fetch_data_with_curl.sh、process_data_with_jq.sh) を /opt/json_processor/ ディレクトリに配置します。

  2. json_processor_userとjson_processor_groupを作成し、process_json_data.shの実行権限を与えます。

    sudo groupadd json_processor_group
sudo useradd -r -g json_processor_group -s /sbin/nologin json_processor_user
sudo mkdir -p /opt/json_processor
sudo cp process_json_data.sh /opt/json_processor/

# fetch_data_with_curl.sh と process_data_with_jq.sh も必要に応じて配置

sudo chown -R json_processor_user:json_processor_group /opt/json_processor
sudo chmod u+x /opt/json_processor/process_json_data.sh

  3. .serviceファイルと.timerファイルを/etc/systemd/system/に配置します。

  4. systemdのデーモンをリロードし、タイマーを有効化します。

    sudo systemctl daemon-reload
sudo systemctl enable json_processor.timer
sudo systemctl start json_processor.timer

  5. ステータスとログを確認します。

    systemctl status json_processor.timer
systemctl status json_processor.service
journalctl -u json_processor.service

検証

  1. スクリプト単体での実行: json_processor_userで直接スクリプトを実行し、意図した動作とエラー処理が行われるか確認します。

    sudo -u json_processor_user /opt/json_processor/process_json_data.sh

  2. systemdタイマーの動作確認:

    • systemctl status json_processor.timerでタイマーがアクティブになっていることを確認。

    • journalctl -u json_processor.timerでタイマーの起動ログを確認。

    • journalctl -u json_processor.serviceでサービスがタイマーによって実行された際のログを確認し、処理が成功しているか、またはエラーが発生しているかを確認します。

運用

Root権限の扱いと権限分離

本ガイドでは、systemdサービス内でUser=json_processor_userを指定することで、root権限から分離した専用ユーザーでスクリプトを実行しています。これはセキュリティ上非常に重要です。

  • 最小権限の原則: json_processor_userは、スクリプト実行に必要な最小限のファイルアクセス権限のみを持つべきです。

  • ホームディレクトリの制限: nologinシェルを指定することで、インタラクティブログインを防ぎます。

  • 一時ファイルの場所: mktempで作成される一時ディレクトリは、そのユーザーが書き込み権限を持つ場所 (例: /tmpやユーザーのホームディレクトリ下の作業ディレクトリ) に配置されるべきです。

ログ監視

systemdのStandardOutputとStandardErrorをjournalに設定することで、すべての出力はjournaldに集約されます。

  • journalctl -u json_processor.service --since "1 hour ago": 過去1時間のエラーや実行状況を確認。

  • ログ監視ツール（Prometheus+Loki, ELK Stack, Splunkなど）と連携し、異常を検知した際にアラートを通知する仕組みを構築します。

トラブルシュート

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

    • systemctl status json_processor.timerやjson_processor.serviceで状態を確認。

    • sudo systemctl daemon-reload後、systemctl restart json_processor.timerを試す。

    • json_processor_userにスクリプトの実行権限があるか確認する (chmod u+x)。

  • jqのエラー:

    • jqの入力JSONが不正な形式でないか確認します (jq . your_file.jsonで検証)。

    • jqフィルタの構文が正しいか確認します。jqのエラーメッセージは比較的詳細です。

  • curlのエラー:

    • journalctl -u json_processor.serviceでcurlの出力（--fail-with-bodyや--verboseを追加して再試行）を確認し、HTTPステータスコードやエラーメッセージを特定します。

    • ネットワーク接続、APIのエンドポイント、認証情報、CA証明書のパスを確認します。

  • 権限エラー:

    • json_processor_userがアクセスしようとしているファイルやディレクトリに対して、適切な読み書き権限を持っているか確認します。

まとめ

、jqを用いたJSONデータの処理、curlによる堅牢なAPI連携、そしてsystemdによる定期的な自動実行を組み合わせたDevOpsにおける実践的なアプローチを紹介しました。安全なBashスクリプトのベストプラクティスを取り入れ、root権限の分離を徹底することで、安定した自動化ワークフローを構築できます。これらの手法は、ログ解析、設定同期、データ変換など、多岐にわたるDevOpsタスクに応用可能です。

参考文献: [1] GNU Project. “Bash Reference Manual.” 最終アクセス日: 2024年7月29日. URL: https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html [2] curl project. “curl man page.” 最終アクセス日: 2024年7月29日. URL: https://curl.se/docs/manpage.html [3] curl project. “SSL CA Certificates.” 最終アクセス日: 2024年7月29日. URL: https://curl.se/docs/ssl-certs.html [4] curl project. “Download wizard.” 2024年6月12日 v8.8.0リリース. 最終アクセス日: 2024年7月29日. URL: https://curl.se/download.html [5] Stedolan et al. “jq Manual.” 最終アクセス日: 2024年7月29日. URL: https://stedolan.github.io/jq/manual/ [6] systemd project. “Releases.” 2024年5月30日 v256リリース. 最終アクセス日: 2024年7月29日. URL: https://github.com/systemd/systemd/releases [7] FreeDesktop.org. “systemd.timer(5).” 最終アクセス日: 2024年7月29日. URL: https://www.freedesktop.org/software/systemd/man/systemd.timer.html

ライセンス：本記事のテキスト/コードは特記なき限り CC BY 4.0 です。引用の際は出典URL（本ページ）を明記してください。
利用ポリシー もご参照ください。

コメント

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