Asana APIは、タスク・プロジェクト・ユーザーなどのAsanaのデータを外部のプログラムから読み書きするREST APIです。基幹システムで受注が入ったら担当者にタスクを起票する、Asanaでタスクが完了したら販売管理のステータスを進める、といった他システム連携はこのAPIで組みます。この記事では、PATとOAuthの使い分け、curlとPythonでのタスク作成、100件単位のページ取得、429のRetry-After対応、Webhookのハンドシェイクと署名検証までをコード付きで整理し、自前で実装するかiPaaSで済ませるかの判断基準も示します。
まとめ:Asana APIで連携を組むときの認証の選び方と実装の勘所
自社内だけで動くバッチや同期処理ならPAT(Personal Access Token)で十分です。他の利用者の代理で動くアプリや、複数の顧客企業に配るツールはOAuthにします。公式ドキュメントがこの線引きを明記しているので、迷う余地はありません。
実装で落としやすいのは3か所です。一覧取得はlimitとoffsetで100件ずつ回す。429が返ったらRetry-Afterの秒数だけ待つ。Webhookは最大1回配信の設計なので、受信だけに頼らず定期ポーリングで差分を拾い直す。連携する相手が3システムを超える、または失敗時の再実行と監査ログが要るなら、ノーコードの連携ツールではなく自前実装を選ぶのが堅実です。
Asana APIの全体像と、エンドポイント・GID・dataで包む基本ルール
まず、どのエンドポイントを使う場合にも共通する前提を押さえます。Backlog・Notion・Slackなど他のSaaSのAPIと比べると、Asana APIはリクエストの包み方と項目の絞り方に独自の作法があります。
ベースURLのapi/1.0とdataで包むリクエスト本文の書き方
エンドポイントはすべてhttps://app.asana.com/api/1.0の下にあります。タスクやプロジェクトはGIDと呼ばれる数字の文字列で識別され、本文を送るときは項目をそのまま並べずに{"data": {...}}で包む形式です。Create a taskのリファレンスでも、POST /tasksの本文はdataの中にname・notes・assignee・due_on・projectsを書く形になっています。
応答は既定で一部の項目を省いた形で返ります。必要な項目はopt_fieldsにカンマ区切りで指定し、memberships.project.nameのように入れ子の項目も取れます。逆に言うと、opt_fieldsを付けずに「期日が返ってこない」と悩むのは典型的なつまずきです。
レート制限は無料150回・有料1,500回/分と同時実行数の上限
Rate limitsのページに載っている上限を、連携設計で効く順に並べると次のとおりです。制限はアクセストークン単位で数えられます。
| 制限の種類 | 上限 | 設計への影響 |
|---|---|---|
| 標準(有料ドメイン) | 1分あたり1,500リクエスト | 通常の同期処理ではまず届かない |
| 標準(無料ドメイン) | 1分あたり150リクエスト | 全件同期を毎分回すと超えやすい |
| 検索API | 1分あたり60リクエスト | 検索で突き合わせる処理は別枠で絞る |
| 同時リクエスト(GET) | 50件 | 読み取りの並列数の上限 |
| 同時要求数(書き込み系) | 15件 | 一括起票の並列数はここで決まる |
表の書き込み系はPOST・PUT・PATCH・DELETEを指し、同時要求数の上限は15件です。このほか、応答を組み立てた後に計算される「コスト」による1分ごとの枠もあり、重いクエリは回数が少なくても制限に掛かります。無料ドメインで1万件のタスクを毎回全件取り直す設計は、100件ずつでも100回の呼び出しになり、150回の枠を1回の同期でほぼ使い切ります。差分だけを取りにいく設計にしておくのが前提です。
PATとOAuthの使い分けと、curlで認証を通すまでの手順
認証方式はPATとOAuth 2.0の2つです。どちらもAuthorization: Bearerヘッダーで渡す点は同じで、違いは「誰の権限で、誰が使うか」にあります。
社内バッチはPAT、他人の代理で動くアプリはOAuthに分ける基準
Personal access tokenのページによると、PATはデベロッパーコンソール(app.asana.com/0/my-apps)で用途の説明を付けて発行し、既定では期限切れになりません。トークンは発行した本人の代理として動くため、本人がアクセスできるワークスペースのデータにはそのまま届きます。同じページには、他のユーザーの代理で操作するアプリを作るならOAuthを使うべきだと書かれています。
実務の線引きはこうなります。情報システム部門が自社のAsanaと基幹システムを同期する夜間バッチならPAT。営業担当が各自のAsanaアカウントで認可して使う社内ツールや、複数の会社に提供する連携アプリならOAuth。PATを使う場合も、個人のアカウントではなく連携専用のアカウントで発行しておくと、担当者の異動や退職で連携が止まる事故を防げます。プログラムへの直書きは公式が禁じており、AWS Secrets Managerなどのシークレット管理に置くよう案内されています。
OAuthの認可コード+PKCEとアクセストークン1時間の更新処理
OAuthのページに沿うと、認可はhttps://app.asana.com/-/oauth_authorize、トークン交換と更新はhttps://app.asana.com/-/oauth_tokenで行う認可コードグラントです。PKCEはS256方式に対応し、リダイレクトURIにlocalhostや127.0.0.1を使う場合は必須になります。CSRF対策のstateも、送った値と戻ってきた値を必ず突き合わせます。
アクセストークンのexpires_inは3,600秒(1時間)です。長期間有効な更新トークンをgrant_type=refresh_tokenで送れば利用者の操作なしに取り直せるので、トークン保存のテーブルには更新トークンと失効時刻を持たせ、呼び出し前に期限を見て更新する処理を共通部品にします。スコープはtasks:read・tasks:writeのように資源と操作の組で指定し、writeはreadを含みません。タスク作成だけのアプリでも、作成後に内容を読み返すなら両方を要求します。
curlで/users/meを呼び、ワークスペースとプロジェクトのGIDを取る
最初の疎通確認は自分自身の情報を返す/users/meが手軽です。環境変数ASANA_TOKENにPATを入れてから、次のコマンドを順に実行します。
# 1. 自分の情報と所属ワークスペースのGIDを確認する
curl -s -H "Authorization: Bearer $ASANA_TOKEN" \
"https://app.asana.com/api/1.0/users/me?opt_fields=name,workspaces.name"
# 2. ワークスペース内のプロジェクト一覧からプロジェクトのGIDを確認する
curl -s -H "Authorization: Bearer $ASANA_TOKEN" \
"https://app.asana.com/api/1.0/projects?workspace=1201234567890000&limit=100&opt_fields=name"
# 3. プロジェクトにタスクを1件作成する(本文はdataで包む)
curl -s -X POST "https://app.asana.com/api/1.0/tasks" \
-H "Authorization: Bearer $ASANA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"data":{"name":"請求書の確認","projects":["1201234567890123"],"assignee":"me","due_on":"2026-11-30","notes":"販売管理から自動登録"}}'
GIDの数字は例なので、手順1と2の結果に置き換えます。作成に成功すると201が返り、本文のdata.gidが新しいタスクのGIDです。projectsか親タスクのparentを指定していればworkspaceは省略できます。なおprojects・tags・followersを本文で指定できるのは作成時だけで、後から足すときはaddProjectなどの別エンドポイントを呼びます。
Pythonでタスク作成と一覧取得を書くときのコードと注意点
本番の連携処理はスクリプト言語で書くことが多いので、Pythonでの書き方を2通り示します。公式SDKで書く方法と、ページ取得や再試行を自分で制御するためにrequestsで書く方法です。
公式SDKのasana 5.5系でタスクを作成するコードとopt_fields
公式のPythonクライアントはGitHubのAsana/python-asanaで公開されており、2026年11月時点のREADMEにはPackage version 5.5.1と書かれています。pip install asanaで入れ、Configurationにトークンを設定してTasksApiを作るのが基本形です。
import os
import asana
# トークンは環境変数から読む(コードに直書きしない)
configuration = asana.Configuration()
configuration.access_token = os.environ["ASANA_TOKEN"]
api_client = asana.ApiClient(configuration)
tasks_api = asana.TasksApi(api_client)
body = {
"data": {
"name": "請求書の確認",
"projects": ["1201234567890123"],
"due_on": "2026-11-30",
}
}
# 作成後に必要な項目だけを返してもらう
task = tasks_api.create_task(body, {"opt_fields": "name,due_on,permalink_url"})
print(task)
SDKは旧来のv3系とv5系で書き方が大きく異なり、検索で見つかる古い記事のasana.Client.access_token(...)という書き方は5系では動きません。サンプルをコピーする前に、READMEの版と手元のpip show asanaの版を突き合わせてください。
limitとoffsetによる100件単位の取得と429のRetry-After待機
Paginationのページによると、limitは1〜100で、続きがあると応答にnext_page.offsetが付きます。limitを付けない古いエンドポイントでは結果が約1,000件で切り捨てられたり、件数の多い組織ではタイムアウトしたりするため、一覧取得にはlimitの指定が必要です。429への対応も同じループに入れておきます。
import os
import time
import requests
BASE = "https://app.asana.com/api/1.0"
HEADERS = {"Authorization": f"Bearer {os.environ['ASANA_TOKEN']}"}
def fetch_project_tasks(project_gid):
"""プロジェクト内のタスクを100件ずつ全件取得する"""
params = {
"project": project_gid,
"limit": 100,
"opt_fields": "name,completed,due_on,modified_at",
}
tasks = []
while True:
r = requests.get(f"{BASE}/tasks", headers=HEADERS, params=params, timeout=30)
if r.status_code == 429:
# 固定の待ち時間ではなく、返された秒数だけ待つ
time.sleep(int(r.headers["Retry-After"]))
continue
r.raise_for_status()
body = r.json()
tasks.extend(body["data"])
next_page = body.get("next_page")
if not next_page:
return tasks
params["offset"] = next_page["offset"]
Rate limitsのページは、待ち時間に固定の1分を使わず返された値を使うこと、制限で拒否された要求も枠に数えられることを明記しています。Retry-Afterより早く再送すると回復がさらに遅れるので、待たずに再送する実装は避けるべきです。offsetには有効期限があり、途中で長く止まった処理は先頭から取り直す前提で組みます。
一括起票時の書き込みを15並列以内に抑え、重複起票を防ぐ設計
受注データから数百件のタスクをまとめて起票する処理では、書き込み系の同時リクエスト上限15件が先に効きます。スレッド数を10程度に固定し、429を受けたら全スレッドで待つ形にすると、上限の手前で安定します。
もう1つ詰まりやすいのが重複起票です。タスク作成のAPIには同じ要求を2回送っても1件に保つ仕組みが見当たらないため、通信がタイムアウトして再送した結果、同じタスクが2件できることがあります。連携元のID(受注番号など)と作成したタスクのGIDの対応表を連携側のデータベースに持ち、再送の前に対応表を確認する設計にしておくと安全です。対応表はWebhookで変更を受けたときに、どの業務データを更新するかを引く用途にも使えます。
Webhookでタスクの変更を受け取るハンドシェイクと署名検証の実装
Asanaで完了や期日変更が起きたら連携先に反映したい場合は、ポーリングよりWebhookのほうが呼び出し回数を抑えられます。ただしAsanaのWebhookは作成時のハンドシェイクと配信の保証範囲に癖があり、そこを知らないと「作れない」「届かない」で止まります。
POST /webhooksの作成とX-Hook-Secretを返すハンドシェイク
Establish a webhookのリファレンスでは、本文に監視対象のresourceと受信先のtargetを指定し、任意でfiltersを付けます。OAuthで作る場合のスコープはwebhooks:writeです。
curl -s -X POST "https://app.asana.com/api/1.0/webhooks" \
-H "Authorization: Bearer $ASANA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"data":{"resource":"1201234567890123","target":"https://hooks.example.com/asana/webhook","filters":[{"resource_type":"task","action":"changed","fields":["completed","due_on"]}]}}'
この要求を受けたAsanaは、targetへX-Hook-Secretヘッダー付きのPOSTを送ります。受信側が同じ値のX-Hook-Secretを200か204で返して初めて、元の作成要求に201が返る仕組みです。つまり作成要求を送るプロセスと受信するサーバーを別に動かしておく必要があり、1本の同期処理の中で両方をこなそうとすると待ち合わせて失敗します。targetにlocalhostを指定すると403になるので、開発中はトンネルサービスなどで外から届くHTTPSのURLを用意します。
チームやワークスペース単位でWebhookを作るときはfiltersの指定が必須で、タスクやサブタスクのイベントはこの上位単位のWebhookには伝わりません。タスクの変更を追うなら、プロジェクト単位で作るのが基本です。
X-Hook-SignatureのHMAC-SHA256検証と10秒以内に返す受信処理
Webhooksのガイドによると、2回目以降の配信には、ハンドシェイクで受け取った秘密値を鍵にして本文全体をSHA256のHMACで計算したX-Hook-Signatureが付きます。検証は強く推奨されており、10秒以内に成功のステータスを返さないと再送の対象になります。Flaskで書くと次の形です。
import hashlib
import hmac
import queue
from flask import Flask, Response, request
app = Flask(__name__)
events_queue = queue.Queue()
SECRET_PATH = "asana_hook_secret.txt" # 本番はシークレット管理に置く
@app.post("/asana/webhook")
def receive():
handshake = request.headers.get("X-Hook-Secret")
if handshake:
# ハンドシェイク:秘密値を保存し、同じ値を返す
with open(SECRET_PATH, "w") as f:
f.write(handshake)
return Response(status=200, headers={"X-Hook-Secret": handshake})
with open(SECRET_PATH) as f:
secret = f.read().strip()
expected = hmac.new(secret.encode(), request.get_data(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-Hook-Signature", "")):
return Response(status=401)
# 重い処理はキューに渡し、10秒以内に応答を返す
for event in request.get_json().get("events", []):
events_queue.put(event)
return Response(status=200)
署名は本文の生のバイト列で計算するため、JSONとして読み直してから計算すると一致しません。このコードは説明のために簡略化しており、本番ではハンドシェイクを受け付けるのを自分がWebhook作成を送った直後だけに限ります。いつでもX-Hook-Secretを受け付けると、第三者が秘密値を上書きできてしまうからです。署名検証と冪等な処理の考え方は、決済の通知でも同じで、決済Webhookの署名検証と冪等な注文確定の実装で詳しく扱っています。
最大1回配信・24時間で削除される仕様に合わせた取りこぼし対策
同じガイドには、配信は最大1回(at-most-once)の設計で、まれに届かないことがあると書かれています。イベントの本文は変更の要点だけを持つ簡略形なので、受け取ったらタスクのGIDでAPIを呼び直し、最新の状態を取得してから連携先へ反映する手順です。大半のイベントは10分以内に届きますが、それを超える場合もあるため、反映前にcreated_atを確認すると古い変更で新しい値を上書きする事故を防げます。
運用で効いてくる数字は3つです。ハートビートは8時間ごとに空の本文で届き、24時間応答が無いとWebhookは削除されます。配信の失敗が24時間続いた場合も削除され、監視対象の資源が消えた場合は72時間後の削除です。受信サーバーの長い停止がそのまま連携停止になるので、1日1回GET /webhooksで存在を確認して消えていたら作り直す処理と、modified_atを条件に差分を取り直すポーリングを併用します。公式もポーリングでの補完を推奨しています。
他システム連携でAsana APIを自前実装する条件とiPaaSで済ませる場面
ここまでの実装は、受信サーバー・トークン管理・対応表・再試行・存在確認を自分で持つことを意味します。すべての連携でそこまで要るわけではありません。
他システムとの双方向同期と監査の要件を満たすための自前実装の選択
自前実装を選ぶ条件は2つに絞れます。1つは、販売管理や基幹システムとAsanaの間で状態を双方向に同期し、どちらで更新しても整合を保つ必要がある場合。重複起票を防ぐ対応表、created_atによる新旧判定、取りこぼしを拾うポーリングは、ノーコードの連携ツールの画面設定では組みにくい部分です。
もう1つは、誰がいつ何を連携したかの記録と、失敗した連携を特定して再実行する手段が業務上必要な場合です。監査やSLAの説明責任がある業務では、この2点を自社のデータベースとログに持てるかが決め手になります。基幹システム側のAPI設計から含めて検討する場合は、API開発・システム連携の範囲で、連携方式と運用監視までまとめて設計できます。
iPaaSやノーコードで足りる連携と、自前実装が過剰になる場面
反対に、フォームの送信でタスクを1件作る、タスクの完了をチャットに通知する、といった片方向で1対1の連携に受信サーバーを立てるのは過剰です。月の処理件数が数百件程度で、取りこぼしても人が気づいて手で直せる業務なら、ZapierやMakeなどの連携ツールで十分に回ります。
判断に迷うのは、最初は片方向で始めて後から双方向にしたくなるケースです。この場合も最初からAPIで作り込む必要はなく、連携ツールで業務の流れを固めてから、件数と要件が増えた時点で自前実装に移すのが無駄の少ない順序です。連携ツールの選定と設定はiPaaS導入支援(Zapier/Make/Workato/Yoom)で相談できます。同じ考え方で組んだ他のSaaSの例として、Backlog APIの認証と課題登録・Webhook連携の実装も参考になります。
Asana APIのよくある質問:無料プラン・対応言語・トークン管理
Asana APIを使い始める前によく調べられる疑問を5つ取り上げます。
Asana APIは無料プランでも使えますか?
無料プランでもAPIの利用は可能です。公式のRate limitsのページには無料ドメインの上限として1分あたり150リクエストが載っており、無料プランのワークスペースでもPATを発行すればAPIを呼べます。有料ドメインの上限は1分あたり1,500リクエストで、差は呼び出し回数の枠にあります。同ページに書かれているのは回数の上限で、呼び出し単位の料金は書かれていません。無料プランで定期同期を組むなら、全件取得ではなく変更分だけを取る設計にして150回の枠に収めます。プラン自体の人数や機能の上限はタスク管理ツールの無料プラン比較を参照してください。
Asana APIはどのプログラミング言語で使えますか?
REST APIなので、HTTPのリクエストを送れる言語なら何でも使えます。curlで手早く試し、本番はPythonやNode.jsで書く組み合わせが一般的です。Pythonには公式クライアントのasana(GitHubのREADMEで5.5.1)があり、pip install asanaで導入できます。注意したいのはSDKの版で、v3系の書き方の記事が多く残っています。v5系ではConfigurationとTasksApiを使う形に変わっているため、サンプルを使う前に手元の版を確認してください。
Asanaのパーソナルアクセストークンに有効期限はありますか?
公式ドキュメントでは、PATは既定で期限切れにならないとされています。そのため漏えいした場合には、影響が長く続くおそれがあるのです。パスワードと同じ扱いで保管し、コードやリポジトリに書かず、シークレット管理のサービスに置くよう公式も案内しています。使わなくなったPATはデベロッパーコンソールで定期的に見直し、取り消す運用が必要です。一方、OAuthのアクセストークンは1時間で切れ、更新トークンで取り直す仕組みなので、他の利用者に配るアプリではOAuthを選びます。
AsanaのWebhookがlocalhostで作成できないのはなぜですか?
Webhook作成のリファレンスに、localhostのような無効なホスト名は403になると書かれているためです。Asanaは作成時にtargetへハンドシェイクのPOSTを送るので、インターネットから届くURLでなければ作成自体が完了しません。開発中はトンネルサービスで手元のサーバーに外部からのHTTPSを通すか、検証用のクラウド環境に受信処理を置きます。作成要求を送る処理と受信サーバーを同じプロセスで同期的に動かしていると、ハンドシェイクに応答できずに失敗する点にも注意してください。
Asana APIで一度に取得できるタスクは何件までですか?
ページ取得のlimitは1〜100なので、1回の呼び出しで返るのは最大100件です。続きがある場合は応答のnext_page.offsetを次の要求に渡して取得を続ける仕組みです。limitを付けない古いエンドポイントでは約1,000件で結果が切り捨てられ、件数の多い組織ではタイムアウトすることもあると公式に書かれています。全件を取り出す処理は必ずlimit付きのループで書き、offsetには有効期限がある点も考慮して、途中で止まったら最初から取り直す作りにしておきます。
関連記事
- Backlog APIの使い方|APIキー・OAuth2の認証と課題登録・Webhook連携の実装:同じタスク・課題管理系SaaSのAPI連携の実装例
- Notion APIとは?データソース対応の使い方とレート制限・社内連携の実装:社内のドキュメント管理とつなぐ場合のAPI
- Slack APIとは?できること・無料の範囲とアプリ作成からBolt実装までの使い方:タスクの変更をチャットに通知する側のAPI
- SendGrid API Event Webhookの実装手順|署名検証と再送・障害設計:Webhookの署名検証と再送設計の別の例
- プロジェクト管理ツールの無料プランはどこまで使える?主要製品の上限と有料化・自社開発の判断軸:Asanaを含む主要製品の無料プランの上限
- Zoom APIの使い方:Server-to-Server OAuthでミーティング作成・録画取得・Webhookを実装:会議の作成と録画の取得を業務システムにつなぐAPI