Asana APIリファレンスを活用して、スクリプトアクションを実装するコツ

Japanese Forum 質問とアドバイス アンバサダーのヒント
1

Asanaのスクリプトアクション（Script Action）は強力な機能ですが、「JavaScript（Node.js）でどう書けばいいかわからない」「APIの仕様を調べるのが大変」と感じることはありませんか？

特にREST APIを扱う部分はハードルが高く感じられますが、 公式の「APIリファレンス」 を賢く使うことで、開発の手間を削減できます。今回は、私が実践しているAPIリファレンス活用術をご紹介します。

1. APIリファレンスは「ただの辞書」じゃない！

AsanaのAPIリファレンスは 「その場でAPIを試せて、サンプルコードまで生成してくれる」 超高機能なツールです。

2. ここが便利！5つの活用ポイント

① 簡単にAPIの機能を試せる（Try It!）

Personal Access Token (PAT) を入力して、ブラウザ上から実際のデータを操作できます。「Get a Task」なら、PATとタスクのGIDを入力して実行するだけ。コードを書く前に「このAPIで期待通りのデータが取れるか」を即座に確認できます。

image
image1406×668 107 KB

② コードサンプルですぐにベースが完成

画面右側のパネルで言語（Node.jsなど）を選択すると、サンプルコードが自動生成されます。これを見るだけで、関数の呼び出し方やパラメータの指定方法が一目でわかります。

image
image454×501 24.8 KB

③ 応答の解析（JSON構造の確認）が楽々！

Try It! を実行すると、全パラメータを含む応答（JSON）が返ってきます。 例えば、複雑なカスタムフィールドの値を取得したい場合も、実際の応答構造を見れば解析コードが書きやすくなります。

JSON応答例（関係個所のみ抜粋）

{
  "data": {
    "gid": "1xxxxxxxxxxxxxx1",
    "custom_fields": [
    {
      "gid": "1xxxxxxxxxxxxxx2",
      "enum_value": 
      {
        "gid": "1xxxxxxxxxxxx3",
      },
    }]
  }
}

データ取得のコード例（単一選択のカスタムフィールドを判定する場合）:

//タスクのデータを取得
const task = await tasksApiInstance.getTask(task_gid, opts);

//GIDが'1xxxxxxxxxxxxxx2'のカスタムフィールドを取得（ここでは単一選択の優先度の想定）
const priorityCF = task.data.custom_fields.find((item)=>item.gid === '1xxxxxxxxxxxxxx2');

//カスタムフィールド優先度の値のGIDが'1xxxxxxxxxxxx3'(高優先度を想定)の場合
if(priorityCF && priorityCF.gid && priorityCF.enum_value &&   priorityCF.enum_value.gid === '1xxxxxxxxxxxx3'){
//TODO:ここに高優先度の処理を記載
}

④ 内部の「GID」確認も楽

「あのカスタムフィールドや選択肢のGIDは何だっけ？」という時も、リファレンスで実行すればJSONの中に答えがあります。UIから探す手間が省けます。。

image
image300×486 43.2 KB

⑤ 外部アプリ開発にもそのまま転用可能

ここで得た知見は、自作の外部アプリからAsana APIを叩く際にもそのまま役立ちます。

:warning: スクリプトアクションに組み込む際の「3つの注意点」

リファレンスのサンプルコードをスクリプトアクションへ持ち込む際は、以下の調整が必要です。

その1：APIコール部分のみを利用する

スクリプトアクション内では、以下の変数が事前定義済みです。

  • tasksApiInstance: タスク操作用のインスタンス
  • task_gid / project_gid / workspace_gid: 実行コンテキストのID

また、ログ出力は console.log ではなく log() 関数を使います。

▼ 実装イメージ（Get a Taskの場合）

JavaScripttasksApiInstance.getTask(task_gid, opts).then((result) => { log('API Success: ' + JSON.stringify(result.data, null, 2)); }, (error) => { log(error.response.body); });

その2：非同期処理の書き換え（async/await）

リファレンスのサンプルは .then() 形式が多いですが、スクリプトアクションで try-catch を使いたい場合は await 形式に書き換えるのがスッキリします。

▼ awaitでの書き換え例

JavaScripttry { const task = await tasksApiInstance.getTask(task_gid, opts); log('Data: ' + JSON.stringify(task.data, null, 2)); } catch (error) { log(error.response.body); }

その3：opt_fields による出力の最適化

APIリファレンスの Query Params にある opt_fields を設定すると、必要なデータだけを返せます。
不要なパラメータを削ることでパフォーマンスが向上し、60秒の実行制限対策にもなるため、積極的に活用しましょう！
API Referenceでも、opt_fieldsを試すことができます。

image
image594×746 33.3 KB

まとめ

「APIリファレンスで挙動を確認 → コードをコピー → スクリプトアクション用に調整」という流れを覚えると、API活用のハードルがグッと下がります。

ぜひ、公式リファレンス活用してください！

6 Likes
Script(API) 活用（参考用）
2

ご丁寧な共有ありがとうございます！
試してみようとアクセスしたことがきっかけで、Goalsの目標数値の更新がAPI経由でできることに気がつきました。

実際に試してみたところ、売上目標に対しての進捗自動更新ができることが確認できました！
これでタスク単位で獲得売上をカスタムフィールドを設けて、タスク完了時にフィールドの数値を引数にして売上の予実管理がゴールでできそうだなと考えています :raising_hands:

1 Like