介绍
# Trello
通过托管的 OAuth 身份验证访问 Trello API。管理看板、列表、卡片、检查清单、标签和成员，以进行项目和任务管理。
## 快速开始
```bash # Get boards for current user python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/trello/1/members/me/boards') 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/trello/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Trello API 端点路径。网关将请求代理到 `api.trello.com` 并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization header 中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取您的 API 密钥
1. 在 [maton.ai](https://maton.ai) 登录或创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Trello OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=trello&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 ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'trello'}).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 ```
### 获取连接
```bash 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 ```
**响应：** ```json { "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": "trello", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash 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 ```
### 指定连接
如果您有多个 Trello 连接，请使用 `Maton-Connection` header 指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/trello/1/members/me/boards') 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 参考
### 成员
#### 获取当前成员
```bash GET /trello/1/members/me ```
#### 获取成员的看板
```bash GET /trello/1/members/me/boards ```
查询参数： - `filter` - 筛选看板：`all`、`open`、`closed`、`members`、`organization`、`starred` - `fields` - 要包含的以逗号分隔的字段
### 看板
#### 获取看板
```bash GET /trello/1/boards/{id} ```
查询参数： - `fields` - 以逗号分隔的字段 - `lists` - 包含列表：`all`、`open`、`closed`、`none` - `cards` - 包含卡片：`all`、`open`、`closed`、`none` - `members` - 包含成员：`all`、`none`
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/trello/1/boards/BOARD_ID?lists=open&cards=open') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 创建看板
```bash POST /trello/1/boards Content-Type: application/json
{ "name": "Project Alpha", "desc": "Main project board", "defaultLists": false, "prefs_permissionLevel": "private" } ```
#### 更新看板
```bash PUT /trello/1/boards/{id} Content-Type: application/json
{ "name": "Project Alpha - Updated", "desc": "Updated description" } ```
#### 删除看板
```bash DELETE /trello/1/boards/{id} ```
#### 获取看板列表
```bash GET /trello/1/boards/{id}/lists ```
查询参数： - `filter` - 筛选：`all`、`open`、`closed`、`none`
#### 获取看板卡片
```bash GET /trello/1/boards/{id}/cards ```
#### 获取看板成员
```bash GET /trello/1/boards/{id}/members ```
### 列表
#### 获取列表
```bash GET /trello/1/lists/{id} ```
#### 创建列表
```bash POST /trello/1/lists Content-Type: application/json
{ "name": "To Do", "idBoard": "BOARD_ID", "pos": "top" } ```
#### 更新列表
```bash PUT /trello/1/lists/{id} Content-Type: application/json
{ "name": "In Progress" } ```
#### 归档列表
```bash PUT /trello/1/lists/{id}/closed Content-Type: application/json
{ "value": true } ```
#### 获取列表中的卡片
```bash GET /trello/1/lists/{id}/cards ```
#### 移动列表中的所有卡片
```bash POST /trello/1/lists/{id}/moveAllCards Content-Type: application/json
{ "idBoard": "BOARD_ID", "idList": "TARGET_LIST_ID" } ```
### 卡片
#### 获取卡片
```bash GET /trello/1/cards/{id} ```
查询参数： - `fields` - 以逗号分隔的字段 - `members` - 包含成员 (true/false) - `checklists` - 包含检查清单：`all`、`none` - `attachments` - 包含附件 (true/false)
#### 创建卡片
```bash POST /trello/1/cards Content-Type: application/json
{ "name": "Implement feature X", "desc": "Description of the task", "idList": "LIST_ID", "pos": "bottom", "due": "2025-03-30T12:00:00.000Z", "idMembers": ["MEMBER_ID"], "idLabels": ["LABEL_ID"] } ```
#### 更新卡片
```bash PUT /trello/1/cards/{id} Content-Type: application/json
{ "name": "Updated card name", "desc": "Updated description", "due": "2025-04-15T12:00:00.000Z", "dueComplete": false } ```
#### 移动卡片到列表
```bash PUT /trello/1/cards/{id} Content-Type: application/json
{ "idList": "NEW_LIST_ID", "pos": "top" } ```
#### 删除卡片
```bash DELETE /trello/1/cards/{id} ```
#### 为卡片添加评论
```bash POST /trello/1/cards/{id}/actions/comments Content-Type: application/json
{ "text": "This is a comment" } ```
#### 为卡片添加成员
```bash POST /trello/1/cards/{id}/idMembers Content-Type: application/json
{ "value": "MEMBER_ID" } ```
#### 从卡片移除成员
```bash DELETE /trello/1/cards/{id}/idMembers/{idMember} ```
#### 为卡片添加标签
```bash POST /trello/1/cards/{id}/idLabels Content-Type: application/json
{ "value": "LABEL_ID" } ```
### 检查清单
#### 获取检查清单
```bash GET /trello/1/checklists/{id} ```
#### 创建检查清单
```bash POST /trello/1/checklists Content-Type: application/json
{ "idCard": "CARD_ID", "name": "Task Checklist" } ```
#### 创建检查清单项目
```bash POST /trello/1/checklists/{id}/checkItems Content-Type: application/json
{ "name": "Subtask 1", "pos": "bottom", "checked": false } ```
#### 更新检查清单项目
```bash PUT /trello/1/cards/{cardId}/checkItem/{checkItemId} Content-Type: application/json
{ "state": "complete" } ```
#### 删除检查清单
```bash DELETE /trello/1/checklists/{id} ```
### 标签
#### 获取看板标签
```bash GET /trello/1/boards/{id}/labels ```
#### 创建标签
```bash POST /trello/1/labels Content-Type: application/json
{ "name": "High Priority", "color": "red", "idBoard": "BOARD_ID" } ```
颜色：`yellow`、`purple`、`blue`、`red`、`green`、`orange`、`black`、`sky`、`pink`、`lime`、`null` (无颜色)
#### 更新标签
```bash PUT /trello/1/labels/{id} Content-Type: application/json
{ "name": "Critical", "color": "red" } ```
#### 删除标签
```bash DELETE /trello/1/labels/{id} ```
### 搜索
#### 搜索全部
```bash GET /trello/1/search?query=keyword&modelTypes=cards,boards ```
查询参数： - `query` - 搜索查询 (必需) - `modelTypes` - 以逗号分隔：`actions`、`boards`、`cards`、`members`、`organizations` - `board_fields` - 返回的看板字段 - `card_fields` - 返回的卡片字段 - `cards_limit` - 返回的最大卡片数 (1-1000)
## 代码示例
### JavaScript
```javascript const headers = { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` };
// Get boards const boards = await fetch( 'https://gateway.maton.ai/trello/1/members/me/boards', { headers } ).then(r => r.json());
// Create card await fetch( 'https://gateway.maton.ai/trello/1/cards', { method: 'POST', headers: { ...headers, 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'New Task', idList: 'LIST_ID', desc: 'Task description' }) } ); ```
### Python
```python import os import requests
headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
# Get boards boards = requests.get( 'https://gateway.maton.ai/trello/1/members/me/boards', headers=headers ).json()
# Create card response = requests.post( 'https://gateway.maton.ai/trello/1/cards', headers=headers, json={ 'name': 'New Task', 'idList': 'LIST_ID', 'desc': 'Task description' } ) ```
## 注意事项
- ID 是 24 个字符的字母数字字符串 - 使用 `me` 来引用已认证的用户 - 日期采用 ISO 8601 格式 - `pos` 可以是 `top`、`bottom` 或正数 - 列表中的卡片位置是浮点数 - 使用 `fields` 参数来限制返回的数据并提高性能 - 可以使用 `filter=closed` 检索已归档的项目 - 重要：使用 curl 命令时，如果 URL 包含括号（`fields[]`、`sort[]`、`records[]`），请使用 `curl -g` 以禁用 glob 解析 - 重要：当将 curl 输出通过管道传递给 `jq` 或其他命令时，某些 shell 环境中的环境变量（如 `$MATON_API_KEY`）可能无法正确展开。通过管道传递时，您可能会遇到“Invalid API key”错误。
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Trello 连接或请求无效 | | 401 | Maton API 密钥无效或缺失 | | 404 | 未找到看板、列表或卡片 | | 429 | 速率受限 (每个账户每秒 10 次请求) | | 4xx/5xx | 来自 Trello API 的透传错误 |
### 故障排除：API 密钥问题
1. 检查 `MATON_API_KEY` 环境变量是否已设置：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash 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 路径以 `trello` 开头。例如：
- 正确：`https://gateway.maton.ai/trello/1/members/me/boards` - 错误：`https://gateway.maton.ai/1/members/me/boards`
## 资源
- [Trello API 概述](https://developer.atlassian.com/cloud/trello/rest/api-group-actions/) - [看板](https://developer.atlassian.com/cloud/trello/rest/api-group-boards/) - [列表](https://developer.atlassian.com/cloud/trello/rest/api-group-lists/) - [卡片](https://developer.atlassian.com/cloud/trello/rest/api-group-cards/) - [检查清单](https://developer.atlassian.com/cloud/trello/rest/api-group-checklists/) - [标签](https://developer.atlassian.com/cloud/trello/rest/api-group-labels/) - [成员](https://developer.atlassian.com/cloud/trello/rest/api-group-members/) - [搜索](https://developer.atlassian.com/cloud/trello/rest/api-group-search/) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])