本文将详细介绍如何利用ClickUp API高效且准确地获取指定用户的逾期任务列表。我们将探讨现有方法的局限性，并重点推荐使用官方支持的`GetFilteredTeamTasks`接口，结合`assignees`和`due_date_lt`参数，实现精确的任务筛选，避免采用复杂的链式查询或未文档化的API，确保方案的稳定性和可维护性。
现有方案分析与局限性
在尝试通过ClickUp API获取指定用户的逾期任务时，开发者可能会遇到几种不同的思路。然而，这些思路往往伴随着效率低下或稳定性风险。
1. 未文档化的内部API
部分开发者可能会通过观察ClickUp应用的网络请求，发现一个形如 https://app.clickup.com/home/team/{team_id}/inbox 的内部API，配合 overdue_only: true 等参数来获取逾期任务ID列表。 局限性： 尽管这种方法看似直接，但由于其未在官方文档中公开，ClickUp随时可能对其进行修改、废弃或限制访问，导致集成方案失效。因此，不建议在生产环境中使用此类未文档化的接口。
2. 多层级遍历查询
另一种思路是遵循ClickUp的层级结构，即先获取团队下的所有空间（Spaces），再获取每个空间下的文件夹（Folders），接着获取每个文件夹下的列表（Lists）以及无文件夹列表（Folderless Lists），最后针对每个列表查询其中分配给特定用户的任务，并进行日期筛选。 局限性： 这种方法虽然完全依赖于官方文档，但其操作流程过于繁琐，需要大量的API请求和复杂的逻辑处理，效率低下且难以维护，不适用于简单地获取逾期任务的需求。
ClickUp API推荐方案：GetFilteredTeamTasks
根据ClickUp官方支持团队的建议，目前最推荐且高效的方法是使用 GetFilteredTeamTasks 接口。该接口允许通过丰富的查询参数直接筛选团队任务，从而精准地获取指定人员的逾期任务。
API端点
GET https://api.clickup.com/api/v2/team/{team_id}/task关键查询参数
要获取指定人员的逾期任务，我们需要组合使用以下两个核心参数：
-
assignees[]: 用于指定任务的分配人员。您需要提供一个或多个ClickUp用户ID。
- 示例: assignees[]=12345678
-
due_date_lt: 用于筛选截止日期在指定Unix时间戳（毫秒）之前的任务。这是判断任务是否“逾期”的关键。您需要提供一个表示当前时间的Unix时间戳（毫秒）。
- 示例: due_date_lt=1678886400000 (表示2023年3月15日00:00:00 UTC)
实践示例
假设我们要获取团队ID为 YOUR_TEAM_ID 下，分配给用户ID为 YOUR_ASSIGNEE_ID 的所有逾期任务。
首先，获取当前的Unix时间戳（毫秒）。例如，在Python中：
import time
current_unix_time_ms = int(time.time() * 1000)
print(f"当前Unix时间戳（毫秒）: {current_unix_time_ms}")然后，构建API请求URL：
import requests
import time
import os
# 假设这些值从配置或环境变量中获取
CLICKUP_API_TOKEN = os.getenv("CLICKUP_API_TOKEN", "YOUR_CLICKUP_API_TOKEN")
TEAM_ID = os.getenv("CLICKUP_TEAM_ID", "YOUR_TEAM_ID")
ASSIGNEE_ID = os.getenv("CLICKUP_ASSIGNEE_ID", "YOUR_ASSIGNEE_ID")
# 获取当前时间的Unix时间戳（毫秒）
current_unix_time_ms = int(time.time() * 1000)
# 构建请求URL
url = f"https://api.clickup.com/api/v2/team/{TEAM_ID}/task"
headers = {
"Authorization": CLICKUP_API_TOKEN,
"Content-Type": "application/json"
}
params = {
"assignees[]": ASSIGNEE_ID,
"due_date_lt": current_unix_time_ms,
"subtasks": "true", # 可选：是否包含子任务
"statuses[]": ["open", "to do", "in progress"] # 可选：只获取未完成状态的任务
}
try:
response = requests.get(url, headers=headers, params=params)
response.raise_for_status() # 检查HTTP请求是否成功
tasks_data = response.json()
print(f"找到 {len(tasks_data.get('tasks', []))} 个逾期任务。")
for task in tasks_data.get("tasks", []):
print(f"任务ID: {task['id']}, 名称: {task['name']}, 截止日期: {task.get('due_date')}")
except requests.exceptions.HTTPError as e:
print(f"HTTP错误: {e}")
print(f"响应内容: {response.text}")
except Exception as e:
print(f"发生错误: {e}")使用 curl 命令的示例：
# 替换 YOUR_CLICKUP_API_TOKEN, YOUR_TEAM_ID, YOUR_ASSIGNEE_ID # $(($(date +%s%N)/1000000)) 会在bash中生成当前时间的毫秒级Unix时间戳 curl -X GET \ "https://api.clickup.com/api/v2/team/YOUR_TEAM_ID/task?assignees[]=YOUR_ASSIGNEE_ID&due_date_lt=$(($(date +%s%N)/1000000))&subtasks=true&statuses[]=open&statuses[]=to%20do&statuses[]=in%20progress" \ -H "Authorization: YOUR_CLICKUP_API_TOKEN"
API参数详解
- team_id (路径参数): 您的ClickUp团队的唯一标识符。
- assignees[] (查询参数): 一个数组，包含一个或多个您希望筛选的用户的ID。
- due_date_lt (查询参数): 一个Unix时间戳（毫秒），表示截止日期必须在此时间点之前的任务才会被返回。
- subtasks (可选查询参数): 布尔值，设置为 true 可包含子任务。默认为 false。
- statuses[] (可选查询参数): 一个数组，包含您希望筛选的任务状态。例如：open, to do, in progress, complete 等。这对于只获取未完成的逾期任务非常有用。
- page (可选查询参数): 用于分页，指定返回结果的页码。
- per_page (可选查询参数): 每页返回的任务数量。
注意事项
- 时区处理： due_date_lt 参数通常期望UTC时间戳。在计算当前时间戳时，请确保考虑到服务器时区与ClickUp任务设置时区之间可能存在的差异，以避免潜在的日期偏差。通常，将本地时间转换为UTC后再获取Unix时间戳是更稳健的做法。
- API令牌： 确保您的ClickUp API令牌具有访问团队任务的足够权限。
- 分页处理： 如果团队中的任务数量较多，API响应可能会进行分页。您需要检查响应中的 last_page 和 page 字段，并根据需要通过 page 参数进行多次请求以获取所有数据。
- 错误处理： 在实际应用中，务必实现健壮的错误处理机制，以应对网络问题、API限流或无效参数等情况。
- API版本： ClickUp API会不断更新。请始终查阅最新的官方文档以获取最准确的接口信息和参数说明。
总结
通过 GetFilteredTeamTasks 接口，结合 assignees[] 和 due_date_lt 参数，我们可以高效且可靠地从ClickUp API获取指定用户的逾期任务列表。这种方法避免了使用未文档化的内部接口带来的风险，也简化了多层级遍历的复杂性，是目前最推荐的集成方案。遵循本文的指南和注意事项，您将能够构建稳定且功能强大的ClickUp集成。
