まず1ページだけ取ってみる
PART 02 で環境変数を設定してある前提で進める。最初に、課題一覧を5件だけ取ってみる。
bash(Linux / macOS / WSL)
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
$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}}, summaryPowerShell の文字列の中では [] は特別な意味を持たないので、そのまま書いてよい。ただし & を含む URL は必ず "..." で囲む。
bash+jq で全件を CSV にする
PART 04 のお題 を bash で書く。JSON の加工には jq を使う(Ubuntu / WSL なら sudo apt install jq)。
#!/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 スクリプト全体
<#
指定プロジェクトの未完了課題を 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」を選ぶ。
実行と結果
.\Get-BacklogIssues.ps1 -ProjectKey DEVoffset=0 : 100 件
offset=100 : 100 件
offset=200 : 37 件
出力: .\issues_DEV.csv (237 件)
件数 担当者
---- ------
64 佐藤 花子
51 山田 太郎
48 鈴木 一郎
41 (未割り当て)
33 高橋 次郎「このシステムではスクリプトの実行が無効になっている」と表示される場合は、その 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.1 | PowerShell 7 | スクリプトでの対処 |
|---|---|---|---|
| .ps1 の既定の文字コード | Shift_JIS(BOM なしの場合) | UTF-8 | UTF-8(BOM 付き)で保存する |
Export-Csv -Encoding UTF8 | BOM 付き | 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 で決め打ちしている。状態一覧から集める |