シェルスクリプトでcurlとjqを使ってREST APIを自動操作する方法｜認証ヘッダー・エラー処理・ページング設計の実装パターン

この記事のポイント

・curl -s -oと-wでレスポンス本文とHTTPステータスコードを別々に受け取れる
・APIトークンはスクリプト内にハードコードせず環境変数かchmod 600ファイルで管理する
・HTTPステータスが4xx/5xxのときはスクリプトをexit 1で止める条件分岐が必須
・ページングはwhile true + 空配列でbreakの汎用パターンが実装しやすく可読性も高い

#!/bin/bash
# GitHub APIからリポジトリの基本情報を取得する例
ORG="torvalds"
REPO="linux"

curl -s \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/${ORG}/${REPO}" \
  | jq '.full_name, .description, .stargazers_count'

"torvalds/linux"
"Linux kernel source tree"
186462

#!/bin/bash
# Slack Incoming WebhookにPOSTする例
WEBHOOK_URL="${SLACK_WEBHOOK_URL}"
MESSAGE="バックアップ完了: $(date '+%Y-%m-%d %H:%M:%S')"

# jqの--argでJSONを安全に生成する（変数内の特殊文字を自動エスケープ）
PAYLOAD=$(jq -n --arg text "${MESSAGE}" '{text: $text}')

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d "${PAYLOAD}" \
  "${WEBHOOK_URL}"

#!/bin/bash
# GitHubのブランチ名を一覧取得する例
ORG="torvalds"
REPO="linux"

curl -s \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/${ORG}/${REPO}/branches?per_page=5" \
  | jq -r '.[].name'

master
linux-rolling-lts

#!/bin/bash
# スクリプト先頭でトークンの存在を確認する
if [[ -z "${GITHUB_TOKEN}" ]]; then
    echo "エラー: 環境変数 GITHUB_TOKEN が設定されていません" >&2
    exit 1
fi

curl -s \
  -H "Authorization: Bearer ${GITHUB_TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/user" \
  | jq '.login, .name'

#!/bin/bash
# トークンファイルから読み込む設計
TOKEN_FILE="${HOME}/.config/github_token"

if [[ ! -r "${TOKEN_FILE}" ]]; then
    echo "エラー: トークンファイルが見つかりません: ${TOKEN_FILE}" >&2
    exit 1
fi

API_TOKEN=$(< "${TOKEN_FILE}")

curl -s \
  -H "Authorization: Bearer ${API_TOKEN}" \
  "https://api.github.com/user"

# トークンファイルのパーミッションを設定する（所有者のみ読み取り可能）
chmod 600 ~/.config/github_token
ls -la ~/.config/github_token
# -rw------- 1 ec2-user ec2-user 41  8月  7 09:15 /home/ec2-user/.config/github_token

#!/bin/bash
# Basic認証を使うAPIの例
API_USER="${ZABBIX_USER}"
API_PASS="${ZABBIX_PASS}"

curl -s \
  -u "${API_USER}:${API_PASS}" \
  -H "Content-Type: application/json" \
  "https://zabbix.example.com/api_jsonrpc.php" \
  -d '{"jsonrpc":"2.0","method":"apiinfo.version","params":[],"id":1}' \
  | jq '.result'

#!/bin/bash
# レスポンスボディとHTTPステータスコードを分離して取得する
API_URL="https://api.github.com/repos/torvalds/linux"

TMP_FILE=$(mktemp)
# -o でボディをファイルへ、-w でステータスコードのみを変数に取り込む
HTTP_STATUS=$(curl -s \
  -H "Accept: application/vnd.github+json" \
  -o "${TMP_FILE}" \
  -w "%{http_code}" \
  "${API_URL}")

if [[ "${HTTP_STATUS}" -ge 200 && "${HTTP_STATUS}" -lt 300 ]]; then
    # 成功（2xx）: jqでレスポンスを解析する
    jq '.full_name, .stargazers_count' "${TMP_FILE}"
else
    # エラー（4xx/5xx）: ステータスコードとボディを stderr に出力
    echo "APIエラー: HTTP ${HTTP_STATUS}" >&2
    cat "${TMP_FILE}" >&2
    rm -f "${TMP_FILE}"
    exit 1
fi

rm -f "${TMP_FILE}"

APIエラー: HTTP 401
{"message":"Requires authentication","documentation_url":"https://docs.github.com/..."}

#!/bin/bash
# Bearer Token認証付きのGETリクエスト関数
api_get() {
    local url="$1"
    local tmp
    tmp=$(mktemp)

    local status
    status=$(curl -s \
      -H "Authorization: Bearer ${API_TOKEN}" \
      -H "Accept: application/vnd.github+json" \
      -o "${tmp}" \
      -w "%{http_code}" \
      "${url}")

    if [[ "${status}" -lt 200 || "${status}" -ge 300 ]]; then
        echo "API GET 失敗: HTTP ${status}  URL=${url}" >&2
        cat "${tmp}" >&2
        rm -f "${tmp}"
        return 1
    fi

    cat "${tmp}"
    rm -f "${tmp}"
    return 0
}

# 使用例：失敗時はそのままスクリプトを終了する
RESULT=$(api_get "https://api.github.com/orgs/torvalds/repos?per_page=5") || exit 1
echo "${RESULT}" | jq -r '.[].name'

#!/bin/bash
# pageパラメータで全件取得するパターン
fetch_all_items() {
    local base_url="$1"
    local per_page=100
    local page=1
    local all_results="[]"

    while true; do
        local result
        result=$(api_get "${base_url}?per_page=${per_page}&page=${page}")
        if [[ $? -ne 0 ]]; then
            echo "ページ ${page} の取得に失敗しました" >&2
            return 1
        fi

        # 空の配列（[]）が返ってきたらループ終了
        local count
        count=$(echo "${result}" | jq 'length')
        if [[ "${count}" -eq 0 ]]; then
            break
        fi

        # 取得結果を累積する
        all_results=$(echo "${all_results} ${result}" | jq -s 'add')
        page=$((page + 1))
    done

    echo "${all_results}"
}

# 使用例
ALL_REPOS=$(fetch_all_items "https://api.github.com/orgs/torvalds/repos") || exit 1
TOTAL=$(echo "${ALL_REPOS}" | jq 'length')
echo "合計: ${TOTAL} 件取得"
echo "${ALL_REPOS}" | jq -r '.[].name'

#!/bin/bash
# Linkヘッダーから次ページURLを抽出する関数
extract_next_url() {
    local link_header="$1"
    # rel="next" のURLを正規表現で取り出す
    echo "${link_header}" | grep -o '<[^>]*>; rel="next"' | sed 's/.*$//'
}

# Linkヘッダー方式での全件取得
fetch_all_with_link() {
    local url="$1"
    local all_results="[]"

    while [[ -n "${url}" ]]; do
        local tmp_body tmp_header
        tmp_body=$(mktemp)
        tmp_header=$(mktemp)

        local status
        status=$(curl -s \
          -H "Authorization: Bearer ${API_TOKEN}" \
          -H "Accept: application/vnd.github+json" \
          -D "${tmp_header}" \
          -o "${tmp_body}" \
          -w "%{http_code}" \
          "${url}")

        if [[ "${status}" -ge 400 ]]; then
            echo "エラー: HTTP ${status}" >&2
            rm -f "${tmp_body}" "${tmp_header}"
            return 1
        fi

        all_results=$(echo "${all_results} $(cat ${tmp_body})" | jq -s 'add')

        local link_header
        link_header=$(grep -i '^Link:' "${tmp_header}" | tr -d '\r')
        url=$(extract_next_url "${link_header}")

        rm -f "${tmp_body}" "${tmp_header}"
    done

    echo "${all_results}"
}