こんにちは。CData Software Japan リードエンジニアの杉本です。
今回はプロジェクト・タスク管理ツールとして徐々に日本でも浸透し始めている Asana の REST APIの使い方を紹介します。
Asana とは?
Asana は Facebookの共同創業者であるダスティン・モスコヴィッツ(Dustin Moskovitz)とジャスティン・ローゼンシュタイン(Justin Rosenstein)が開発したチームのプロジェクトとタスクを管理するためのクラウドサービスです。
Asana は、チームの目標を見据えて、プロジェクトや日々のタスクを管理できる、ビジネスの成長を加速させるワークマネジメントプラットフォームです。
さすが Facebook の創業メンバーが開発しているプロダクトだけあって、APIも充実。連携先サービスも Slack や Salesforce、Dropbox と数多く公開されています。
CData でも Asana REST API を活用した Driver 製品をリリースしていて、BIツールやETLツールとの連携をサポートしています。
https://www.cdata.com/jp/drivers/asana/
Asana API Reference
Asana では以下のURLでAPI Referenceを公開しており、機能としては RESTベースのAPIとWebhooksをサポートしていますが、本記事では前者のREST APIを対象として解説します。
https://developers.asana.com/docs/
REST API は「タスク」や「プロジェクト」といったAsanaのコア部分の機能のコントロールから「ユーザー」「ワークスペース」といった管理系の機能、一括リクエストをサポートする BatchAPIなども提供されていて、UIで実行可能な操作のほとんどはAPIでも操作できそうですね。
また、Asana は OpenAPI 3.0 で記述されており、以下のURLでYAML のSpecが公開されているので、PowerApps に取り込んだり、Client Side SDKを生成したりと行った点も柔軟に可能。
https://raw.githubusercontent.com/Asana/developer-docs/master/defs/asana_oas.yaml
さらに以下のページでは Postman のコレクションも入手できます! (素晴らしい)
https://developers.asana.com/docs/#accessing-the-api-with-postman
なお、認証方法は OAuth 2.0 とPAT(パーソナルアクセストークン)の2種類がサポートされています。
https://developers.asana.com/docs/#authentication-basics
使い方
それでは、実際に認証方法を抑えながら、API の使い方を見ていきましょう。
PAT(Personal Access Token) の取得方法
PATの入手は簡単です。以下のURLにアクセスし、個人アクセストークンの追加を行います。
https://app.asana.com/0/developer-console
任意のトークン名を入力し、API利用規約に同意の上、「トークンを作成」ボタンをクリックすれば
以下のようにトークンを取得できます。トークンは二度と表示されないので、忘れてしまった場合は作り直す必要があります。注意しましょう。
こんな感じの文字列です。
0/6ce9fe94e649ece8970fae2a4a7eb316
OAuth 2.0 によるアクセストークンの取得方法
OAuth 2.0 の場合も、先程と同様にまずデベロッパーコンソールにアクセスします。
その後マイアプリから新しくアプリの作成を行います。
https://app.asana.com/0/developer-console
任意のアプリ名を入力の上、API 利用規約に同意し、「アプリを作成」をクリックします。
作成後、クライアントIDとクライアントシークレットを入手できます。また、任意のリダイレクトURLも指定しておきましょう。今回はローカルホストからアクセスするので「http://localhost:33333」としました。
これでアプリの準備完了です。それでは実際にAccess Tokenを取得してみます。
OAuth 2.0 のAccessTokenの取得プロセスは以下を参照してください。
https://developers.asana.com/docs/#authentication-basics
サポートされる OAuthフローは現状 Authorization Code のみ。Authorization URLとToken URLは次の通りです。
- Authorize URL:https://app.asana.com/-/oauth_authorize
- Token URL:https://app.asana.com/-/oauth_token
認証コードの取得は以下のURLを使ってログインすることで、事前に登録したCallback URLへ返ってきます。
URLにアクセスすると以下のような画面が表示され、
Codeを取得できます。
http://localhost:33333/?code=0%2Fb72f72bf854a988022b27e45c47a02e5
あとはこの取得したCodeを使って、Tokenをリクエストします。
POST https://app.asana.com/-/oauth_token client_id=1162672466883558&client_secret=523da8a12ea74fb26ebc1f03335524c8&code=0%2Fb72f72bf854a988022b27e45c47a02e5&redirect_uri=http%3A%2F%2Flocalhost%3A33333&grant_type=authorization_code
Postmanの場合はこんな感じです。
Task API へのアクセス方法
あとは取得したAccessTokenを使ってAPIへ接続します。
例えば、Task一覧を取得したい場合はまず そのTaskが登録されているProjectを把握する必要があるので、以下のリクエストで ProjectのIDを特定します。
GET https://app.asana.com/api/1.0/projects Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRob3JpemF0aW9uIjoxMTYyODA0MzA0MDM5MzgxLCJzY29wZSI6ImRlZmF1bHQgaWRlbnRpdHkiLCJpYXQiOjE1ODIxNjYyMTIsImV4cCI6MTU4MjE2OTgxMn0.V1raB189r-zXFYq7B2i2lEsz1ROPqPtmd-nSFzcsIrY Accept: application/json
するとレスポンスで以下のような値が取得できるので
{ "data": [ { "gid": "1161534178974052", "name": "スタンドアップミーティング", "resource_type": "project" }, { "gid": "1161534178974089", "name": "製品プロジェクト計画", "resource_type": "project" } ] }
取得したいTaskが登録されているProjectのGidを使って、Taskリソースにアクセスします。
https://developers.asana.com/docs/#get-multiple-tasks
GET https://app.asana.com/api/1.0/projects/1161534178974052/tasks Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRob3JpemF0aW9uIjoxMTYyODA0MzA0MDM5MzgxLCJzY29wZSI6ImRlZmF1bHQgaWRlbnRpdHkiLCJpYXQiOjE1ODIxNjYyMTIsImV4cCI6MTU4MjE2OTgxMn0.V1raB189r-zXFYq7B2i2lEsz1ROPqPtmd-nSFzcsIrY Accept: application/json
以下のようなレスポンスを取得できました!
{ "data": [ { "gid": "1161534178974055", "name": "[必読] このテンプレートの使用手順", "resource_type": "task" }, { "gid": "1161534178974063", "name": "タスク例 - <チームメイト名 1>", "resource_type": "task" } ] }
わかりやすいAPIでとてもいいです。
CData Driver での接続方法
CData Driver では PAT(Personal Access Token)・OAuth 2.0 どちらもサポートしています。
CData Driver での設定方法(ODBCやExcel Addinの場合)
http://www.cdata.com/jp/drivers/asana/odbc/
CData Driver(ODBCやExcel Addin)の場合
PWA接続は以下のようにOAuth Access Token にPATを設定し、Other項目に対して「InitiateOAuth=OFF;」を入力してください。
OAuth 2.0 の場合は「Callback URL」「OAuth Client Id」「OAuth Client Secret」を指定します。
CData Driver での設定方法(接続文字列の場合)
http://www.cdata.com/jp/drivers/asana/jdbc/
JDBCなどの場合は、以下のような接続文字列を作成し、指定します。
PATを指定する場合は
- InitiateOAuth=OFF;OAuthAccessToken=0/6ce9fe94e649ece8970fae2a4a7eb316;
OAuth 2.0 の場合は
- InitiateOAuth=GETANDREFRESH;OAuthClientId=1162672466883558;OAuthClientSecret=523da8a12ea74fb26ebc1f03335524c8;