Google Apps Scriptを使ってBacklogのプロジェクト作成をもっと便利に［REST API / スプレッドシート操作］ - Qiita のTrello編

タスク管理のTrelloのUI/UXが面白くて、これも業務で試せないかなと思って、他のツールのAPIと並行していくつか調べてみました。

で、REST APIの実行という点では、Backlogのときはスプレッドシート+GASで試して、過去にはGoogleフォトのときはcurl、チャットワークのときはPython(ただし2.7)だったので、今回はPowerShellで試してみました。

(ちなみにGoogleフォトは最終的にPowerShellでツール化して、今回のTrelloについては結局スプレッドシート＋GASでツール化しました)

PowerShellのバージョンは5.1(Windows 10 home)

ちなみに、PowerShellでHTTPアクセスするためのInvoke-WebRequestについては以下にもまとめてるので、ご参考
curl/PowerShellでHTTPアクセスいろいろ - Qiita

API Document

Trello Developersから。

"Get Started In Under 5 Minutes"(5分ではじめよっ！)ってあるけど、これはREST APIじゃなくてPower-Upっぽい。

上部の[API Docs]のリンクを開けばAPIの一覧が見れる。

準備

API Keyの作成

APIキーはスクリプトに紐づくキー

API Keyのリンクを開く。

開発者契約(英語)を確認し、チェックを入れて「APIキーを表示」を押下すると、生成されたAPI Keyが表示される。

API Tokenの作成

APIトークンは、スクリプトを使用するユーザ毎に取得するトークン。
API実行時はこのトークンを取得したユーザ権限で動作する。

ローカルテスティング用の手動トークン作成のリンク

となってるので、account権限を外して

こんな感じのURLで、Trelloにログインしている状態でブラウザでアクセスする。($API_KEYのとこは取得したAPIキーの文字列)
nameのところは、トークンを取得するユーザが「見たときにわかりやすいもの」を設定すればよい。

するとこのAPIキーを使用したアプリケーションを使用してもよいかの確認が表示されるので「許可」する。

すると、トークンが表示されるので、このテキストをメモする。

これでAPIの実行に必要なAPI KeyとAPI Tokenが取得できた。

APIの実行

API DocsのAPI Key & Tokensから。

自分のユーザIDを取得するには？？？

「自分のユーザIDを取得するAPI」はない。替わりにmeを指定すればよい。
(REST API的によくある設定パターンなのかな？確かMattermostもこういう仕様だったような)

ボード一覧の取得(curl編)

APIはMembersのboardsを使用。
日本語のエンコード状態がどうなってるか見るには、勝手にエンコードされたりしないcurlが結局一番かもしれない笑

zaki@mascarpone% curl -sS "https://api.trello.com/1/members/me/boards?key=${API_KEY}&token=${API_TOKEN}&fields=name" | python -m json.tool 
[
    {
        "id": "5cc3933dda8c9901496f1aec",
        "name": "zaki\u30bf\u30b9\u30af"
    },
    :
    :
]

日本語はUnicodeのコードポイント方式でGoogleフォトと一緒かな？

ユーザIDを指定する場合は、meのところにユーザIDを指定

zaki@mascarpone% curl -sS "https://api.trello.com/1/members/${USER_ID}/boards?key=${API_KEY}&token=${API_TOKEN}&fields=name" | python -m json.tool 
[
    {
        "id": "5cc3933dda8c9901496f1aec",
        "name": "zaki\u30bf\u30b9\u30af"
    },
    :
    :
]

APIの実行(PowerShell編)

ここから本題

参照系

ボード一覧の取得

上記のcurlと同等の処理をPowerShellから実行するには、Invoke-RestMethodを使ってこんな感じ

$base_url = "https://api.trello.com/1"
$api_key = "********"
$api_token = "********"

$boads_url = $base_url + "/members/me/boards?key=" + $api_key + "&token=" + $api_token
$resp = Invoke-RestMethod $boads_url

これで$respに、JSON形式のレスポンスがオブジェクト化(連想配列)されてセットされる。
$resp | ConvertTo-JsonすればJSONの構造がわかりやすい。

取得できるボード情報については、リンクが見当たらなくてちょっとあれ？って思ったけど、Board Objectに載ってる

指定ボードのリスト一覧の取得

BoardsのAPIの"lists"機能から。
指定のボードは前述のボード一覧取得などからあらかじめ特定しておく。

$base_url = "https://api.trello.com/1"
$api_key = "********"
$api_token = "********"
$board_id = ****

$lists_url = $base_url + "/boards/" + $board_id + "/lists?key=" + $api_key + "&token=" + $api_token
$list_resp = Invoke-RestMethod $lists_url

これで$list_respにJSON形式でリスト一覧がセットされる。
リストの形式はList Objectから。

ConvertTo-Jsonするとこんな感じ。

PS C:\Users\zaki\src\trello\ps1> $list_resp | ConvertTo-Json
[
    {
        "id":  "5cd428573041d96b6e9670d2",
        "name":  "◆pickup◆",
        "closed":  false,
        "idBoard":  "5cc3933dda8c9901496f1aec",
        "pos":  0.5,
        "subscribed":  false,
        "softLimit":  null
    },
    {
        "id":  "5cc3933d59e30b084e1c2d72",
        "name":  "するべきこと",
        "closed":  false,
        "idBoard":  "5cc3933dda8c9901496f1aec",
        "pos":  1,
        "subscribed":  false,
        "softLimit":  null
    },
    :
    :
]

指定ボードの全カード取得

ボード上の全カードを取得するのであれば、[BoardsのAPIの"cards"機能]から。
リスト一覧取得同様、指定のボードIDはあらかじめ取得しておく。

$base_url = "https://api.trello.com/1"
$api_key = "********"
$api_token = "********"

$cards_url = $base_url + "/boards/" + $board_id + "/cards?key=" + $api_key + "&token=" + $api_token
$cards_resp = Invoke-RestMethod $cards_url

リスト一覧同様、$cards_respにJSON形式のカード一覧がセットされる。
カードの形式はCard Object参照。

指定リストのカード一覧

リスト一覧取得で取得したリストのIDがあれば、そのリスト内のカード一覧だけ取得することもできる。

$base_url = "https://api.trello.com/1"
$api_key = "********"
$api_token = "********"
$list_id = ********

$card_in_list_url = $base_url + "/lists/" + $list_id + "/cards?key=" + $api_key + "&token=" + $api_token
$card_in_list_resp = Invoke-RestMethod $card_in_list_url

登録系

先に日本語のエンコードについて書いておくと、前述のcurlのレスポンス的にはUTF-16のコードポイントで指定するように見えるけど、2019年5月の時点ではUTF-8の文字列をただURLエスケープしただけでPOSTして大丈夫だった。

で、PowerShellのInvoke-RestMethodとInvoke-WebRequestは(全バージョンを調べたわけじゃないけど、少なくともwin10標準のPowerShell5.1では)ソースコードのエンコードがShift_JISでもHTTPリクエスト時にはUTF-8でURLエスケープしてくれるので、特に何も考えずに日本語の引数を指定すればTrello的には問題ない。

新規ボードの作成

ボードを新しく作成するには、Boardsの/boards/のPOSTを使う。

Query Paramsがいろいろあるが、ボードを作成するのに最低限必要なのは

$base_url = "https://api.trello.com/1"
$api_key = "********"
$api_token = "********"

$board_name = "サンプルボード"

$create_board_url = $base_url + "/boards?name=" + $board_name + "&key=" + $api_key + "&token=" + $api_token
$create_board_resp = Invoke-RestMethod $create_board_url -Method Post

レスポンスは

PS C:\Users\zaki\src\trello\ps1> $create_board_resp


id             : 5ce11e359ce2422ed908369f
name           : サンプルボード
desc           : 
descData       : 
closed         : False
idOrganization : 
pinned         : False
url            : https://trello.com/b/79K4qbRR/%E3%82%B5%E3%83%B3%E3%83%97%E3%83%AB%E3%83%9C%E3%83%BC%E3%83%89
shortUrl       : https://trello.com/b/79K4qbRR
prefs          : @{permissionLevel=private; voting=disabled; comments=members; invitations=members; selfJoin=True; cardCovers=True; isTemplate=False; cardAging=regul
                 ar; calendarFeedEnabled=False; background=blue; backgroundImage=; backgroundImageScaled=; backgroundTile=False; backgroundBrightness=dark; backgroun
                 dColor=#0079BF; backgroundBottomColor=#0079BF; backgroundTopColor=#0079BF; canBePublic=True; canBeEnterprise=True; canBeOrg=True; canBePrivate=True;
                  canInvite=True}
labelNames     : @{green=; yellow=; orange=; red=; purple=; blue=; sky=; lime=; pink=; black=}
limits         :

Trelloで見るとこんな感じ。作成できてる。というか、「デフォルトのリスト」も作成されてる。(これどこに設定あるかわからなかった…)

主要なパラメタ

デフォルトのリストを作成しない
- Query ParamsにdefaultLists=falseを追加
背景色を指定したい
- prefs_background=***を追加。指定できる背景色は
  
  The id of a custom background or one of: blue, orange, green, red, purple, pink, lime, sky, grey.
  
  とあるが、それ以外に背景画像IDの指定もできた。
  背景画像IDの取得は…わからん。。どこかにあるかもしれないけど、背景設定済みボードのボード情報を取得すれば、prefs.backgroundにセットされてるのでそれ参照
「このボードについて」のテキストを設定
- desc=********を追加。ここに指定したテキストがそのまま「このボードについて」に設定される

新規リストの作成

リスト作成のボードIDを指定して、Listsの"/lists"のPOSTを使う。

$base_url = "https://api.trello.com/1"
$api_key = "********"
$api_token = "********"

$board_id = ******
$list_name = "優先タスク"

$create_list_url = $base_url + "/lists?name=" + $list_name + "&idBoard=" + $board_id + "&pos=bottom&key=" + $api_key + "&token=" + $api_token
$create_list_resp = Invoke-RestMethod $create_list_url -Method Post

前述の「ボード作成」の例であれば、レスポンスのボードIDは5ce11e359ce2422ed908369fになっているので、これを指定すればこんな感じ

レスポンスは以下の通り。

PS C:\Users\zaki\src\trello\ps1> $create_list_resp


id      : 5ce1276eb20290533b2c888e
name    : 優先タスク
closed  : False
idBoard : 5ce11e359ce2422ed908369f
pos     : 65536
limits  :

posについては

top, bottom, or a positive floating point number

とあるが、topを指定すれば左端、bottomで右端になる。
リストの作成は1個ずつしかできないので、ボード作成時に複数のリストをまとめてドンと作りたい場合は、ループで処理すればまぁ問題ないかと。

メンバーの招待

チーム機能を使おう！
ということなんだろうけど、いろんな事情でユーザ指定で招待して共有したい場合。

Boardsの/boards/{id}/membersにPUTを使って、これもAPIで実行できる。

$base_url = "https://api.trello.com/1"
$api_key = "********"
$api_token = "********"

$board_id = ******
$email_addr = "zaki-lknr@example.org"

$url = $base_url + "/boards/" + $board_id + "/members?email=" + $email_addr + "&key=" + $api_key + "&token=" + $api_token
$resp = Invoke-RestMethod $url -Method Put -Headers @{type = "normal"}

ポイントは

メソッドはPUT
招待するユーザのアドレスはQuery Stirngに指定
対象ユーザの権限はHTTPヘッダで指定(typeにnormalかadminを指定)
招待済みのユーザに対する再実行は問題ない(権限が更新されると思えばいい)
ボードのオーナーのアドレスを指定すると403エラー("Not enough admins"と出力される)になるので注意

実行すると、処理対象のボードIDと、membersのリストと、membershipsのリストが返る。
membersはこちら
membershipsはどこにドキュメントあるかわからん。。

PowerShell単体だと使う人(非技術者を想定)にはまだちょっと不親切なので、Excelで作った作成対象ボード一覧とかリスト一覧とか招待するユーザ一覧とかを用意して、PowerShellのCOMからExcel操作してファイル読み込んでスクリプト実行、みたいにすれば便利になると思う。
PowerShell で Excel をどうのこうのすることに興味を持ってくれると嬉しい - Qiita