Zenn
📒

【Trello】Rest APIの備忘録

2021/12/12に公開
Trello
rest
tech

TrelloにはRest API(HTTPアクセスでリストやカードを操作する機能)が用意されている
CLIツールを作る上でTrelloの仕様を纏めて備忘録として載せていく

APIキーとトークンの発行

API Introductionの「Your First API Call」セクションでは
実際にcurlコマンドを使ったHTTPリクエストの例を紹介してくれている

curl 'https://api.trello.com/1/members/me/boards?key={yourKey}&token={yourToken}'

Rest APIを実行するにはAPIキーとトークンの2つが必要である事がわかる。
そしてその取得方法も記載されている

To get started, you’ll need an API key. You can get your API key by logging into Trello and visiting https://trello.com/app-key. Be sure to read and agree to Trello Developer Terms of Service. Your API key will be clearly labeled at the top of that page.

https://trello.com/app-keyページを訪問すると、
日本語のページが出現する(私の言語設定が日本語だったからだろうか？)
このページ内で発行出来るのはAPIキーのみ。

トークンを得る手段は別途認証機能を行うか、
手っ取り早く上記のAPIキーのページ内にある「手動でトークンを生成できます。」のリンクをクリックして払い出すかの二択のようだ。

今回私が作りたいのは自分のTrelloカードを確認する為のCLIツールなので
リンクをクリックしてトークンを払い出す事にした。

全体的な流れ

Rest APIでは基本的に下記のような階層構造になっている

  • Member: ユーザー自分自身、もし企業始動なら紐付いている複数ユーザーを操れる
    • Board
      • List
        • Card: コメントはこの中に内包されているようだ
      • Label: 各Cardに指定するラベル
      • Checklist: チェックリスト、Cardとはどちらも複数形指定するので多対多の関係

(他にもActionsやEnterprises、Emojiとか色々あるけど、Trello特化でもない限り不要なので割愛)

これを元にリファレンスを見ればRestful APIのCRUDなので一通り触れる。
知っておくとTrelloのRest APIを扱いやすくなる機能が2つある

  • 上の階層から子の一覧を取得出来るパラメータが存在する
  • MembersのIDでmeを指定すると自分自身が取得できる

API Introductionの「Your First API Call」に再度戻って
これでボードの一覧を取得してくださいという紹介がされている。

curl 'https://api.trello.com/1/members/me/boards?key={yourKey}&token={yourToken}'

「ボードの一覧が取得出来て良かったね」で流すには勿体ない。
私が注目したポイントは下記の2点

  • 自分自身のMember.idはmeで代用出来るので知る必要がない
  • 紐付いている親子のIDを元に実データまで引っ張ってこれる

後者に関してみていこう。
Reference/Members/Get Boards that Member belongs to
公式リファレンスによると、Memberに紐づくBoard一覧のエンドポイントには、
下記のパラメータをクエリストリングに含める事が可能となっている。

  • filter
  • fields
  • lists: Boardに紐づくListの一覧
  • organization
  • organization_fields

なんと1度のリクエストでMemberの2階層下にいるListの情報まで取得できてしまう。
取得したJSONの中身を見る限り普通の生データだ。

CLIツールを作る側としてはHTTPリクエストを何度も発射しまくることになるので、
階層の上下から引っ掛けられるということを意識しておくとリクエストの回数を劇的に減らせる可能性がある。
それを念頭に置きつつ設計を行いたい。

閲覧はこれだけ叩いてればOKじゃね？

最初に叩くcurl 'https://api.trello.com/1/members/me/boards?key={yourKey}&token={yourToken}'も異常に便利だったが、
後はこの辺が叩ければ閲覧用途だとやることがもうなくなってしまう。

  • Get a Member
    自分にアサインされたCardの一覧を全て取得できる
  • Get a Board
    紐付いているListとCardの一覧を全て取得できる

今回私が作ろうとしているCLIツールは
自分一人しか閲覧しないBoardを作ってアサインせずにカードを作って管理しようと思っているので、下の「Get a Board」との併用で考えている。

先のコマンドでBoardのIDを取得しておいて……
curl 'https://api.trello.com/1/boards/{boardId}?cards=open&lists=open&key={yourKey}&token={yourToken}'

cardsやlistsパラメータがopenなのはそれぞれ「here」リンクから辿る事で取りうる値を確認出来る。

開かれているものということでopenがあることを確認したので指定すればOK

というわけで出来上がったツールがこちら

https://github.com/miyabisun/todo-cli

自分で使うものを手っ取り早く用意したいのでLiveScriptを採用した。
CoffeeScriptライクなAltJSをNode.jsで動かしているだけなので
その気になれば読めると思う。

CRUDの扱いは/modules/cards.lsのあたりを確認してもらえればって感じ。

参照元

Discussion