Google Tasks

通过托管的OAuth认证访问Google Tasks API。使用完整的CRUD操作管理任务列表和任务。

快速开始

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

将{native-api-path}替换为实际的Google Tasks API端点路径。网关将请求代理至tasks.googleapis.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密钥

在以下网址管理您的Google Tasks OAuth连接https://ctrl.maton.ai。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-tasks&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': 'google-tasks'}).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": "0e13cacd-cec8-4b6b-9368-c62cc9b06dd9",
    "status": "ACTIVE",
    "creation_time": "2026-02-07T02:35:51.002199Z",
    "last_updated_time": "2026-02-07T05:32:30.369186Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-tasks",
    "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

指定连接

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

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-tasks/tasks/v1/users/@me/lists')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '0e13cacd-cec8-4b6b-9368-c62cc9b06dd9')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认的（最早的）活动连接。

API参考

任务列表

列出所有任务列表

GET /google-tasks/tasks/v1/users/@me/lists

查询参数：

• maxResults- 要返回的任务列表的最大数量（默认值：20，最大值：100）
• pageToken- 用于分页的令牌

响应：

{
  "kind": "tasks#taskLists",
  "etag": "\"OW7pv01-vgQ\"",
  "items": [
    {
      "kind": "tasks#taskList",
      "id": "MDEzMTQ2ODk4NDc2ODkyOTIyMTE6MDow",
      "etag": "\"Yz7ljQZ5Xuw\"",
      "title": "My Tasks",
      "updated": "2023-09-18T06:12:59.468Z",
      "selfLink": "https://www.googleapis.com/tasks/v1/users/@me/lists/MDEzMTQ2ODk4NDc2ODkyOTIyMTE6MDow"
    }
  ]
}

获取任务列表

GET /google-tasks/tasks/v1/users/@me/lists/{tasklistId}

创建任务列表

POST /google-tasks/tasks/v1/users/@me/lists
Content-Type: application/json

{
  "title": "New Task List"
}

响应：

{
  "kind": "tasks#taskList",
  "id": "OFYyU09veWMyWl84SjNQXw",
  "etag": "\"XTqLSxP4QZQ\"",
  "title": "New Task List",
  "updated": "2026-02-07T05:45:22.685Z",
  "selfLink": "https://www.googleapis.com/tasks/v1/users/@me/lists/OFYyU09veWMyWl84SjNQXw"
}

更新任务列表（PATCH - 部分更新）

PATCH /google-tasks/tasks/v1/users/@me/lists/{tasklistId}
Content-Type: application/json

{
  "title": "Updated Title"
}

更新任务列表（PUT - 完全替换）

PUT /google-tasks/tasks/v1/users/@me/lists/{tasklistId}
Content-Type: application/json

{
  "title": "Replaced Title"
}

删除任务列表

DELETE /google-tasks/tasks/v1/users/@me/lists/{tasklistId}

任务

列出任务

GET /google-tasks/tasks/v1/lists/{tasklistId}/tasks

查询参数：

• maxResults- 返回任务的最大数量（默认：20，最大值：100）
• pageToken- 用于分页的令牌
• showCompleted- 包含已完成任务（默认：true）
• showDeleted- 包含已删除任务（默认：false）
• showHidden- 包含隐藏任务（默认：false）
• dueMin- 截止日期下限（RFC 3339 时间戳）
• dueMax- 截止日期的上限（RFC 3339 时间戳）
• completedMin- 完成日期的下限（RFC 3339 时间戳）
• completedMax- 完成日期的上限（RFC 3339 时间戳）
• updatedMin- 最后更新时间下限（RFC 3339 时间戳）

响应：

{
  "kind": "tasks#tasks",
  "etag": "\"Jhh35adkRkU\"",
  "nextPageToken": "CgwI27nR6AUQsKHh7QIa...",
  "items": [
    {
      "kind": "tasks#task",
      "id": "blJQR1hfaXhSU0tMY3gwdg",
      "etag": "\"Uqc8Y3T9VOA\"",
      "title": "Example Task",
      "updated": "2020-11-09T21:17:08.911Z",
      "selfLink": "https://www.googleapis.com/tasks/v1/lists/.../tasks/blJQR1hfaXhSU0tMY3gwdg",
      "position": "00000000000000000000",
      "status": "needsAction",
      "due": "2020-12-08T00:00:00.000Z",
      "notes": "Task notes here",
      "links": [],
      "webViewLink": "https://tasks.google.com/task/nRPGX_ixRSKLcx0v?sa=6"
    }
  ]
}

获取任务

GET /google-tasks/tasks/v1/lists/{tasklistId}/tasks/{taskId}

创建任务

POST /google-tasks/tasks/v1/lists/{tasklistId}/tasks
Content-Type: application/json

{
  "title": "New Task",
  "notes": "Task description",
  "due": "2026-03-01T00:00:00.000Z"
}

查询参数（可选）：

• parent- 父任务ID（用于子任务）
• previous- 前一个同级任务ID（用于定位）

响应：

{
  "kind": "tasks#task",
  "id": "bkludnJmdjZIZWVFejBnYg",
  "etag": "\"EKX4SVb-Ljk\"",
  "title": "New Task",
  "updated": "2026-02-07T05:45:05.371Z",
  "selfLink": "https://www.googleapis.com/tasks/v1/lists/.../tasks/bkludnJmdjZIZWVFejBnYg",
  "position": "00000000000000000000",
  "notes": "Task description",
  "status": "needsAction",
  "due": "2026-03-01T00:00:00.000Z",
  "links": [],
  "webViewLink": "https://tasks.google.com/task/nInvrfv6HeeEz0gb?sa=6"
}

更新任务（PATCH - 部分更新）

PATCH /google-tasks/tasks/v1/lists/{tasklistId}/tasks/{taskId}
Content-Type: application/json

{
  "title": "Updated Task Title",
  "status": "completed"
}

响应：

{
  "kind": "tasks#task",
  "id": "bkludnJmdjZIZWVFejBnYg",
  "etag": "\"OeWHIDNj-os\"",
  "title": "Updated Task Title",
  "updated": "2026-02-07T05:45:15.334Z",
  "selfLink": "https://www.googleapis.com/tasks/v1/lists/.../tasks/bkludnJmdjZIZWVFejBnYg",
  "position": "00000000000000000000",
  "notes": "Task description",
  "status": "completed",
  "completed": "2026-02-07T05:45:15.307Z",
  "links": [],
  "webViewLink": "https://tasks.google.com/task/nInvrfv6HeeEz0gb?sa=6"
}

更新任务（PUT - 完全替换）

PUT /google-tasks/tasks/v1/lists/{tasklistId}/tasks/{taskId}
Content-Type: application/json

{
  "title": "Replaced Task",
  "notes": "New notes",
  "status": "needsAction"
}

删除任务

DELETE /google-tasks/tasks/v1/lists/{tasklistId}/tasks/{taskId}

移动任务

在任务列表中重新定位任务或更改其父任务。

POST /google-tasks/tasks/v1/lists/{tasklistId}/tasks/{taskId}/move

查询参数（可选）：

• parent- 新的父任务ID（用于将其设为子任务）
• previous- 前一个兄弟任务ID（用于在该任务之后定位）

响应：

{
  "kind": "tasks#task",
  "id": "VkI5bTEzazdvNzlYNWVycw",
  "etag": "\"Uplv6eL0sDo\"",
  "title": "Task B",
  "updated": "2026-02-07T05:45:36.801Z",
  "selfLink": "https://www.googleapis.com/tasks/v1/lists/.../tasks/VkI5bTEzazdvNzlYNWVycw",
  "position": "00000000000000000001",
  "status": "needsAction",
  "links": [],
  "webViewLink": "https://tasks.google.com/task/VB9m13k7o79X5ers?sa=6"
}

清除已完成任务

从任务列表中删除所有已完成的任务。

POST /google-tasks/tasks/v1/lists/{tasklistId}/clear

成功时返回 HTTP 204 No Content。

任务资源字段

任务列表资源字段

分页

使用maxResults和pageToken进行分页：

GET /google-tasks/tasks/v1/lists/{tasklistId}/tasks?maxResults=50

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

{
  "kind": "tasks#tasks",
  "etag": "...",
  "nextPageToken": "CgwI27nR6AUQsKHh7QIa...",
  "items": [...]
}

在后续请求中使用nextPageToken值：

GET /google-tasks/tasks/v1/lists/{tasklistId}/tasks?maxResults=50&pageToken=CgwI27nR6AUQsKHh7QIa...

代码示例

JavaScript

// List all task lists
const response = await fetch(
  'https://gateway.maton.ai/google-tasks/tasks/v1/users/@me/lists',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);

// Create a new task
const createResponse = await fetch(
  `https://gateway.maton.ai/google-tasks/tasks/v1/lists/${tasklistId}/tasks`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'New Task',
      notes: 'Task description',
      due: '2026-03-01T00:00:00.000Z'
    })
  }
);

Python

import os
import requests

# List all task lists
response = requests.get(
    'https://gateway.maton.ai/google-tasks/tasks/v1/users/@me/lists',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)

# Create a new task
create_response = requests.post(
    f'https://gateway.maton.ai/google-tasks/tasks/v1/lists/{tasklist_id}/tasks',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={
        'title': 'New Task',
        'notes': 'Task description',
        'due': '2026-03-01T00:00:00.000Z'
    }
)

注意事项

• 任务列表ID和任务ID为不透明字符串（采用Base64编码）
• 状态值包括"needsAction"（待处理）或"completed"（已完成）
• 截止日期采用RFC 3339时间戳格式
• 标题最大长度：1024个字符
• 备注最大长度：8192个字符
• 重要提示：使用curl命令时，若URL包含方括号，请使用curl -g以禁用通配符解析
• 重要提示：将curl输出通过管道传递给jq或其他命令时，某些shell环境中可能无法正确展开$MATON_API_KEY这类环境变量。通过管道传递时可能出现"Invalid API key"（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路径以google-tasks开头。例如：

• 正确示例：https://gateway.maton.ai/google-tasks/tasks/v1/users/@me/lists
• 错误示例：https://gateway.maton.ai/tasks/v1/users/@me/lists

资源

• Google Tasks API 概述
• 任务参考
• 任务列表参考
• 马顿社区
• 马顿支持