まず1ページだけ取ってみる

PART 02 で環境変数を設定してある前提で進める。最初に、課題一覧を5件だけ取ってみる。

bash(Linux / macOS / WSL)

bash
PID=$(curl -sS -H "Backlog-API-Key: $BACKLOG_API_KEY" \
  "https://$BACKLOG_HOST/api/v2/projects/$BACKLOG_PROJECT_KEY" | jq '.id')

curl -sS -g -H "Backlog-API-Key: $BACKLOG_API_KEY" \
  "https://$BACKLOG_HOST/api/v2/issues?projectId[]=$PID&count=5" \
  | jq -r '.[] | [.issueKey, .status.name, .summary] | @tsv'
出力例
DEV-128	処理中	ログイン画面のレイアウト崩れ
DEV-127	未対応	CSV出力の文字化け
DEV-126	完了	月次バッチの実行時間短縮
…

-g を忘れない。curl は URL の [] を「連番の展開」として解釈するため、-g(--globoff)を付けないと projectId[] がエラーになる。

PowerShell

PowerShell
$h = @{ 'Backlog-API-Key' = $env:BACKLOG_API_KEY }
$base = "https://$env:BACKLOG_HOST/api/v2"
$project = Invoke-RestMethod "$base/projects/$env:BACKLOG_PROJECT_KEY" -Headers $h
$issues = Invoke-RestMethod "$base/issues?projectId[]=$($project.id)&count=5" -Headers $h
$issues | Select-Object issueKey, @{n='status'; e={$_.status.name}}, summary

PowerShell の文字列の中では [] は特別な意味を持たないので、そのまま書いてよい。ただし & を含む URL は必ず "..." で囲む。

bash+jq で全件を CSV にする

PART 04 のお題 を bash で書く。JSON の加工には jq を使う(Ubuntu / WSL なら sudo apt install jq)。

bash(backlog_issues.sh)
#!/usr/bin/env bash
# 指定プロジェクトの未完了課題を CSV に出力する
set -euo pipefail

BASE="https://${BACKLOG_HOST}/api/v2"
KEY="${BACKLOG_PROJECT_KEY}"
OUT="issues_${KEY}.csv"

api() {  # api パス [クエリ]  → 本文を標準出力へ。429 なら60秒待って再試行
  local url="${BASE}/$1${2:+?$2}" body code
  for i in 1 2 3 4 5; do
    body=$(curl -sS -g -w '\n%{http_code}' -H "Backlog-API-Key: ${BACKLOG_API_KEY}" "$url")
    code=${body##*$'\n'}; body=${body%$'\n'*}
    if [[ "$code" == 200 ]]; then printf '%s' "$body"; return 0; fi
    if [[ "$code" == 429 || "$code" -ge 500 ]]; then
      echo "HTTP $code: ${i}回目。待って再試行します" >&2; sleep 60; continue
    fi
    echo "HTTP $code: $(jq -r '.errors[0].message // .' <<<"$body")" >&2; return 1
  done
  return 1
}

PID=$(api "projects/${KEY}" | jq '.id')
# 「完了」(ID 4) 以外の状態を statusId[]=… の形に
STATUS_Q=$(api "projects/${KEY}/statuses" | jq -r '[.[] | select(.id != 4) | "statusId[]=\(.id)"] | join("&")')

tmp=$(mktemp)
offset=0
while :; do
  page=$(api "issues" "projectId[]=${PID}&${STATUS_Q}&sort=created&order=asc&count=100&offset=${offset}")
  jq -c '.[]' <<<"$page" >> "$tmp"
  n=$(jq 'length' <<<"$page")
  echo "offset=${offset}: ${n}件" >&2
  (( n < 100 )) && break
  offset=$(( offset + 100 ))
done

{
  printf '\xEF\xBB\xBF'   # Excel で開くための UTF-8 BOM
  echo '課題キー,件名,状態,担当者,期限日,予定時間,実績時間'
  jq -rs 'unique_by(.id)[] | [
      .issueKey, .summary, .status.name,
      (.assignee.name // "(未割り当て)"),
      ((.dueDate // "")[:10]),
      (.estimatedHours // ""), (.actualHours // "")
    ] | @csv' "$tmp"
} > "$OUT"

echo "出力: $OUT($(jq -s 'unique_by(.id) | length' "$tmp")件)"
echo '--- 担当者別 ---'
jq -rs 'unique_by(.id) | group_by(.assignee.name // "(未割り当て)")
        | map({name: (.[0].assignee.name // "(未割り当て)"), n: length})
        | sort_by(-.n)[] | "\(.n)\t\(.name)"' "$tmp"
rm -f "$tmp"

// "…" は「左側が null なら右側の値を使う」という jq の書き方で、担当者や期限日が未設定の課題に対応している。@csv は件名にカンマや " が含まれていても正しくクォートしてくれる。

PowerShell 版の方針

Windows で日常的に使うなら PowerShell 版が便利だ。次の方針で書く。

  • Invoke-RestMethod ではなく Invoke-WebRequest を使う:レスポンスヘッダー(X-RateLimit-Remaining など)を見るため
  • 本文は UTF-8 として自分でデコードする:環境によって日本語が化けるのを防ぐ
  • Windows PowerShell 5.1 と PowerShell 7 の両方で動かす:違いは 後述

PowerShell スクリプト全体

PowerShell(Get-BacklogIssues.ps1)
<#
  指定プロジェクトの未完了課題を CSV に出力し、担当者別の件数を表示する
  例) .\Get-BacklogIssues.ps1 -ProjectKey DEV
#>
param(
    [string]$ProjectKey = $env:BACKLOG_PROJECT_KEY,
    [string]$OutFile = ".\issues_$ProjectKey.csv"
)
$ErrorActionPreference = 'Stop'
$BaseUrl = "https://$env:BACKLOG_HOST/api/v2"
$Headers = @{ 'Backlog-API-Key' = $env:BACKLOG_API_KEY }

function Get-HeaderValue($res, [string]$name) {
    # 5.1 は文字列、7 は文字列の配列で返るので、先頭の1つを取り出す
    $v = $res.Headers[$name]
    if ($null -eq $v) { return $null }
    return [string]($v | Select-Object -First 1)
}

function Invoke-Backlog {
    param([string]$Path, [string[]]$Query = @())
    $uri = "$BaseUrl/$Path"
    if ($Query.Count -gt 0) { $uri += '?' + ($Query -join '&') }

    for ($i = 1; $i -le 5; $i++) {
        try {
            $res = Invoke-WebRequest -Uri $uri -Headers $Headers -UseBasicParsing
        }
        catch {
            $code = 0
            if ($_.Exception.Response) { $code = [int]$_.Exception.Response.StatusCode }
            if ($code -eq 429 -or $code -ge 500 -or $code -eq 0) {
                Write-Warning "HTTP $code ($i 回目)。60秒待って再試行します"
                Start-Sleep -Seconds 60
                continue
            }
            $msg = $_.ErrorDetails.Message
            try { $msg = ($msg | ConvertFrom-Json).errors[0].message } catch { }
            throw "HTTP $code : $msg ($uri)"
        }

        # 残りが少なければ、リセット時刻まで先回りして待つ
        $remaining = Get-HeaderValue $res 'X-RateLimit-Remaining'
        $reset = Get-HeaderValue $res 'X-RateLimit-Reset'
        if ($remaining -and [int]$remaining -le 1 -and $reset) {
            $wait = [long]$reset - [DateTimeOffset]::UtcNow.ToUnixTimeSeconds() + 1
            if ($wait -gt 0) { Write-Host "レート制限の残りが少ないため $wait 秒待ちます"; Start-Sleep -Seconds $wait }
        }

        $text = [Text.Encoding]::UTF8.GetString($res.RawContentStream.ToArray())
        $data = $text | ConvertFrom-Json
        return $data   # 配列は1件ずつパイプラインに流れる
    }
    throw "再試行の上限に達しました ($uri)"
}

function Get-BacklogAll {
    param([string]$Path, [string[]]$Query = @())
    $all = New-Object System.Collections.Generic.List[object]
    $offset = 0
    while ($true) {
        $page = @(Invoke-Backlog $Path ($Query + @('count=100', "offset=$offset")))
        foreach ($x in $page) { $all.Add($x) }
        Write-Host "offset=$offset : $($page.Count) 件"
        if ($page.Count -lt 100) { break }
        $offset += 100
    }
    return $all
}

function ConvertTo-Jst($value, [string]$Format = 'yyyy-MM-dd HH:mm') {
    # PowerShell 7 は日時を自動で DateTime に変換するため、文字列と両方に対応する
    if ($null -eq $value -or "$value" -eq '') { return '' }
    if ($value -is [datetime]) { $utc = $value.ToUniversalTime() }
    else { $utc = [DateTimeOffset]::Parse([string]$value).UtcDateTime }
    return $utc.AddHours(9).ToString($Format)
}

# ① プロジェクトID
$project = Invoke-Backlog "projects/$ProjectKey"
# ② 「完了」(ID 4) 以外の状態ID
$statusQuery = @(Invoke-Backlog "projects/$ProjectKey/statuses" |
    Where-Object { $_.id -ne 4 } |
    ForEach-Object { "statusId[]=$($_.id)" })
# ③ 課題を全件取得(登録日時の昇順で固定)
$issues = Get-BacklogAll 'issues' (@("projectId[]=$($project.id)", 'sort=created', 'order=asc') + $statusQuery)
$issues = $issues | Sort-Object id -Unique

# ④ CSV に出力
$rows = foreach ($i in $issues) {
    [pscustomobject][ordered]@{
        '課題キー' = $i.issueKey
        '件名'     = $i.summary
        '状態'     = $i.status.name
        '担当者'   = $(if ($i.assignee) { $i.assignee.name } else { '(未割り当て)' })
        '期限日'   = ConvertTo-Jst $i.dueDate 'yyyy-MM-dd'
        '予定時間' = $i.estimatedHours
        '実績時間' = $i.actualHours
        '更新日時' = ConvertTo-Jst $i.updated
    }
}
$encoding = if ($PSVersionTable.PSVersion.Major -ge 6) { 'utf8BOM' } else { 'UTF8' }
$rows | Export-Csv -Path $OutFile -NoTypeInformation -Encoding $encoding
Write-Host "出力: $OutFile ($(@($rows).Count) 件)"

# ⑤ 担当者別の件数
$rows | Group-Object '担当者' | Sort-Object Count -Descending |
    Format-Table @{n='件数'; e={$_.Count}}, @{n='担当者'; e={$_.Name}} -AutoSize

⚠️ スクリプトは「UTF-8(BOM 付き)」で保存する

Windows PowerShell 5.1 は、BOM のない .ps1 ファイルを Shift_JIS として読む。日本語の列名('課題キー' など)を含むスクリプトを BOM なしの UTF-8 で保存すると、文字化けしたりエラーになったりする。VS Code なら右下の「UTF-8」をクリックし、「エンコード付きで保存」→「UTF-8 with BOM」を選ぶ。

実行と結果

PowerShell
.\Get-BacklogIssues.ps1 -ProjectKey DEV
出力例
offset=0 : 100 件
offset=100 : 100 件
offset=200 : 37 件
出力: .\issues_DEV.csv (237 件)

件数 担当者
---- ------
  64 佐藤 花子
  51 山田 太郎
  48 鈴木 一郎
  41 (未割り当て)
  33 高橋 次郎

「このシステムではスクリプトの実行が無効になっている」と表示される場合は、その PowerShell のウィンドウだけ実行を許可する。

PowerShell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned

出力した CSV はダブルクリックで Excel で開ける。BOM 付きの UTF-8 にしてあるので、日本語も化けない。

Windows PowerShell 5.1 と PowerShell 7 の違い

Windows に最初から入っているのは Windows PowerShell 5.1(powershell.exe)で、別途インストールするのが PowerShell 7(pwsh.exe)だ。Backlog API を扱うときに影響する違いは次のとおりで、上のスクリプトはどちらでも動くように書いてある。

項目Windows PowerShell 5.1PowerShell 7スクリプトでの対処
.ps1 の既定の文字コードShift_JIS(BOM なしの場合)UTF-8UTF-8(BOM 付き)で保存する
Export-Csv -Encoding UTF8BOM 付きBOM なし(Excel で化ける)7 では utf8BOM を指定
ConvertFrom-Json の日時文字列のままDateTime に自動変換ConvertTo-Jst で両方を受け付ける
レスポンスヘッダーの値文字列文字列の配列Get-HeaderValue で先頭を取り出す
-UseBasicParsing指定しないと IE のエンジンを使おうとする常にこの動作(指定しても無視)常に指定する

応用:条件を変える

$Query に渡す配列を変えれば、絞り込みを自由に変えられる。

やりたいこと追加するクエリ
自分が担当の課題だけ"assigneeId[]=$((Invoke-Backlog 'users/myself').id)"
期限切れの課題だけ"dueDateUntil=$((Get-Date).AddDays(-1).ToString('yyyy-MM-dd'))"
今週更新された課題"updatedSince=$((Get-Date).AddDays(-7).ToString('yyyy-MM-dd'))"
キーワードを含む課題"keyword=$([uri]::EscapeDataString('ログイン'))"
親課題だけ(子課題を除く)'parentChild=1'

日本語を含む値は [uri]::EscapeDataString() で URL エンコードしてから渡す。

つまずきやすい点

症状原因と対処
curl で bad range in URL-g を付けていない
件数が20件しか取れないcount=100 を付けていない、またはページネーションをしていない
CSV を Excel で開くと文字化けするBOM なしの UTF-8 で出力している。PowerShell 7 では -Encoding utf8BOM
PowerShell 7 で Substring のエラー日時が DateTime に変換されている。ConvertTo-Jst のように型を見て処理する
列名が文字化けする、構文エラーになる.ps1 を BOM なしで保存し、5.1 で実行している
カスタム状態の課題が出てこない状態IDを 1〜3 で決め打ちしている。状態一覧から集める

✅ 次の記事では…

PART 06 では、同じお題を Excel VBA で実装し、ボタン1つでシートに課題一覧を展開するブックを作る。

→ PART 06 — Excel VBAで取得するへ