# 结论
TAPD API 需求、缺陷、任务自定义优先级兼容指引：
建议使用所见即所得，无映射关系的 priority_label 字段。
# 之前：
curl -u 'client_id:client_secret' -d 'priority=4&workspace_id=10104801&id=1010104801000191608' 'https://api.tapd.cn/stories'
# 现在：
curl -u 'client_id:client_secret' -d 'priority_label=High&workspace_id=10104801&id=1010104801000191608' 'https://api.tapd.cn/stories'
# 背景
随着越来越多团队提出自定义优先级的需要，TAPD 团队着手了产品规划、兼容与迁移方案准备、灰度方案准备、和相关实现的开发。为了尽可能地保持平滑适配，我们启用了新的优先级字段 priority_label，按照设想：
- priority_label 会按照显示值与实际值一样。比如这是旧的需求优先级字段，是个 map 映射：
| 取值 | 字面值 |
|---|---|
| 4 | High |
| 3 | Middle |
| 2 | Low |
| 1 | Nice To Have |
- 旧字段的值会通过脚本迁移到 priority_label。 同时为了兼容，对旧优先级字段 priority 的读写，会自动转换成对 priority_label 字段的读写
# 自定义优先级对 TAPD API 的影响
# 阶段一：平滑迁移阶段（当前阶段）
只要项目没开启自定义优先级，通过 API 对旧 priority 字段读写没什么影响。同时已经支持了读写 priority_label 字段 。目前是这个阶段。
这阶段我们建议使用团队尽快迁移到priority_label 字段。
# 阶段二：开放配置自定义优先级阶段
这个阶段，会开放项目配置自定义优先级入口。
- 如果项目没配置自定义优先级，则对 API 调用无影响，priority 字段及旧的 map 映射都能使用。
- 项目一旦配置了自定义优先级，这时候优先级取值会发生变化，就必须要使用
priority_label字段。比如项目加了个“非常高”的优先级，返回的需求出现 priority=非常高 的取值，这会不会导致代码崩溃，需要使用方具体评估。
# 第三方系统适配自定义优先级字段建议
- 字段从 priority 改成对 priority_label ，类型还是 string
- 传值不需要再做 High -> 4 这样的映射了，直接传 High
- 后面优先级的取值范围，还是可以继续从 get_fields_info 接口获取
- 阶段二灰度时间没定，后续会继续同步进展。留下改造时间
# 具体适配参考
# 需求
# 获取需求
获取高优先级的需求
新：
curl -u 'client_id:client_secret' 'https://api.tapd.cn/stories?workspace_id=10104801&priority_label=High'
旧：
curl -u 'client_id:client_secret' 'https://api.tapd.cn/stories?workspace_id=10104801&priority=3'
# 创建需求
创建一条优先级为 High 的需求
新：
curl -u 'client_id:client_secret' -d 'priority_label=High&workspace_id=10104801&name=新高优先级需求' 'https://api.tapd.cn/stories'
旧：
curl -u 'client_id:client_secret' -d 'priority=4&workspace_id=10104801&name=高优先级需求' 'https://api.tapd.cn/stories'
# 缺陷
# 获取缺陷
获取低优先级的缺陷
新：
curl -u 'client_id:client_secret' 'https://api.tapd.cn/bugs?workspace_id=10104801&priority_label=低'
旧：
curl -u 'client_id:client_secret' 'https://api.tapd.cn/bugs?workspace_id=10104801&priority=low'
# 创建缺陷
创建一条优先级为 高 的缺陷
新：
curl -u 'client_id:client_secret' -d 'priority_label=高&workspace_id=10104801&title=新高优先级缺陷' 'https://api.tapd.cn/bugs'
旧：
curl -u 'client_id:client_secret' -d 'priority=high&workspace_id=10104801&title=高优先级缺陷' 'https://api.tapd.cn/bugs'
# 任务
# 获取任务
获取高优先级的任务
新：
curl -u 'client_id:client_secret' 'https://api.tapd.cn/tasks?workspace_id=10104801&priority_label=High'
旧：
curl -u 'client_id:client_secret' 'https://api.tapd.cn/tasks?workspace_id=10104801&priority=3'
# 创建任务
创建一条优先级为 High 的任务
新：
curl -u 'client_id:client_secret' -d 'priority_label=High&workspace_id=10104801&name=新高优先级任务' 'https://api.tapd.cn/tasks'
旧：
curl -u 'client_id:client_secret' -d 'priority=4&workspace_id=10104801&name=高优先级任务' 'https://api.tapd.cn/tasks'