Backlog の Wiki 一覧と Wiki 添付ファイル一覧を Backlog API で一括取得してみた

コンバンハ、千葉（幸）です。

Backlog では Wiki を利用できます。Wiki は階層構造を取ることができ、Backlog 画面の右側で以下のように構造を確認できます。

階層構造は折りたたまれて表現されているため、全量を確認するにはそれぞれを展開して確認が必要です。もっと手軽に全体構造を把握したいと考えました。

また、Wiki にはファイルを添付できます。あらかじめアップロードされた「共有ファイル」へのリンクを張るのとは別に、Wiki ページ自体にファイルを添付できます。

プランによって保存できる容量に上限があることもあり、添付ファイルのデータ容量を気にする機会があるかと思います。Wiki の個別のページを1つずつ添付ファイルを確認していくのは手間がかかるので、Wiki に添付されたファイル一覧を取得したいと考えました。

上記を Backlog API を用いて実現する方法を確認してみました。

Backlog API 利用に向けた前提知識と準備

今回のブログで用いるコマンド/スクリプトでは、以下の情報を必要とします。事前に発行/確認を行なってください。

• Backlog スペース ID
• Backlog プロジェクト ID
• Backlog API キー

Backlog スペース ID

Backlog はスペースの中に複数のプロジェクトを作成して利用します。個々のスペースは、xxx.backlog.jpといった URL で分けられています。xxxに該当するのがスペース ID です。

Backlog プロジェクト ID

いくつかの Backlog API ではプロジェクト IDの指定を必要とします。ホーム画面で確認できる「プロジェクト名」や「プロジェクトキー」とは別物です。

Backlog画面の「プロジェクト設定」を開いた時の URL の末尾に表示されている 10 桁の数字が該当します。

https://xxx.backlog.jp/ViewPermission.action?projectId=0000000000

Backlog API キー

Backlog API を利用するための認証に必要です。API キーはプロジェクト単位で個別で用意するものではなく、スペース単位で共通のものです。

API キーを払い出したら、API のリクエスト URL に?apiKey=abcdefghijklmn...の形式でパラメータとして付与することで認証が行えます。

本ブログのコマンド/スクリプトの基本情報

• 動作確認環境
  • macOS Sonoma 14.2.1
  • zsh
• 必要ツール
  • jq

Backlog プロジェクト内の Wiki を一覧表示するコマンド

実行するのは以下の Backlog API です。

コマンドを実行する前に、必要な情報を環境変数に設定します。

# 必要な情報を設定
BACKLOG_DOMAIN="xxx.backlog.jp" # xxxをスペースIDに置き換え
PROJECT_ID="0000000000" # プロジェクトIDに置き換え
API_KEY="zzzz..." # APIキーに置き換え
API_ENDPOINT="https://${BACKLOG_DOMAIN}/api/v2/wikis"

その後、Backlog API を実行します。ここでは、「Wiki ID」「Wiki 名（60文字に切り詰め）」「作成日時」「更新日時」を取得してみました。

curl -s -X GET "${API_ENDPOINT}?apiKey=${API_KEY}&projectIdOrKey=${PROJECT_ID}"\
 | jq -r '.[] | [.id,.name[0:60],.created,.updated] | @tsv' | column -t -s $'\t'

出力イメージは以下です。ここでは作成日時で昇順に並んでいます。

Wiki 名でソートしたい場合は、以下のように実行します。

curl -s -X GET "${API_ENDPOINT}?apiKey=${API_KEY}&projectIdOrKey=${PROJECT_ID}"\
 | jq -r 'sort_by(.name) | .[] | [.id,.name[0:60],.created,.updated] | @tsv' | column -t -s $'\t'

Backlog プロジェクト内の Wiki の添付ファイルを一覧表示するスクリプト

添付ファイルまで取得しようと思うとコマンドで組み立てるのは大変そうだったので、スクリプトを作成しました。

冒頭の必要情報を置き換えて実行してください。

#!/bin/bash

# 必要な情報を設定
BACKLOG_DOMAIN="xxx.backlog.jp" # xxxをスペースIDに置き換え
PROJECT_ID="0000000000" # プロジェクトIDに置き換え
API_KEY="zzzz..." # APIキーに置き換え

API_ENDPOINT="https://${BACKLOG_DOMAIN}/api/v2/wikis"

# Wiki IDと名前の取得
echo "Wikiの情報を取得します。"
wiki_data=$(curl -s -X GET "${API_ENDPOINT}?apiKey=${API_KEY}&projectIdOrKey=${PROJECT_ID}" | jq -r '.[] | "\(.id):\(.name)"')

# Wiki添付ファイルを取得する関数
get_attached_files() {
    attached_file_list=""
    local IFS=$'\n'
    for wiki in $wiki_data; do
        id=${wiki%%:*} # Wiki IDを抽出
        name=${wiki#*:} # Wiki名を抽出
        # Wiki名を先頭30文字に切り詰め
        short_name=${name:0:30}
        # Wiki IDを使って添付ファイルリストを取得し、短縮されたWiki名を挿入
        curl -s -X GET "${API_ENDPOINT}/${id}/attachments?apiKey=${API_KEY}" | jq -r --arg wiki_name "$short_name" '.[] | [$wiki_name, .name[0:30], .size] | @tsv' > temp_file.txt
        while IFS= read -r line; do
            # 最初の行でなければ、先に改行を追加する
            if [[ -n $attached_file_list ]]; then
                attached_file_list+=$'\n'
            fi
            attached_file_list+="$line"
        done < temp_file.txt
    done
    rm temp_file.txt # 一時ファイルを削除
    echo "$attached_file_list"
}

# ファイル一覧を出力する関数
print_file_list() {
    local file_list="$1" # 引数からファイルリストを受け取る
    case "$2" in # 第二引数で出力オプションを指定
        1) echo "$file_list" | column -t -s $'\t' ;;
        2) echo "$file_list" | sort -t$'\t' -k3,3nr | column -t -s $'\t' ;;
        3) echo "$file_list" | sort -t$'\t' -k3,3nr | awk -F $'\t' '{printf "%s\t%s\t%.2f MB\n", $1, $2, $3 / 1024 / 1024}' | column -t -s $'\t' ;;
        *) echo "Invalid option. Please provide a valid output format option (1, 2, or 3)." ;;
    esac
}

# Wikiの添付ファイル一覧の取得
echo "Wikiの添付ファイルの情報を取得します。"
attached_file_list=$(get_attached_files) # 関数の結果を変数に格納

# Wikiの添付ファイル一覧の出力の実行
echo "Wikiの添付ファイルの情報を出力します。"
# 第二引数で出力オプションを指定してファイルリストを出力: 1 (標準), 2 (ファイルサイズ順), 3 (ファイルサイズ順でMBに変換)
print_file_list "$attached_file_list" 1

実行した際の出力イメージは以下です。

Wiki の添付ファイル一覧として以下がタブ区切りで出力されます。

• Wiki ページ名
• ファイル名
• サイズ（byte）

スクリプト末尾で指定するオプションによって細部を変更できます。

# Wikiの添付ファイル一覧の出力の実行
echo "Wikiの添付ファイルの情報を出力します。"
# 第二引数で出力オプションを指定してファイルリストを出力: 1 (標準), 2 (ファイルサイズ順), 3 (ファイルサイズ順でMBに変換)
print_file_list "$attached_file_list" 1

1. 標準（Wikiの作成日時で昇順）
2. ファイルサイズ順で降順
3. ファイルサイズ順で降順の上で単位を MB に変換

スクリプトの解説

使用している Backlog API は 2 種類あります。

ひとつは先ほどコマンドで用いたもので、これにより「Wiki ID」と「Wiki名」を取得しています。

その後、Wiki IDを指定して以下の Backlog API を繰り返し実行します。

以下のように Wiki 添付ファイルの詳細を取得できます。

リファレンスより引用

[ 
    { 
        "id": 1, 
        "name": "IMGP0088.JPG", 
        "size": 85079 
    }, 
    ... 
]

ここではどの Wiki に添付されているかの情報が含まれていないため、あらかじめ保有していたリストから「Wiki IDに紐づく Wiki 名」を挿入するようにしています。

具体的には以下の部分です。jq で--argオプションを使用することによって変数を渡せることを知りました。

jq -r --arg wiki_name "$short_name" '.[] | [$wiki_name, .name[0:30], .size] | @tsv'

Wiki 名やファイル名は 30 文字で切り詰めしているので、全量が必要な場合には適宜修正してご利用ください。

終わりに

Backlog プロジェクト内の Wiki 一覧、および Wiki の添付ファイル一覧を一括で取得する方法のご紹介でした。

ひとまずやりたいことを満たすために突貫で作ったものなので、環境が異なるとうまく動かない場合もあります。細部をカスタマイズしてご利用ください。

以上、 チバユキ (@batchicchi) がお送りしました。

関連

参考

• Backlog API とは | Backlog Developer API | Nulab