Asana

通过托管的OAuth身份验证访问Asana API。管理工作管理中的任务、项目、工作区、用户和Webhook。

快速开始

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/tasks?project=PROJECT_GID')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础URL

https://gateway.maton.ai/asana/{native-api-path}

将{native-api-path}替换为实际的Asana API端点路径。网关将请求代理到app.asana.com并自动注入您的OAuth令牌。

身份验证

所有请求都要求在Authorization头中包含Maton API密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的API密钥设置为MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的API密钥

1. 登录或创建账户于maton.ai
2. 前往maton.ai/settings
3. 复制您的API密钥

连接管理

在以下地址管理您的Asana OAuth连接https://ctrl.maton.ai。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=asana&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'asana'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "asana",
    "metadata": {}
  }
}

在浏览器中打开返回的url以完成OAuth授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您有多个Asana连接，请使用Maton-Connection请求头来指定要使用哪一个：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/tasks?project=PROJECT_GID')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略此请求头，网关将使用默认的（最早创建的）活跃连接。

API参考

任务

获取多个任务

GET /asana/api/1.0/tasks

查询参数：

• project- 用于筛选任务的项目的GID
• assignee- 负责人的用户GID，或使用"me"表示分配给自己的任务
• workspace- 工作区的GID（如果未指定项目，则此参数为必需）
• completed_since- 用于筛选在此日期之后完成任务时的ISO 8601格式日期
• opt_fields- 需要包含的字段列表，以逗号分隔

示例：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/tasks?project=1234567890&opt_fields=name,completed,due_on')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "data": [
    {
      "gid": "1234567890",
      "name": "审核季度报告",
      "completed": false,
      "due_on": "2025-03-15"
    }
  ]
}

获取任务

GET /asana/api/1.0/tasks/{task_gid}

示例：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/tasks/1234567890')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建任务

POST /asana/api/1.0/tasks
Content-Type: application/json

{
  "data": {
    "name": "新任务",
    "projects": ["项目_GID"],
    "assignee": "用户_GID",
    "due_on": "2025-03-20",
    "notes": "此处为任务描述"
  }
}

示例：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'data': {'name': '完成API集成', 'projects': ['1234567890'], 'due_on': '2025-03-20'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/tasks', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

更新任务

PUT /asana/api/1.0/tasks/{task_gid}

示例：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'data': {'completed': True}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/tasks/1234567890', data=data, method='PUT')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

删除任务

DELETE /asana/api/1.0/tasks/{task_gid}

获取项目中的任务

GET /asana/api/1.0/projects/{project_gid}/tasks

获取子任务

GET /asana/api/1.0/tasks/{task_gid}/subtasks

创建子任务

POST /asana/api/1.0/tasks/{task_gid}/subtasks
Content-Type: application/json

{
  "data": {
    "name": "子任务名称",
    "assignee": "USER_GID",
    "due_on": "2025-03-20"
  }
}

搜索任务（高级版）

注意：此端点需要 Asana 高级版订阅。

GET /asana/api/1.0/workspaces/{workspace_gid}/tasks/search

查询参数：

• text- 要搜索的文本
• assignee.any- 按负责人筛选
• projects.any- 按项目筛选
• completed- 按完成状态筛选

项目

获取多个项目

GET /asana/api/1.0/projects

查询参数：

• workspace- 工作区 GID
• team- 团队 GID
• opt_fields- 逗号分隔的字段列表

示例：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/projects?workspace=1234567890&opt_fields=name,owner,due_date')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "data": [
    {
      "gid": "1234567890",
      "name": "Q1市场营销活动",
      "owner": {
        "gid": "0987654321",
        "name": "爱丽丝·约翰逊"
      },
      "due_date": "2025-03-31"
    }
  ]
}

获取单个项目

GET /asana/api/1.0/projects/{project_gid}

创建项目

POST /asana/api/1.0/projects

示例：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'data': {'name': '新项目', 'workspace': '1234567890', 'notes': '项目描述'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/projects', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

更新项目

PUT /asana/api/1.0/projects/{project_gid}

删除项目

DELETE /asana/api/1.0/projects/{project_gid}

工作区

获取多个工作区

GET /asana/api/1.0/workspaces

示例：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/workspaces')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "data": [
    {
      "gid": "1234567890",
      "name": "Acme Corp",
      "is_organization": true
    }
  ]
}

获取单个工作区

GET /asana/api/1.0/workspaces/{workspace_gid}

更新工作区

PUT /asana/api/1.0/workspaces/{workspace_gid}

向工作区添加用户

POST /asana/api/1.0/workspaces/{workspace_gid}/addUser

从工作区移除用户

POST /asana/api/1.0/workspaces/{workspace_gid}/removeUser

用户

获取多个用户

GET /asana/api/1.0/users

查询参数：

• 工作区- 用于筛选用户的工作区GID

示例：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/users?workspace=1234567890&opt_fields=name,email')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "data": [
    {
      "gid": "1234567890",
      "name": "Alice Johnson",
      "email": "alice.johnson@acme.com"
    }
  ]
}

获取当前用户

GET /asana/api/1.0/users/me

获取用户

GET /asana/api/1.0/users/{user_gid}

获取团队中的用户

GET /asana/api/1.0/teams/{team_gid}/users

获取工作区中的用户

GET /asana/api/1.0/workspaces/{workspace_gid}/users

Webhooks

获取多个Webhook

GET /asana/api/1.0/webhooks

查询参数：

• 工作区- 工作区GID（必需）
• 资源- 要筛选的资源GID

示例：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/webhooks?workspace=1234567890')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建Webhook

注意：Asana在创建Webhook时会验证目标URL是否可达并返回200状态码。

POST /asana/api/1.0/webhooks
Content-Type: application/json

{
  "data": {
    "resource": "PROJECT_OR_TASK_GID",
    "target": "https://example.com/webhook",
    "filters": [
      {
        "resource_type": "task",
        "action": "changed",
        "fields": ["completed", "due_on"]
      }
    ]
  }
}

示例：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'data': {'resource': '1234567890', 'target': 'https://example.com/webhook'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/webhooks', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "data": {
    "gid": "1234567890",
    "resource": {
      "gid": "1234567890",
      "name": "Q1 Project"
    },
    "target": "https://example.com/webhook",
    "active": true
  }
}

获取Webhook

GET /asana/api/1.0/webhooks/{webhook_gid}

更新Webhook

PUT /asana/api/1.0/webhooks/{webhook_gid}

删除Webhook

DELETE /asana/api/1.0/webhooks/{webhook_gid}

返回200 OK成功时返回空数据。

分页

Asana使用基于游标的分页。请使用偏移量用于分页：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/asana/api/1.0/tasks?project=1234567890&limit=50&offset=OFFSET_TOKEN')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

当存在更多结果时，响应包含：next_page当存在更多结果时：

{
  "data": [...],
  "next_page": {
    "offset": "eyJ0eXBlIjoib2Zmc2V0IiwidmFsdWUiOjUwfQ",
    "path": "/tasks?project=1234567890&limit=50&offset=eyJ0eXBlIjoib2Zmc2V0IiwidmFsdWUiOjUwfQ",
    "uri": "https://app.asana.com/api/1.0/tasks?project=1234567890&limit=50&offset=eyJ0eXBlIjoib2Zmc2V0IiwidmFsdWUiOjUwfQ"
  }
}

代码示例

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/asana/api/1.0/tasks?project=1234567890',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/asana/api/1.0/tasks',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'project': '1234567890'}
)
data = response.json()

注意事项

• 资源ID（GID）是字符串
• 时间戳采用 ISO 8601 格式
• 使用opt_fields来指定要返回的字段
• 工作区是最高级别的组织单位
• 组织是代表公司的特殊工作区
• 重要提示：使用 curl 命令时，如果 URL 包含括号，请使用curl -g当 URL 包含括号时字段[],排序[],记录[]) 以禁用通配符解析
• 重要提示：当通过管道将 curl 输出传递给jq或其他命令时，环境变量如$MATON_API_KEY在某些 shell 环境中可能无法正确展开。通过管道传递时，您可能会遇到“无效的 API 密钥”错误。

错误处理

故障排除：API 密钥问题

1. 检查是否已设置MATON_API_KEY环境变量：

echo $MATON_API_KEY

2. 通过列出连接来验证 API 密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排除：无效的应用名称

1. 请确保您的 URL 路径以asana开头。例如：

• 正确示例：https://gateway.maton.ai/asana/api/1.0/tasks
• 错误示例：https://gateway.maton.ai/api/1.0/tasks

资源

• Asana API 文档
• API 参考
• LLM 参考
• Maton 社区
• Maton 支持