Microsoft To Do

通过托管的 OAuth 认证访问 Microsoft To Do API。通过完整的 CRUD 操作管理任务列表、任务、清单项目和链接资源。

快速开始

# List all task lists
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/microsoft-to-do/v1.0/me/todo/lists')
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/microsoft-to-do/{native-api-path}

将{native-api-path}替换为实际的 Microsoft Graph API 端点路径。网关会将请求代理到graph.microsoft.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. 创建账户前往
3. maton.ai/settings

复制您的 API 密钥

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

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=microsoft-to-do&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': 'microsoft-to-do'}).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": "microsoft-to-do",
    "metadata": {}
  }
}

在浏览器中打开返回的网址以完成 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

指定连接

如果您有多个 Microsoft To Do 连接，请通过Maton-Connection请求头指定要使用的连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/microsoft-to-do/v1.0/me/todo/lists')
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 /microsoft-to-do/v1.0/me/todo/lists

响应：

{
  "value": [
    {
      "id": "AAMkADIyAAAhrbPWAAA=",
      "displayName": "Tasks",
      "isOwner": true,
      "isShared": false,
      "wellknownListName": "defaultList"
    }
  ]
}

获取任务列表

GET /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}

创建任务列表

POST /microsoft-to-do/v1.0/me/todo/lists
Content-Type: application/json

{
  "displayName": "Travel items"
}

响应（201 已创建）：

{
  "id": "AAMkADIyAAAhrbPWAAA=",
  "displayName": "Travel items",
  "isOwner": true,
  "isShared": false,
  "wellknownListName": "none"
}

更新任务列表

PATCH /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}
Content-Type: application/json

{
  "displayName": "Vacation Plan"
}

删除任务列表

DELETE /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}

返回204 无内容成功时。

任务操作

列出任务

GET /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}/tasks

响应：

{
  "value": [
    {
      "id": "AlMKXwbQAAAJws6wcAAAA=",
      "title": "Buy groceries",
      "status": "notStarted",
      "importance": "normal",
      "isReminderOn": false,
      "createdDateTime": "2024-01-15T10:00:00Z",
      "lastModifiedDateTime": "2024-01-15T10:00:00Z",
      "body": {
        "content": "",
        "contentType": "text"
      },
      "categories": []
    }
  ]
}

获取任务

GET /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}/tasks/{taskId}

创建任务

POST /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}/tasks
Content-Type: application/json

{
  "title": "A new task",
  "importance": "high",
  "status": "notStarted",
  "categories": ["Important"],
  "dueDateTime": {
    "dateTime": "2024-12-31T17:00:00",
    "timeZone": "Eastern Standard Time"
  },
  "startDateTime": {
    "dateTime": "2024-12-01T08:00:00",
    "timeZone": "Eastern Standard Time"
  },
  "isReminderOn": true,
  "reminderDateTime": {
    "dateTime": "2024-12-01T09:00:00",
    "timeZone": "Eastern Standard Time"
  },
  "body": {
    "content": "Task details here",
    "contentType": "text"
  }
}

任务字段：

更新任务

PATCH /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}/tasks/{taskId}
Content-Type: application/json

{
  "status": "completed",
  "completedDateTime": {
    "dateTime": "2024-01-20T15:00:00",
    "timeZone": "UTC"
  }
}

删除任务

DELETE /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}/tasks/{taskId}

返回204 无内容成功时。

清单项操作

清单项是任务内的子任务。

列出清单项

GET /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}/tasks/{taskId}/checklistItems

响应：

{
  "value": [
    {
      "id": "51d8a471-2e9d-4f53-9937-c33a8742d28f",
      "displayName": "Create draft",
      "createdDateTime": "2024-01-17T05:22:14Z",
      "isChecked": false
    }
  ]
}

创建清单项

POST /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}/tasks/{taskId}/checklistItems
Content-Type: application/json

{
  "displayName": "Final sign-off from the team"
}

更新清单项

PATCH /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}/tasks/{taskId}/checklistItems/{checklistItemId}
Content-Type: application/json

{
  "isChecked": true
}

删除清单项

DELETE /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}/tasks/{taskId}/checklistItems/{checklistItemId}

返回204 无内容成功时。

链接资源操作

链接资源将任务连接到外部项目（例如，电子邮件、文件）。

列出关联的资源

GET /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}/tasks/{taskId}/linkedResources

响应：

{
  "value": [
    {
      "id": "f9cddce2-dce2-f9cd-e2dc-cdf9e2dccdf9",
      "webUrl": "https://example.com/item",
      "applicationName": "MyApp",
      "displayName": "Related Document",
      "externalId": "external-123"
    }
  ]
}

创建关联资源

POST /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}/tasks/{taskId}/linkedResources
Content-Type: application/json

{
  "webUrl": "https://example.com/item",
  "applicationName": "MyApp",
  "displayName": "Related Document",
  "externalId": "external-123"
}

删除关联资源

DELETE /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}/tasks/{taskId}/linkedResources/{linkedResourceId}

返回204 无内容成功时。

分页

Microsoft Graph 使用 OData 分页。使用$top来限制结果数量，并使用$skip进行偏移：

GET /microsoft-to-do/v1.0/me/todo/lists/{todoTaskListId}/tasks?$top=10&$skip=0

响应包含@odata.nextLink当存在更多结果时：

{
  "value": [...],
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/todo/lists/{id}/tasks?$skip=10"
}

代码示例

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/microsoft-to-do/v1.0/me/todo/lists',
  {
    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/microsoft-to-do/v1.0/me/todo/lists',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()

备注

• 任务列表ID和任务ID是不透明的字符串（例如，AAMkADIyAAAhrbPWAAA=）
• 时间戳默认使用UTC的ISO 8601格式
• 该dateTimeTimeZone类型需要同时包含dateTime和timeZone字段
• wellknownListName可以是defaultList、flaggedEmails或none
• 任务状态取值：未开始、进行中、已完成、等待他人、已推迟
• 任务重要性取值：低,正常,高
• 支持 OData 查询参数：$select,$filter,$orderby,$top,$skip
• 重要提示：使用 curl 命令时，若 URL 包含方括号，请使用curl -g以禁用通配符解析
• 重要提示：将 curl 输出通过管道传递给jq或其他命令时，某些 shell 环境中可能无法正确展开环境变量，例如$MATON_API_KEY 错误处理

状态

故障排除：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 路径以microsoft-to-do开头。例如：

• 正确：https://gateway.maton.ai/microsoft-to-do/v1.0/me/todo/lists
• 错误：https://gateway.maton.ai/v1.0/me/todo/lists

资源

• Microsoft To Do API 概览
• todoTaskList 资源
• todoTask 资源
• checklistItem 资源
• linkedResource 资源
• Maton 社区
• Maton 支持