查询看板内容列表
GET /api/v5/org/{owner}/kanban/{kanban_id}/item_list
该接口用于查询指定组织下看板的内容项列表,支持按仓库、来源类型(issue/merge_request)、来源状态、标题及 issue 或 PR 的编号进行筛选,并支持分页,返回内容项、关联仓库、标签、指派人员、里程碑及看板字段值等详细信息。
访问令牌支持说明
- AtomGit 用户访问令牌(AtomGit user access tokens)
是否允许匿名访问
此接口允许匿名访问
请求参数
| 参数名 |
位置 |
类型 |
必填 |
说明 |
owner |
path |
string |
是 |
组织的路径 |
kanban_id |
path |
string |
是 |
看板 id |
repo |
query |
string |
否 |
仓库路径 |
source_type |
query |
string |
否 |
来源类型;枚举:issue / merge_request |
source_status |
query |
string |
否 |
来源状态;枚举:opened / closed / merged |
title |
query |
string |
否 |
标题 |
source_iids |
query |
string |
否 |
使用 PR 或 issue 的 iid 进行查询;使用该参数必须填写 repo 参数,否则不生效 |
page |
query |
string |
否 |
分页参数,第几页 |
per_page |
query |
string |
否 |
分页参数,每页数量 |
响应参数
| 字段 |
类型 |
必返 |
可为空 |
说明 |
id |
integer |
是 |
— |
看板内容项 id |
number |
integer |
是 |
— |
编号 |
title |
string |
是 |
— |
标题 |
source_type |
string |
是 |
— |
来源类型(issue / merge_request) |
status |
string |
是 |
— |
来源状态(opened / closed / merged) |
html_url |
string |
是 |
— |
HTML 地址 |
url |
string |
是 |
— |
API 地址 |
repo |
object |
是 |
— |
关联仓库信息 |
labels |
object[] |
是 |
— |
标签列表 |
assignees |
object[] |
是 |
— |
指派人员列表 |
milestone_resp |
object |
否 |
— |
里程碑信息 |
linked_pull_requests |
object[] |
否 |
— |
关联的拉取请求列表 |
values |
object[] |
是 |
— |
看板字段值列表 |
reviewers |
object[] |
否 |
— |
评审人员列表 |
Note: 响应体为 JSON 数组,上表描述的是数组元素(看板内容项)的字段。
repo 对象
| 字段 |
类型 |
必返 |
可为空 |
说明 |
repo.id |
integer |
是 |
— |
仓库 id |
repo.full_name |
string |
是 |
— |
仓库全名 |
repo.human_name |
string |
是 |
— |
仓库显示名称 |
repo.url |
string |
是 |
— |
仓库 API 地址 |
repo.name |
string |
是 |
— |
仓库名称 |
labels 对象(数组元素)
| 字段 |
类型 |
必返 |
可为空 |
说明 |
labels.id |
integer |
是 |
— |
标签 id |
labels.name |
string |
是 |
— |
标签名称 |
labels.color |
string |
是 |
— |
标签颜色 |
assignees 对象(数组元素)
| 字段 |
类型 |
必返 |
可为空 |
说明 |
assignees.id |
string |
是 |
— |
用户 id |
assignees.login |
string |
是 |
— |
登录名 |
assignees.name |
string |
是 |
— |
姓名 |
assignees.avatar_url |
string |
是 |
— |
头像地址 |
assignees.html_url |
string |
是 |
— |
用户主页地址 |
assignees.url |
string |
是 |
— |
用户 API 地址 |
milestone_resp 对象
| 字段 |
类型 |
必返 |
可为空 |
说明 |
milestone_resp.html_url |
string |
是 |
— |
里程碑 HTML 地址 |
milestone_resp.id |
integer |
是 |
— |
里程碑 id |
milestone_resp.title |
string |
是 |
— |
里程碑标题 |
milestone_resp.url |
string |
是 |
— |
里程碑 API 地址 |
linked_pull_requests 对象(数组元素)
| 字段 |
类型 |
必返 |
可为空 |
说明 |
linked_pull_requests.id |
integer |
否 |
— |
拉取请求 id |
linked_pull_requests.html_url |
string |
否 |
— |
拉取请求 HTML 地址 |
linked_pull_requests.number |
integer |
否 |
— |
编号 |
linked_pull_requests.state |
string |
否 |
— |
状态 |
linked_pull_requests.url |
string |
否 |
— |
拉取请求 API 地址 |
linked_pull_requests.repo |
object |
否 |
— |
关联仓库信息 |
linked_pull_requests.repo 对象
| 字段 |
类型 |
必返 |
可为空 |
说明 |
linked_pull_requests.repo.id |
integer |
是 |
— |
仓库 id |
linked_pull_requests.repo.full_name |
string |
是 |
— |
仓库全名 |
linked_pull_requests.repo.human_name |
string |
是 |
— |
仓库显示名称 |
linked_pull_requests.repo.url |
string |
是 |
— |
仓库 API 地址 |
linked_pull_requests.repo.name |
string |
是 |
— |
仓库名称 |
values 对象(数组元素)
| 字段 |
类型 |
必返 |
可为空 |
说明 |
values.field_name |
string |
是 |
— |
字段名称 |
values.field_type |
string |
是 |
— |
字段类型 |
values.value |
object |
是 |
— |
字段值 |
values.value 对象
| 字段 |
类型 |
必返 |
可为空 |
说明 |
values.value.color |
string |
是 |
— |
颜色 |
values.value.value |
string |
是 |
— |
字段值 |
values.value.position |
integer |
是 |
— |
排序位置 |
values.value.description |
string |
否 |
— |
描述 |
reviewers 对象(数组元素)
| 字段 |
类型 |
必返 |
可为空 |
说明 |
reviewers.id |
string |
否 |
— |
用户 id |
reviewers.login |
string |
否 |
— |
登录名 |
reviewers.name |
string |
否 |
— |
姓名 |
reviewers.avatar_url |
string |
否 |
— |
头像地址 |
reviewers.html_url |
string |
否 |
— |
用户主页地址 |
reviewers.url |
string |
否 |
— |
用户 API 地址 |
失败响应
只有成功响应是不够的:调用方需要知道失败长什么样才能编写错误处理。
400 参数错误
{
"error": "invalid_request",
"message": "参数 owner 不能为空",
"field": "owner"
}
401 未认证
{
"error": "unauthorized",
"message": "缺少或无效的访问令牌"
}
错误字段名以后端实际返回为准,无法确认时请勿臆造。
HTTP 响应状态码
| 状态码 |
说明 |
200 |
成功(OK) |
304 |
未修改(Not modified) |
401 |
需要认证(Requires authentication) |
403 |
禁止访问(Forbidden) |
请求示例
参数说明
<org> 替换为组织的路径(企业、组织或个人的地址 path);
<kanban_id> 替换为看板 id;
<repo> 替换为仓库路径(可选);
- 该接口允许匿名访问,也可携带 AtomGit 用户访问令牌(通过
access_token 参数)进行认证(可选)。
cURL
curl -X GET 'https://api.atomgit.com/api/v5/org/<org>/kanban/<kanban_id>/item_list?repo=<repo>&source_type=issue&source_status=opened&page=1&per_page=20' \
-H 'Accept: application/json'
JavaScript
const org = "<org>";
const kanbanId = "<kanban_id>";
const params = new URLSearchParams({
repo: "<repo>",
source_type: "issue",
source_status: "opened",
page: "1",
per_page: "20",
});
const response = await fetch(
`https://api.atomgit.com/api/v5/org/${encodeURIComponent(org)}/kanban/${encodeURIComponent(kanbanId)}/item_list?${params}`,
{
headers: {
"Accept": "application/json",
},
},
);
if (!response.ok) {
throw new Error(`请求失败: ${response.status}`);
}
const data = await response.json();
console.log(data);
Python
import requests
org = "<org>"
kanban_id = "<kanban_id>"
params = {
"repo": "<repo>",
"source_type": "issue",
"source_status": "opened",
"page": "1",
"per_page": "20",
}
resp = requests.get(
f"https://api.atomgit.com/api/v5/org/{org}/kanban/{kanban_id}/item_list",
params=params,
headers={"Accept": "application/json"},
timeout=10,
)
resp.raise_for_status()
print(resp.json())
响应示例
状态码: 200
[
{
"id": 101,
"number": 2,
"title": "实现看板内容列表查询接口",
"source_type": "issue",
"status": "opened",
"html_url": "https://api.atomgit.com/<org>/<repo>/issues/2",
"url": "https://api.atomgit.com/api/v5/org/<org>/kanban/<kanban_id>/item_list",
"repo": {
"id": 1,
"full_name": "<org>/<repo>",
"human_name": "示例仓库",
"url": "https://api.atomgit.com/api/v5/repos/<org>/<repo>",
"name": "<repo>"
},
"labels": [
{
"id": 1,
"name": "bug",
"color": "#d73a4a"
}
],
"assignees": [
{
"id": "12345",
"login": "octocat",
"name": "Octo Cat",
"avatar_url": "https://api.atomgit.com/avatars/octocat.png",
"html_url": "https://api.atomgit.com/octocat",
"url": "https://api.atomgit.com/api/v5/users/octocat"
}
],
"milestone_resp": {
"html_url": "https://api.atomgit.com/<org>/<repo>/milestone/3",
"id": 3,
"title": "v1.0",
"url": "https://api.atomgit.com/api/v5/repos/<org>/<repo>/milestones/3"
},
"linked_pull_requests": [
{
"id": 501,
"html_url": "https://api.atomgit.com/<org>/<repo>/pull/5",
"number": 5,
"state": "open",
"url": "https://api.atomgit.com/api/v5/repos/<org>/<repo>/pulls/5",
"repo": {
"id": 1,
"full_name": "<org>/<repo>",
"human_name": "示例仓库",
"url": "https://api.atomgit.com/api/v5/repos/<org>/<repo>",
"name": "<repo>"
}
}
],
"values": [
{
"field_name": "状态",
"field_type": "select",
"value": {
"color": "#36a2eb",
"value": "进行中",
"position": 1,
"description": "当前迭代进行中"
}
}
],
"reviewers": [
{
"id": "67890",
"login": "reviewer1",
"name": "Reviewer One",
"avatar_url": "https://api.atomgit.com/avatars/reviewer1.png",
"html_url": "https://api.atomgit.com/reviewer1",
"url": "https://api.atomgit.com/api/v5/users/reviewer1"
}
]
}
]
错误码
| 错误码 |
说明 |
401 |
未认证或凭证无效(缺少/无效的访问凭证) |
400 |
参数错误或请求无法解析 |
404 |
请求路径不存在 |
405 |
请求方法不支持 |
429 |
请求过于频繁,触发限流 |
500 |
系统内部错误 |