时间字段
枚举字段
模糊匹配
不等于查询
多ID查询
多人员查询
特殊查询
特殊传值
- 富文本类型自定义字段传值
分页及翻页
- 深分页限制与游标翻页
Python 语言调用 TAPD API

# 请求地址

https://api.tapd.cn

# 参数格式

如果是 GET 请求，参数统一放 URL里面，并做 urlencode。比如 order=id%20desc
如果是 POST 请求，支持 application/x-www-form-urlencoded Key-Value 格式或者 application/json json 格式，其中要注意：
1. 如果POST参数是 json 格式，请求头要加上： Content-Type: application/json
2. 如果POST参数是 Key-Value 格式，请求头注意加上： Content-Type: application/x-www-form-urlencoded
3. 如果是文件上传的接口，请求头注意加上：Content-Type: multipart/form-data

# 如何查看项目ID

tapd.woa.com 进入对应项目空间，点击左上角项目名称，查看项目id

# 返回值

返回值支持 json 及 xml格式，默认是 json，可通过在URL中传入 __format 参数来控制。返回值结构都由 status、info、data 三个字段组成，具体作用如下表：

字段	说明
status	返回的状态。1 代表请求成功，其它代表失败
info	返回说明。如果出错，这里会给出出错信息
data	数据部分

# 认证

面对企业用户，TAPD API 采用 HTTP BASIC AUTH 认证。HTTP BASIC AUTH使用具体可看这里：API配置指引

# 帐号申请

目前TAPD API是TAPD的商业化模块，TAPD企业版的公司管理员可以在公司管理>开放集成>API账号管理中申请试用90天。

# 数据查询接口特别说明

# 时间字段

时间类型支持 <、> 和 ~ 操作符调用方式为： curl –u 'api_user:api_password' 'https://api.tapd.cn/stories/count?workspace_id=20003271&created=<2016-01-01' curl –u 'api_user:api_password' 'https://api.tapd.cn/stories/count?workspace_id=20003271&created=>2016-01-01' curl –u 'api_user:api_password' 'https://api.tapd.cn/stories/count?workspace_id=20003271&created=2016-02-01~2016-02-29'

要特别注意等号的位置和日期格式，支持时间段查询如：created=2024-12-23 14:00:00~2024-12-23 23:59:00

# 枚举字段

枚举类型支持 | 操作符，调用方式为： curl –u 'api_user:api_password' 'https://api.tapd.cn/stories/count?workspace_id=20003271&status=new|in_progress'

# 模糊匹配

就是 like 查询，调用方式为： curl –u 'api_user:api_password' 'https://api.tapd.cn/stories/count?workspace_id=20003271&title=api'

# 不等于查询

支持 <> 查询，调用方式为： curl –u 'api_user:api_password' 'https://api.tapd.cn/stories.json?workspace_id=20003271&iteration_id=<>1120003271001000275'

# 多ID查询

使用英文逗号 , 分开，调用方式为： curl –u 'api_user:api_password' 'https://api.tapd.cn/stories?workspace_id=20003271&id=1120003271001000042,1120003271001000043,1120003271001000044'

# 多人员查询

使用 | 表示或，如找出缺陷参与人是 A 或者 B 的： curl –u 'api_user:api_password' 'https://api.tapd.cn/bugs?workspace_id=20003271&participator=A|B' 使用 ; 表示与，如找出缺陷参与人是 A 并且是B 的： curl –u 'api_user:api_password' 'https://api.tapd.cn/bugs?workspace_id=20003271&participator=A;B'

# 特殊查询

TAPD API 提供 field=OP 特殊的查询语法，以便在所有字段上，都能使用这些特殊查询规则。

# field=LIKE

支持模糊查询。比如： curl –u 'api_user:api_password' 'https://api.tapd.cn/stories/count?workspace_id=20003271&custom_field_one=LIKE<安卓>'

# field=LIKE_OR

多值模糊查询，使用竖线分隔值，满足任一值则为匹配。比如： curl –u 'api_user:api_password' 'https://api.tapd.cn/stories/count?workspace_id=20003271&name=LIKE_OR<安卓|苹果>'

# field=EQ

全等匹配查询。比如： curl –u 'api_user:api_password' 'https://api.tapd.cn/stories/count?workspace_id=20003271&name=EQ<这是一个很长很长很长的标题>'

# field=NOT_EQ

全等不匹配查询。比如： curl –u 'api_user:api_password' 'https://api.tapd.cn/stories/count?workspace_id=20003271&name=NOT_EQ<这是一个很长很长很长的标题>'

# field=CONTAINS

目前仅支持需求、缺陷、任务类型对象中，针对多选下拉、复选框类型的多选自定义字段。查询同时包含所有指定候选值的对象，如找出custom_field_1字段同时选中value1、value2、value3的对象: curl –u 'api_user:api_password' 'https://api.tapd.cn/stories?workspace_id=20003271&custom_field_1=CONTAINS<value1|value2|value3>'

# field=CONTAINS_OR

目前仅支持需求、缺陷、任务类型对象中，针对多选下拉、复选框类型的多选自定义字段。查询包含任一指定候选值的对象，如找出custom_field_1字段选中value1或value2或value3的对象: curl –u 'api_user:api_password' 'https://api.tapd.cn/stories?workspace_id=20003271&custom_field_1=CONTAINS_OR<value1|value2|value3>'

# field=USER_OR

目前仅支持需求、缺陷、任务类型对象中的用户相关字段。查询包含任一指定用户的对象，如找出处理人包含user1或user2或user3的对象: curl –u 'api_user:api_password' 'https://api.tapd.cn/stories?workspace_id=20003271&owner=USER_OR<user1|user2|user3>'

# 特殊传值

# 富文本类型自定义字段传值

创建、更新需求或缺陷时，如果自定义字段配置为“富文本”类型，可以传入 HTML 或 Markdown 内容。以下以 custom_field_8 为例，请替换为目标项目中实际的富文本自定义字段系统名；普通文本等其他类型的字段不适用此规则。

# 富文本字符串（推荐）

优先推荐直接传入 HTML 富文本字符串，后台按 HTML 模式处理，无需额外封装 content_type、html_content 等属性。普通文本字符串也按 HTML 模式处理。

以创建缺陷为例，POST https://api.tapd.cn/bugs，请求头使用 Content-Type: application/json，请求体如下：

{
    "workspace_id": "20003271",
    "title": "富文本字段示例",
    "custom_field_8": "<p>问题说明：<strong>保存失败</strong></p>"
}

1
2
3
4
5

# JSON 字符串（可选）

需要指定内容格式（例如 Markdown）时，可以先组装包含以下属性的 JSON 结构，再序列化为字符串，作为自定义字段的值传入。**不要直接将 JSON 对象作为 custom_field_8 的值。**下表描述的是序列化前的结构：

属性	类型	必填条件	说明
`content_type`	string / integer	必填	`html` 或 `1` 表示 HTML；`markdown` 或 `2` 表示 Markdown。也兼容字符串 `"1"`、`"2"`。
`html_content`	string	HTML 模式必填	HTML 正文。Markdown 模式下，未传、传空字符串或仅空白时，后台会根据 `markdown_content` 自动生成 HTML；已传非空 HTML 时保留该值，请确保与 Markdown 内容一致。
`markdown_content`	string	Markdown 模式必填	Markdown 原文。HTML 模式下可以省略或传空字符串。

使用这种可选格式时，先将上述结构序列化为 JSON 字符串，再放入请求体。例如 JavaScript 使用 JSON.stringify，Python 使用 json.dumps。application/json 请求体中的内部引号和换行由 JSON 序列化工具转义；表单请求则对字段值进行表单编码。
不要把 content_type、html_content 等属性放在请求参数的顶层。
直接传 Markdown 字符串不会自动识别为 Markdown，需使用这种 JSON 字符串格式。
正文属性必须为字符串，允许空字符串；不能传数组、对象或 null。格式类型非法、缺少当前模式必填正文或正文类型不合法时，接口返回参数错误。

# Markdown 传值示例

以创建需求为例，POST https://api.tapd.cn/stories，请求头使用 Content-Type: application/json。将 content_type 和 Markdown 原文一起序列化为字符串传入，后台会自动补齐 HTML：

{
    "workspace_id": "20003271",
    "name": "Markdown 字段示例",
    "custom_field_8": "{\"content_type\":\"markdown\",\"markdown_content\":\"## 需求说明\\n\\n支持 **富文本** 自定义字段。\"}"
}

1
2
3
4
5

上例中的 \\n 是请求体 JSON 中的转义写法；请求体解析后得到字段值字符串，再解析该字符串，才能得到 Markdown 正文中的换行。

自动转换失败时，本次工作项不会保存，接口返回服务错误；可以重试，或同时提供对应的非空 html_content。批量更新时，转换失败仅影响当前条目，请检查每条更新结果。

# 表单传值示例

表单方式也推荐直接传 HTML 富文本字符串，使用 --data-urlencode 完成字段值编码：

curl -u 'api_user:api_password' '{{ $page.apiHost }}/bugs' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'workspace_id=20003271' \
    --data-urlencode 'title=富文本字段示例' \
    --data-urlencode 'custom_field_8=<p>问题说明：<strong>保存失败</strong></p>'

1
2
3
4
5

# 更新与清空

更新时按对应接口要求传入工作项 id、项目 ID 等参数，富文本字段格式与创建时相同。未传某个字段表示不修改该字段；一次请求可以更新多个富文本自定义字段。
清空字段可以直接传 "custom_field_8": ""。如果保留 Markdown 模式，JSON 请求体中的字段写为 "custom_field_8": "{\"content_type\":\"markdown\",\"markdown_content\":\"\",\"html_content\":\"\"}"，仍然传字符串，不要传对象。

# 分页及翻页

获取数据接口，基本默认是只取 30 条数据。可以通过传递 limit 参数获取更多，比如：limit=100。但 limit 的上限是 200，超过这个上限的数据，可以传递 page 参数来翻页。比如 limit=10&page=2，则是数据每页10条数据，取第二页的。数据的总条目数，一般可以通过对应的 count 计数接口来获取。

# 深分页限制与游标翻页

page * limit 最大支持 20000（即 limit=200 时最多翻到第 100 页）。超过该上限的深分页请求，服务端会返回错误。

需要遍历更多数据时，请改用游标（cursor）方式翻页：

游标取值：上一页返回结果中最后一条数据的 id；
翻页时传递 cursor 参数，接口会从该游标位置继续向后取一页数据，无需再递增 page；
游标翻页仅支持 id 排序：大部分接口默认按 id DESC 排序，可直接传 cursor；但部分接口未设置默认排序（如 bugs、attachments 等），这些接口必须显式指定 order=id asc 或 order=id desc，否则 cursor 参数不生效。其他排序字段请控制在 20000 的翻页深度以内；
翻页过程中请保持查询条件（过滤参数、limit、排序）不变，并串行翻页（同一查询条件不要并发翻页）。

调用示例（按 id 逆序遍历项目全部测试用例）：

# 第一页：不传 cursor，按默认 id DESC 排序取前 200 条
curl –u 'api_user:api_password' '{{ $page.apiHost }}/tcases?workspace_id=20003271&limit=200'

# 后续翻页：cursor 传上一页最后一条数据的 id
curl –u 'api_user:api_password' '{{ $page.apiHost }}/tcases?workspace_id=20003271&limit=200&cursor=10234567890123'

1
2
3
4
5

# Python 语言调用 TAPD API

使用 Python 语言调用 TAPD API，推荐使用 requests 库。 requests 安装文档：https://requests.readthedocs.io/en/latest/user/install/#install requests 快速上手文档：https://requests.readthedocs.io/en/latest/user/quickstart/ 下面是 Python 环境下使用 requests 来请求 TAPD API 的例子：

import requests
r = requests.get('[api地址]/quickstart/testauth', auth=('api_user', 'api_password'))
ret = r.text # 获取接口返回结果
print(ret) # Python 3
print ret # Python 2

1
2
3
4
5

← 事件通信示例 API配置指引 →