jqでAPIのJSON配列を安全に処理する ― select・?・//で欠損値に強くする

この記事について
この記事は、生成AIを活用した自動生成フローで作成しています。jqの標準的な配列・null処理とcurl/bashのエラー処理を見直し、旧記事のダミーAPIキーや壊れやすい一時ファイル処理を修正しました。

検証ステータス：✅ コマンド構造を再確認・安全側へ修正

APIからJSONを取得してjqで絞り込む処理は短く書けます。しかし実運用では、「配列がない」「tagsがnull」「APIキーを入れ忘れた」「HTTP 500なのにJSONとして処理した」といった例外への備えが重要です。

例：Activeかつcriticalタグを持たないリソース

次のJSONを想定します。

{
  "resources": [
    {"id": 101, "status": "Active", "name": "ServerA", "tags": ["prod"]},
    {"id": 102, "status": "Inactive", "name": "ServerB", "tags": ["prod"]},
    {"id": 103, "status": "Active", "name": "ServerC", "tags": ["critical"]},
    {"id": 104, "status": "Active", "name": null}
  ]
}

抽出は次のように書けます。

jq -r '
  .resources[]?
  | select(.status == "Active")
  | select((.tags // []) | index("critical") | not)
  | [.id, (.name // "NO_NAME_PROVIDED")]
  | @csv
' response.json

出力例：

101,"ServerA"
104,"NO_NAME_PROVIDED"

[]?で配列欠損に耐える

.resources[]は、resourcesが存在しない・配列でない場合にエラーになることがあります。.resources[]?とすると、存在しない値に対してエラーを出さずにスキップできます。

ただし「resourcesが必須」というAPI仕様なら、黙ってスキップするより先に構造を検証する方が安全です。

jq -e '.resources | type == "array"' response.json >/dev/null

//でnullや欠損の既定値を作る

.tags // []は、tagsがnullまたは存在しない場合に空配列として扱います。.name // "NO_NAME_PROVIDED"も同じ考え方です。

APIデータは「常に完全」と考えず、欠損時の扱いをフィルターの中に明示しておくと保守しやすくなります。

API取得まで含めた安全な最小スクリプト

#!/usr/bin/env bash
set -euo pipefail

: "${API_ENDPOINT:?API_ENDPOINT is required}"
: "${API_KEY:?API_KEY is required}"

tmp="$(mktemp)"
trap 'rm -f "$tmp"' EXIT

curl \
  --fail-with-body \
  --silent \
  --show-error \
  --location \
  -H "Authorization: Bearer ${API_KEY}" \
  "$API_ENDPOINT" \
  -o "$tmp"

jq -e '.resources | type == "array"' "$tmp" >/dev/null

jq -r '
  .resources[]?
  | select(.status == "Active")
  | select((.tags // []) | index("critical") | not)
  | [.id, (.name // "NO_NAME_PROVIDED")]
  | @csv
' "$tmp"

旧コードから変えたポイント

systemdで回す場合

定期実行なら、標準出力と標準エラーをjournaldで確認できます。ただしAPIキーをコマンドラインやログへ出さないようにします。

journalctl -u inventory-sync.service --since "10 minutes ago" --no-pager

自動処理では、成功時の件数、失敗理由、取得日時をログへ残すと、API側の仕様変更にも気付きやすくなります。

参考情報

• jq Manual
• curl man page
• GNU Bash Reference Manual

この記事の更新履歴

• 2026-09-14 追加：[]?、//、@csv、JSON構造検証、mktempの実用例を追加。
• 2026-09-14 変更：API処理を正常系中心から、欠損値・HTTPエラー・未設定シークレットに強い構成へ変更。
• 2026-09-14 削除：内部メタデータ/style_prompt、本文H1、DUMMY_KEYフォールバック、手作り一時ファイル名を削除。