Backlog プロジェクト内のファイル一覧を Backlog API で取得してみた

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

Backlog では ファイル を利用できます。ここでの「ファイル」を、課題や WIki への添付ファイルと区別するために、以降は共有ファイルと呼びます。

共有ファイルとして保存したデータは、Backlog画面の「ファイル」から確認したり、課題や WIki からリンクできます。

プランによって保存できる容量に上限があることもあり、共有ファイルのデータ容量を気にする機会があるかと思います。Backlog 画面から都度ディレクトリを深掘って確認していくのは手間がかかるので、Backlog API を使って一括で一覧取得する Bash スクリプトを作ってみました。

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 プロジェクト内のファイルを一覧取得するスクリプト

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

#!/bin/bash

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

API_ENDPOINT="https://${BACKLOG_DOMAIN}/api/v2/projects/${PROJECT_ID}/files/metadata"

# APIからJSONデータを取得する関数
fetch_json() {
    local api_url="$1"
    # URL内のスペースを %20 にエンコード
    local encoded_url=$(echo "$api_url" | sed 's/ /%20/g')
    curl -s -X GET "${encoded_url}?apiKey=${API_KEY}"
}

# ディレクトリ一覧用の変数にルートをあらかじめ格納
directories=("/")

# ディレクトリの一覧を取得する関数
get_directories() {
    local current_path="$1"
    local dir_list=$(fetch_json "${API_ENDPOINT}${current_path}" | jq -r '.[] | select(.type == "directory") | .name')
    while IFS= read -r dir_name; do
        if [[ -n "$dir_name" ]]; then
            local full_path="${current_path}${dir_name}/"
            directories+=("$full_path")
            get_directories "$full_path"
        fi
    done <<< "$dir_list"
}

# ファイルメタデータの一覧を取得する関数
get_files_metadata() {
    for dir in "${directories[@]}"; do
        fetch_json "${API_ENDPOINT}${dir}" | jq -r '.[] | select(.type == "file") | [.dir[0:30], .name[0:30], .size, .created] | @tsv'
    done
}

# ファイル一覧を出力する関数
print_file_list() {
    local file_list=$(get_files_metadata)
    case "$1" 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\t%s\n", $1, $2, $3 / 1024 / 1024, $4}' | column -t -s $'\t' ;;
        *) echo "Invalid option. Please provide a valid output format option (1, 2, or 3)." ;;
    esac
}

# 初期パスを設定
initial_path="/"

# ディレクトリ一覧の取得の実行
echo "ディレクトリ一覧を取得します。"
get_directories "$initial_path"
echo "ディレクトリ一覧を取得しました。"

# ファイル一覧の出力の実行
echo "ファイル一覧を出力します。"
# 出力オプションを選択: 1 (標準), 2 (ファイルサイズ順), 3 (ファイルサイズ順でMBに変換)
print_file_list 1

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

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

• ディレクトリ
• ファイル名
• サイズ（byte）
• 作成日時

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

# ファイル一覧の出力の実行
echo "ファイル一覧を出力します。"
# 出力オプションを選択: 1 (標準), 2 (ファイルサイズ順), 3 (ファイルサイズ順でMBに変換)
print_file_list 1

1. 標準（ディレクトリ名で降順）
2. ファイルサイズ順で降順
3. ファイルサイズ順で降順の上で単位を MB に変換

スクリプトの解説

使用している Backlog API は以下です。

ここではディレクトリのパスを指定することで、そのパス直下のディレクトリやファイルを一覧表示できます。

[ 
    { 
        "id": 825952, 
        "projectId": 5,
        "type": "file", 
        "dir": "/プレスリリース/20091130/", 
        "name": "20091130.txt", 
        "size": 4836, 
        "createdUser": { 
            "id": 1, 
            "userId": "admin", 
            "name": "admin", 
            "roleType": 1, 
            "lang": "ja", 
            "nulabAccount": {
                "nulabId": "Prm9ZD9DQD5snNWcSYSwZiQoA9WFBUEa2ySznrSnSQRhdC2X8G",
                "name": "admin",
                "uniqueId": "admin"
            },
            "mailAddress": "[email protected]", 
            "lastLoginTime": "2022-09-01T06:35:39Z"
        }, 
        "created": "2009-11-30T01:22:21Z", 
        "updatedUser": null, 
        "updated": "2009-11-30T01:22:21Z" 
    }, 
    ... 
] 

まずget_directories()関数で再帰的に一覧を取得し、取得した一覧に対してそれぞれget_files_metadata()関数でファイルを取得するようにしています。

ディレクトリ名、ファイル名が長い場合に備えて、以下のように jq で先頭30文字に切り詰める処理を入れています。

jq -r '.[] | select(.type == "file") | [.dir[0:30], .name[0:30], .size, .created] | @tsv'

全量が必要な場合には、[0:30]の部分を取り除いてください。

ちょっとハマったところ

この API の実行先 URL は以下で、:pathにはディレクトリのパスを入れます。

/api/v2/projects/:projectIdOrKey/files/metadata/:path

ディレクトリ名は日本語でも特に問題ありませんが、スペースが入っていると cURL の実行に失敗します。そのため、半角スペースが入っている場合は%20に置換する処理を入れました。

終わりに

Backlog プロジェクト内の共有ファイル一覧を一括で取得するスクリプトのご紹介でした。

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

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

関連

参考

• Backlog API とは | Backlog Developer API | Nulab