# 说明
返回符合查询条件的所有任务变更历史（分页显示，默认一页30条）
# 提示
如果需要做状态停留时长分析，请直接使用 获取状态流转时间接口
# url
https://api.tapd.cn/task_changes
# 支持格式
JSON/XML（默认JSON格式）
# HTTP请求方式
GET
# 请求数限制
created参数与task_id参数二选一必填。即 task_id、created 两个参数至少填写一个- 其中 created 参数要填写成日期格式，比如 created=2022-02-22，则返回 2022-02-22 这一天的变更历史
- 默认返回 30 条。可通过传 limit 参数设置，最大取 100。也可以传 page 参数翻页
# 请求参数
| 字段名 | 必选 | 类型及范围 | 说明 | 特殊规则 |
|---|---|---|---|---|
| id | 否 | integer | id | 支持多ID查询 |
| workspace_id | 是 | integer | 项目ID | |
| task_id | 否 | integer | 任务ID | |
| creator | 否 | string | 创建人（操作人） | |
| created | 否 | datetime | 创建时间（变更时间） | 支持时间查询 |
| change_summary | 否 | string | 需求变更描述 | |
| comment | 否 | string | 评论 | |
| changes | 否 | string | 变更详细记录 | |
| entity_type | 否 | string | 变更的对象类型 | |
| need_parse_changes | 否 | integer | 设置field_changes字段是否返回（默认取 1。取 0 则不返回） | |
| limit | 否 | integer | 设置返回数量限制，默认为30 | |
| page | 否 | integer | 返回当前数量限制下第N页的数据，默认为1（第一页） | |
| order | 否 | string | 排序规则，规则：字段名 ASC或者DESC，然后 urlencode | 如按创建时间逆序：order=created%20desc |
| fields | 否 | string | 设置获取的字段，多个字段间以','逗号隔开 |
# 调用示例及返回结果
# 获取项目下任务变更历史
# curl 使用 Basic Auth 鉴权调用示例
curl -u 'api_user:api_password' 'https://api.tapd.cn/task_changes?workspace_id=10158231&limit=2'
#
# 返回结果
{
"status": 1,
"data": [
{
"WorkitemChange": {
"id": "1010158231046789917",
"workspace_id": "10158231",
"creator": "anyechen",
"created": "2020-02-28 00:55:03",
"change_summary": "open",
"comment": null,
"changes": "[{\"field\":\"effort\",\"value_before\":\"0\",\"value_after\":\"10\"}]",
"entity_type": "Task",
"task_id": "1010158231500600411"
}
},
{
"WorkitemChange": {
"id": "1010158231046789915",
"workspace_id": "10158231",
"creator": "anyechen",
"created": "2020-02-28 00:54:56",
"change_summary": null,
"comment": null,
"changes": "[{\"field\":\"status\",\"value_before\":null,\"value_after\":\"open\"}]",
"entity_type": "Task",
"task_id": "1010158231500600411"
}
}
],
"info": "success"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 获取任务ID为 1010158231500600411 的任务变更历史
# curl 使用 Basic Auth 鉴权调用示例
curl -u 'api_user:api_password' 'https://api.tapd.cn/task_changes?workspace_id=10158231&task_id=1010158231500600411'
# 返回结果
{
"status": 1,
"data": [
{
"WorkitemChange": {
"id": "1010158231046789917",
"workspace_id": "10158231",
"creator": "anyechen",
"created": "2020-02-28 00:55:03",
"change_summary": "open",
"comment": null,
"changes": "[{\"field\":\"effort\",\"value_before\":\"0\",\"value_after\":\"10\"}]",
"entity_type": "Task",
"task_id": "1010158231500600411"
}
},
{
"WorkitemChange": {
"id": "1010158231046789915",
"workspace_id": "10158231",
"creator": "anyechen",
"created": "2020-02-28 00:54:56",
"change_summary": null,
"comment": null,
"changes": "[{\"field\":\"status\",\"value_before\":null,\"value_after\":\"open\"}]",
"entity_type": "Task",
"task_id": "1010158231500600411"
}
}
],
"info": "success"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 任务变更历史字段说明
# 任务变更历史重要字段说明
| 字段 | 说明 |
|---|---|
| id | id |
| workspace_id | 项目ID |
| creator | 创建人（操作人） |
| created | 创建时间（变更时间） |
| change_summary | 需求变更描述 |
| comment | 评论 |
| changes | 变更详细记录 |
| entity_type | 变更的对象类型 |
# 最佳实践
# 做状态停留时长分析
如果需要做状态停留时长分析，请直接使用 获取状态流转时间接口。
# 全量同步变更历史数据
如果需要同步项目全量状态变更历史数据，可以按照如下步骤：
- 使用获取任务数据接口，分页获取任务的ID。比如
https://api.tapd.cn/tasks?workspace_id=项目ID&limit=30&page=1&fields=id - 根据步骤1获取到的任务ID，加到 task_id 参数里面，分页获取变更历史数据。比如
https://api.tapd.cn/task_changes?workspace_id=项目ID&task_id=任务ID1,任务ID2,任务3&limit=30&page=1 - 重复步骤1、步骤2直到拿到所有任务的变更历史
# 增量同步变更历史数据
因为变更历史数据不会变，只增不减。所以可以传递 created 参数来增量获取变更历史数据。参考这样：
- 传递 created=日期 。比如
https://api.tapd.cn/task_changes?workspace_id=项目ID&created=2022-02-22&limit=30&page=1来获取某天的变更历史数据