PowerShell から Backlog API を呼び出して課題を登録する #PowerShell

Backlog を利用していて、複数件の課題を手作業で登録するのが手間だったため、スクリプトとして処理できるようにしました。

環境

PS> $PSVersionTable

Name                           Value
----                           -----
PSVersion                      6.2.2
PSEdition                      Core
GitCommitId                    6.2.2
OS                             Microsoft Windows 10.0.18362
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

API 仕様を確認

まず、Backlog API のリファレンスを確認します。

Backlog ユーザーの認証方法として、ここでは API キーを利用しています。リファレンスに従い、Backlog の個人設定から API キー文字列を発行しておいてください。

送信パラメーターの概要

上記リファレンスにより、課題登録のために必須のパラメーターは以下であることがわかります。

パラメーター名	型	内容
projectId	数値	課題を登録するプロジェクトのID
summary	文字列	課題の件名
issueTypeId	数値	課題の種別のID
priorityId	数値	課題の優先度のID

projectId は利用している Backlog スペース内のプロジェクトの ID で、画面上から確認できるプロジェクト名とは異なります。summary は課題の件名を表します。

このほか issueTypeId は課題のカテゴリーを、priorityId は課題の優先度を表しています。summary の項目以外は、数値で表される ID を指定するところに注意が必要です。

各 ID は以下の API から確認することができます。

サンプルコード

これらのパラメーターを設定し、PowerShell から Backlog API へ課題を登録するサンプルが以下になります。

function New-Issue {
  param (
    $Space,
    $ApiKey,
    $ProjectId,
    $IssueTypeId,
    $PriorityId,
    $Summary
  )

  $body = @{
    projectId   = $ProjectId;
    summary     = $Summary;
    issueTypeId = $IssueTypeId;
    priorityId  = $PriorityId;
  }

  $api = 'issues'
  $url = "https://$Space.backlog.jp/api/v2/$($api)?apiKey=$ApiKey"

  # 課題の作成に成功すると 201 (Created) が返ってくる
  (Invoke-WebRequest $url -Method Post -Body $body).StatusCode
}

# 使用例
New-Issue -Space 'myspace' -ApiKey 'xXxXxXx' -ProjectId 123456 -IssueTypeId 999999 -PriorityId 3 -Summary 'test task'

New-Issue 関数に渡した各種パラメーターをもとに、任意の Backlog プロジェクトへ Post しています。必要に応じて、API リファレンスを参考にパラメーターを追加してください。

SSL 通信のエラーが原因で Invoke-WebRequest が失敗する場合は、下記のスクリプトを実行して TLS 1.2 を有効化してみてください。

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12