virtualiment

Google Apps Script からTrello API を使ってTrelloを操作する

公開日：2018/09/30 更新日：2018/09/30
GoogleAppsScript trello
Google Apps Script からTrello API を使ってTrelloを操作するのサムネイル

はじめに

Trelloはカンバン方式のタスク管理サービスになります。Trelloはその使いやすさだけでなく、APIの公式ドキュメントが豊富で外部サービスや自分で作成したアプリでの連携が比較的容易である点も魅力です。ここでは、Google Apps ScriptからTrello APIを使ってTrello上のリストやタスクに対して基本的な操作を行うところまでをメモします。

できるようになること

Goolge Apps ScriptからTrello APIを使って、以下の基本的な操作をTrelloに対して実行できるようになります。以降では、まずTrello APIを使うためのAPIキーとAPIトークンの取得手順を説明し、その後で以下の処理を実行するGoogle Apps Scriptのコードについて説明します。

  • 全てのボードの情報を取得する
  • 指定したボード内の全てのリストの情報を取得する
  • 指定したリスト内の全てのカードの情報を取得する
  • 指定したリストにカードを新規作成する
  • カードを更新する
  • カードをアーカイブする

Trello APIキーとAPIトークンの取得

まずはじめに、外部のアプリケーションからTrello APIを使用するために、APIキーとAPIトークンを取得します。取得するためには、まず自身のTrelloアカウントでTrelloにログインし、ログインしている状態で以下の公式APIページにアクセスします。

trello.com
Trello API

Trello API

以下のようなページが表示されるので、利用規約を読んで同意の上、「Generate API Key」をクリックします。

1-apikey.png

「Generate API Key」をクリックすると、いかのように「Developers API Key」が表示されます。ここで以下の「Token」というリンクをクリックします。 2-developer-api-key.png

「Token」のリンクをクリックすると、以下のようにトークンに本当に許可を与えるかの確認画面が表示されるので、「Allow」をクリックします。 4-api-token.png

「Allow」をクリックすると、以下のようにトークンを含むページが表示されますので、ここに表示されたトークンをどこかにメモしておきます。 5-given-token.png

以上でTrello APIキーとAPIトークンの取得は完了です。

Google Apps ScriptからTrello APIを使って操作する

Trello APIの公式ドキュメントを参考に、Google Apps ScriptからTrello APIを使ってTrelloを操作します。なお、ここで使用するTrello APIはREST APIとなっています。従って、以降に記載するGoogle Apps Scriptの関数は、特定のURLに対してGET、POST、PUTリクエストをそれぞれ送るシンプルなものです。各リクエストを送って、それに対する応答としてデータが返ってきます。以降で紹介する関数は、各APIでどのような処理ができるかを示すための例となり、実用的でない部分も多いです。ただ、APIの動作さえ理解すれば、簡単に応用できると思います。

なお、REST APIとは何か？については以下のサイト様が参考になりました。

0からREST APIについて調べてみた - Qiita

また、全てのAPIの使い方は、以下の公式ドキュメントに整理されています。

Trello Developers

動作確認用のログ関数

以降では、全ての処理でエラーを補足してログするために以下の関数を使用しています。適当なスプレッドシートを用意し、そのスプレッドシートのIDとシート名があれば後はどんどんログを残していきます。

function addLog(text) {
  var spreadsheetId = "スプレッドシートのID";
  var sheetName = "シート名";
  var spreadsheet = SpreadsheetApp.openById(spreadsheetId);
  var sheet = spreadsheet.getSheetByName(sheetName);
  sheet.appendRow([new Date()/*タイムスタンプ*/,text]);
}

全てのボードの情報を取得する

以下のgetAllBoards関数は、自身のTrelloアカウント上に作成されている全てのボードの情報を取得します。

function getAllBoards() {
  var DEV_API_KEY = "取得したAPIキー";
  var API_TOKEN = "取得したAPIトークン";

  var url = 'https://api.trello.com/1/members/me/boards?key=' + DEV_API_KEY + '&token=' + API_TOKEN; 

  try {
         var response = UrlFetchApp.fetch(url, {'method':'get'}); // GETリクエスト 
         addLog(response);
    
       } catch (er) { //エラー内容をログに保存
         var logText = "エラー : line - " + er.lineNumber + '\n Error: ' + er.message;
         addLog(logText);
       }

}

上記のurlのhttps://api.trello.com/1/members/me/boardsに含まれるmeは、この後に続くAPIキー（上記のDEV_API_KEY）とトークン（上記のAPI_TOKEN）の組み合わせから自動的に自身のユーザ名と解釈されて処理されます。そしてこのURLに対してGETリクエストを送っています。このGETリクエストに対して全てのボードの情報がJSON形式でレスポンスとして返ってきます。 （公式ドキュメント参照）

具体的には、以下のように多くの情報が１つのボードについて返ってきます。複数のボードが存在する場合は、各ボードについて以下の情報が返ってきます。

{
    "name": "myTrelloBoard",
    "desc": "",
    "descData": null,
    "closed": true,
    "idOrganization": null,
    "limits": null,
    "pinned": null,
    "invitations": null,
    "shortLink": "lmCwMYKw",
    "powerUps": [],
    "dateLastActivity": "2018-06-09T10:30:44.519Z",
    "idTags": [],
    "datePluginDisable": null,
    "creationMethod": null,
    "id": "914y91375y91h135971y53h15",
    "invited": false,
    "starred": false,
    "url": "https://trello.com/t/krtnrtjart/myTrelloBoard",
    "prefs": {
        "permissionLevel": "private",
        "voting": "disabled",
        "comments": "members",
        "invitations": "members",
        "selfJoin": false,
        "cardCovers": true,
        "cardAging": "regular",
        "calendarFeedEnabled": false,
        "background": "blue",
        "backgroundImage": null,
        "backgroundImageScaled": null,
        "backgroundTile": false,
        "backgroundBrightness": "dark",
        "backgroundColor": "#0079BF",
        "backgroundBottomColor": "#0079BF",
        "backgroundTopColor": "#0079BF",
        "canBePublic": true,
        "canBeOrg": true,
        "canBePrivate": true,
        "canInvite": true
    },
    "subscribed": false,
    "labelNames": {
        "green": "",
        "yellow": "",
        "orange": "",
        "red": "",
        "purple": "",
        "blue": "",
        "sky": "",
        "lime": "",
        "pink": "",
        "black": ""
    },
    "dateLastView": "2018-07-24T10:51:26.199Z",
    "shortUrl": "https://trello.com/t/krtnrtjart",
    "memberships": [{
        "id": "23592q86p98y6p8946",
        "idMember": "23957257h5397h5n33957",
        "memberType": "admin",
        "unconfirmed": false,
        "deactivated": false
    }]
}, 
（・・・１つ目以降のボードの情報が続く・・・）
]

もしボードの指定したフィールドのみがほしい場合は、クエリパラメータで指定します。 例えば、各ボードのIDと名前だけを取得したい場合は、getAllBoards関数の中のurlの値に、以下のように&fields=nameを追加してGETリクエストを送ります。

var url = 'https://api.trello.com/1/members/me/boards?key=' + DEV_API_KEY + '&token=' + API_TOKEN + '&fields=name';`</pre>

<p>`&fields=name`をURLに追加して`getAllBoards`関数を実行すると、以下のように全ボードの名前とIDだけが返ってきます。IDは指定しなくても返ってきます。</p>
<pre><code class="hljs">[{
    "name": ""myTrelloBoard",
    "id": "914y91375y91h135971y53h15"
}, {
    "name": "myBoard2",
    "id": "53wer8346346467l4jk34k6k4k"
}, 
（・・・２つ目以降のボードの情報が続く・・・）
]

指定したボード内の全てのリストの情報を取得する

以下のgetListsFromBoard(boardID)関数は、ボードIDを引数として渡すことでそのボードに含まれる全てのリストの情報を取得します。ボードIDは、前述したgetAllBoards関数などで取得していることが前提になります。なお、以下では&fields=nameをURLに追加してリストの名前だけを返すようにしています。getAllBoards関数とほとんど一緒になりますが、GETリクエストの送信先となるurlが異なっています。

function getListsFromBoard(boardID){
  var DEV_API_KEY = "取得したAPIキー";
  var API_TOKEN = "取得したAPIトークン";
  var url = 'https://api.trello.com/1/boards/' + boardID + '/lists?key=' + DEV_API_KEY + '&token=' + API_TOKEN + '&fields=name';

  try {
         var response = UrlFetchApp.fetch(url, {'method':'get'}); // GETリクエスト
         addLog(response);
    
       } catch (er) { //エラー内容をログに保存
         var logText = "エラー : line - " + er.lineNumber + '\n Error: ' + er.message;
         addLog(logText);
       }
}

返ってくる結果は以下になります。リストのIDと名前の一覧です。

[{
    "id": "2383833m338m3m33mm0",
    "name": "ToDo"
}, {
    "id": "2383833m338m3m323525l",
    "name": "Doing"
}, {
    "id": "2383833m338m3m3235245",
    "name": "Done"
}, {
    "id": "2311233m235\568km3m33",
    "name": "Pending"
}, {
    "id": "23948833m338m3m333rir8",
    "name": "Meeting"
}]

指定したリスト内の全てのカードの情報を取得する

以下のgetCardsFromList(listID)関数は、リストのIDを引数として渡すことでそのリストに含まれる全カードの情報を取得します。リストIDは、前述したgetListsFromBoard(boardID)関数などで取得していることが前提になります。なお、以下では&fields=nameをURLに追加してカードの名前だけを返すようにしています。

function getCardsFromList(listID){
  var DEV_API_KEY = "取得したAPIキー";
  var API_TOKEN = "取得したAPIトークン";
  var url = 'https://api.trello.com/1/lists/' + listID + '/cards?key=' + DEV_API_KEY + '&token=' + API_TOKEN + '&fields=name';
   
  try {
         var response = UrlFetchApp.fetch(url, {'method':'get'}); // GETリクエスト  
         addLog(response);
    
       } catch (er) { //エラー発生寺にログを記録
         var logText = "エラー : line - " + er.lineNumber + '\n Error: ' + er.message;
         addLog(logText);
       }
}

以下がレスポンスとして返ってきます。

[{
    "id": "5592kr09fk9k49ek3930802w2",
    "name": "ミーティングする"
}, {
    "id": "5592kr09fk9k49kk339202262",
    "name": "メール返す"
}, {
    "id": "5592kk3i9jfp2k0t73858kfik22",
    "name": "買い物いく"
}, {
    "id": "5592kr09fk35ou2p08jyp;9022",
    "name": "電話する"
}, {
    "id": "5592k384o689k66k25k9dlod2",
    "name": "挨拶にいく"
}]

指定したリストにカードを新規作成する

以下のaddCardToList(listID)関数は、指定したリストに新しいカードを新規作成します。なお、作成するカードの情報は、以下のようにGETリクエストのクエリパラメータとして渡すことができます。

function addCardToList(listID){
  var DEV_API_KEY = "取得したAPIキー";
  var API_TOKEN = "取得したAPIトークン";
  
  var cardName = "newtask";
  var cardDesc = "This is newtask";
  var cardPos = "top";
  var cardDue = "2018-10-12";
  
  // パラメータが多いと見にくいため以下のように並べる
  var url_ext = 'name=' + cardName // カード名
  + '&desc=' + cardDesc            // カードの説明
  + '&pos=' + cardPos              // カードの位置
  + '&due=' + cardDue              // カードの締切日
  + '&idList=' + listID            // カードを作成先であるリストのID
  + '&key=' + DEV_API_KEY
  + '&token=' + API_TOKEN;

  var baseurl = 'https://api.trello.com/1/cards?'; //ベースとなるURL
  var url = baseurl + url_ext;

  try {
         var response = UrlFetchApp.fetch(url, {'method':'post'});  // POSTリクエスト       
         addLog(response);
    
       } catch (er) { //エラー発生寺にログを記録
         var logText = "エラー : line - " + er.lineNumber + '\n Error: ' + er.message;
         addLog(logText);
       }
}

上記のaddCardToList(listID)では、以下の情報をクエリパラメータとして渡しています。

  • cardName : カードの名前
  • cardDesc : カードの説明
  • cardPos : カードの位置。リストの中の一番上に作成したい場合はtop、一番下はbottomを指定する
  • cardDue : カードの締切日。

その他にもラベルなども指定できます。詳しくはこちらの公式ドキュメントに記載があります。

作成に成功すると、作成したカードの情報がレスポンスとして返ってきます。

{
    "id": "5k20485l9l5i6mtp434958",
    "badges": {
        "votes": 0,
        "attachmentsByType": {
            "trello": {
                "board": 0,
                "card": 0
            }
        },
        "viewingMemberVoted": false,
        "subscribed": false,
        "fogbugz": "",
        "checkItems": 0,
        "checkItemsChecked": 0,
        "comments": 0,
        "attachments": 0,
        "description": true,
        "due": "2018-10-12T00:00:00.000Z",
        "dueComplete": false
    },
    "checkItemStates": null,
    "stickers": [],
    "closed": false,
    "dueComplete": false,
    "dateLastActivity": "2018-09-28T13:30:34.697",
    "desc": "This is newtask",
    "descData": {
        "emoji": {}
    },
    "due": "2018-10-12T00:00:00.000Z",
    "email": null,
    "idBoard": "2075937460u6jy03068j0y8",
    "idChecklists": [],
    "idList": "230854208np93j5j08346j84j",
    "idMembers": [],
    "idMembersVoted": [],
    "idShort": 67,
    "idAttachmentCover": null,
    "labels": [],
    "idLabels": [],
    "manualCoverAttachment": false,
    "name": "newtask",
    "pos": 32767.5,
    "shortLink": "uhS7G58g",
    "shortUrl": "https://trello.com/c/mgiu848jr4",
    "subscribed": false,
    "url": "https://trello.com/c/mgiu848jr4/67-newtask",
    "limits": {}
}

カードを更新する

以下のupdateCard(cardID)関数は、指定したカードの情報を更新することができます。例えば、指定のリストに移動したり、指定のボードに移動したりすることができます。以下のupdateCard(cardID)では、例として指定したカードを指定したリストに移動する更新処理を行っています。ちなみに、PUTリクエストになります。

function updateCard(cardID){
  var DEV_API_KEY = "取得したAPIキー";
  var API_TOKEN = "取得したAPIトークン";
  var newListID = "239h5525h9823h5"; 
  var cardPos = "top"; 

  var url_ext = 'idList=' + newListID
  + '&pos=' + cardPos
  + '&key=' + DEV_API_KEY
  + '&token=' + API_TOKEN;

  var baseurl = 'https://api.trello.com/1/cards/' + cardID + '?';
  var url = baseurl + url_ext;

  try {
         var response = UrlFetchApp.fetch(url, {'method':'put'});  // PUTリクエスト
         addLog(response);
    
       } catch (er) { //エラー発生寺にログを記録
         var logText = "エラー : line - " + er.lineNumber + '\n Error: ' + er.message;
         addLog(logText);
       }
}

newListIDで指定したリストIDを持つリストにカードを移動しています

カードをアーカイブする

前述した updateCard(cardID)関数の中で、クエリパラメータを以下のように変更して実行すると、指定したカードをアーカイブすることができます。

function archiveCard(cardID){
  var DEV_API_KEY = "取得したAPIキー";
  var API_TOKEN = "取得したAPIトークン";
  
  var url_ext = 'closed?value=true'
  + '&key=' + DEV_API_KEY
  + '&token=' + API_TOKEN;

  var baseurl = 'https://api.trello.com/1/cards/' + cardID + '/';
  var url = baseurl + url_ext;

  try {
         var response = UrlFetchApp.fetch(url, {'method':'put'}); // PUTリクエスト   
         addLog(response);
    
       } catch (er) { //エラー発生寺にログを記録
         var logText = "エラー : line - " + er.lineNumber + '\n Error: ' + er.message;
         addLog(logText);
       }
}

まとめ

Trello APIをGoogle Apps Scriptで操作することで、色々なアプリと連携させることができます。例えば、Trello上で期限が迫っているタスクがあれば、Google Apps ScriptからSkypeやSlackにメッセージを投稿するということもできます。

関連記事

開発アプリ

nanolog.app
nanolog

毎日の小さな出来事をなんでも記録して、ログとして残すためのライフログアプリです。