查询看板内容列表¶
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 参数错误
401 未认证
错误字段名以后端实际返回为准,无法确认时请勿臆造。
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 |
系统内部错误 |
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 gitcode-dev/atomgit-api-doc