LoginSignup
3
2

More than 3 years have passed since last update.

@zaki-lknrin株式会社エーピーコミュニケーションズ

PowerShellからREST APIを使ってTrelloのボード作成をもっと便利に

Last updated at Posted at 2019-05-19

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でツール化しました:innocent:)

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のリンクを開く。

image.png

image.png

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

API Tokenの作成

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

image.png

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

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

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

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

image.png

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

image.png

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

image.png

主要なパラメタ

  • デフォルトのリストを作成しない
    • 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になっているので、これを指定すればこんな感じ

image.png

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

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

3
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
3
2