项目议题看板 API - GitLab - GitLab 文档中心

Tier: 基础版，专业版，旗舰版

Offering: JihuLab.com，私有化部署

使用此 API 管理议题看板。每次调用此 API 都需要进行身份验证。

如果用户不是私有项目的成员，对该项目执行 GET 请求会返回 404 状态码。

列出项目中的所有议题看板#

列出指定项目中的所有议题看板。

plaintext
GET /projects/:id/boards

属性	类型	是否必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/boards"

示例响应：

json
1[
2  {
3    "id" : 1,
4    "name": "board1",
5    "hide_backlog_list": false,
6    "hide_closed_list": false,
7    "project": {
8      "id": 5,
9      "name": "Diaspora Project Site",
10      "name_with_namespace": "Diaspora / Diaspora Project Site",
11      "path": "diaspora-project-site",
12      "path_with_namespace": "diaspora/diaspora-project-site",
13      "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
14      "web_url": "http://example.com/diaspora/diaspora-project-site"
15    },
16    "milestone":   {
17      "id": 12,
18      "title": "10.0"
19    },
20    "lists" : [
21      {
22        "id" : 1,
23        "label" : {
24          "name" : "Testing",
25          "color" : "#F0AD4E",
26          "description" : null
27        },
28        "position" : 1,
29        "max_issue_count": 0,
30        "max_issue_weight": 0,
31        "limit_metric": null
32      },
33      {
34        "id" : 2,
35        "label" : {
36          "name" : "Ready",
37          "color" : "#FF0000",
38          "description" : null
39        },
40        "position" : 2,
41        "max_issue_count": 0,
42        "max_issue_weight": 0,
43        "limit_metric":  null
44      },
45      {
46        "id" : 3,
47        "label" : {
48          "name" : "Production",
49          "color" : "#FF5F00",
50          "description" : null
51        },
52        "position" : 3,
53        "max_issue_count": 0,
54        "max_issue_weight": 0,
55        "limit_metric":  null
56      }
57    ]
58  }
59]

当项目中没有已激活或存在的看板时，另一个示例响应：

json
[]

检索一个议题看板#

检索项目中指定的议题看板。

plaintext
GET /projects/:id/boards/:board_id

属性	类型	是否必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
board_id	integer	是	看板的 ID。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/boards/1"

示例响应：

json
1  {
2    "id": 1,
3    "name": "project issue board",
4    "hide_backlog_list": false,
5    "hide_closed_list": false,
6    "project": {
7      "id": 5,
8      "name": "Diaspora Project Site",
9      "name_with_namespace": "Diaspora / Diaspora Project Site",
10      "path": "diaspora-project-site",
11      "path_with_namespace": "diaspora/diaspora-project-site",
12      "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
13      "web_url": "http://example.com/diaspora/diaspora-project-site"
14    },
15    "milestone":   {
16      "id": 12,
17      "title": "10.0"
18    },
19    "lists" : [
20      {
21        "id" : 1,
22        "label" : {
23          "name" : "Testing",
24          "color" : "#F0AD4E",
25          "description" : null
26        },
27        "position" : 1,
28        "max_issue_count": 0,
29        "max_issue_weight": 0,
30        "limit_metric":  null
31      },
32      {
33        "id" : 2,
34        "label" : {
35          "name" : "Ready",
36          "color" : "#FF0000",
37          "description" : null
38        },
39        "position" : 2,
40        "max_issue_count": 0,
41        "max_issue_weight": 0,
42        "limit_metric":  null
43      },
44      {
45        "id" : 3,
46        "label" : {
47          "name" : "Production",
48          "color" : "#FF5F00",
49          "description" : null
50        },
51        "position" : 3,
52        "max_issue_count": 0,
53        "max_issue_weight": 0,
54        "limit_metric":  null
55      }
56    ]
57  }

创建议题看板#

在指定项目中创建议题看板。

plaintext
POST /projects/:id/boards

属性	类型	是否必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
name	string	是	新看板的名称。

shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/boards" \
  --data "name=newboard"

示例响应：

json
1  {
2    "id": 1,
3    "name": "newboard",
4    "hide_backlog_list": false,
5    "hide_closed_list": false,
6    "project": {
7      "id": 5,
8      "name": "Diaspora Project Site",
9      "name_with_namespace": "Diaspora / Diaspora Project Site",
10      "path": "diaspora-project-site",
11      "path_with_namespace": "diaspora/diaspora-project-site",
12      "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
13      "web_url": "http://example.com/diaspora/diaspora-project-site"
14    },
15    "lists" : [],
16    "group": null,
17    "milestone": null,
18    "assignee" : null,
19    "labels" : [],
20    "weight" : null
21  }

更新议题看板#

更新项目中指定的议题看板。

plaintext
PUT /projects/:id/boards/:board_id

属性	类型	是否必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
board_id	integer	是	看板的 ID。
name	string	否	看板的新名称。
hide_backlog_list	boolean	否	隐藏 Open 列表。
hide_closed_list	boolean	否	隐藏 Closed 列表。
assignee_id	integer	否	看板应限定范围的指派人。仅专业版和旗舰版。
milestone_id	integer	否	看板应限定范围的里程碑。仅专业版和旗舰版。
labels	string	否	以逗号分隔的标签名称列表，看板应限定范围至这些标签。仅专业版和旗舰版。
weight	integer	否	权重范围，从 0 到 9，看板应限定范围至该权重。仅专业版和旗舰版。

shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/boards/1" \
  --data "name=new_name&milestone_id=43&assignee_id=1&labels=Doing&weight=4"

示例响应：

json
1  {
2    "id": 1,
3    "name": "new_name",
4    "hide_backlog_list": false,
5    "hide_closed_list": false,
6    "project": {
7      "id": 5,
8      "name": "Diaspora Project Site",
9      "name_with_namespace": "Diaspora / Diaspora Project Site",
10      "path": "diaspora-project-site",
11      "path_with_namespace": "diaspora/diaspora-project-site",
12      "created_at": "2018-07-03T05:48:49.982Z",
13      "default_branch": null,
14      "tag_list": [], //已废弃，请改用 `topics`
15      "topics": [],
16      "ssh_url_to_repo": "ssh://user@example.com/diaspora/diaspora-project-site.git",
17      "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
18      "web_url": "http://example.com/diaspora/diaspora-project-site",
19      "readme_url": null,
20      "avatar_url": null,
21      "star_count": 0,
22      "forks_count": 0,
23      "last_activity_at": "2018-07-03T05:48:49.982Z"
24    },
25    "lists": [],
26    "group": null,
27    "milestone": {
28      "id": 43,
29      "iid": 1,
30      "project_id": 15,
31      "title": "Milestone 1",
32      "description": "Milestone 1 desc",
33      "state": "active",
34      "created_at": "2018-07-03T06:36:42.618Z",
35      "updated_at": "2018-07-03T06:36:42.618Z",
36      "due_date": null,
37      "start_date": null,
38      "web_url": "http://example.com/root/board1/milestones/1"
39    },
40    "assignee": {
41      "id": 1,
42      "name": "Administrator",
43      "username": "root",
44      "state": "active",
45      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
46      "web_url": "http://example.com/root"
47    },
48    "labels": [{
49      "id": 10,
50      "name": "Doing",
51      "color": "#5CB85C",
52      "description": null
53    }],
54    "weight": 4
55  }

删除议题看板#

删除项目中指定的议题看板。

plaintext
DELETE /projects/:id/boards/:board_id

属性	类型	是否必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
board_id	integer	是	看板的 ID。

shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/boards/1"

列出议题看板中的所有列表#

列出指定议题看板中的所有列表。不包括 open 和 closed 列表。

plaintext
GET /projects/:id/boards/:board_id/lists

属性	类型	是否必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
board_id	integer	是	看板的 ID。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/boards/1/lists"

示例响应：

json
1[
2  {
3    "id" : 1,
4    "label" : {
5      "name" : "Testing",
6      "color" : "#F0AD4E",
7      "description" : null
8    },
9    "position" : 1,
10    "max_issue_count": 0,
11    "max_issue_weight": 0,
12    "limit_metric":  null
13  },
14  {
15    "id" : 2,
16    "label" : {
17      "name" : "Ready",
18      "color" : "#FF0000",
19      "description" : null
20    },
21    "position" : 2,
22    "max_issue_count": 0,
23    "max_issue_weight": 0,
24    "limit_metric":  null
25  },
26  {
27    "id" : 3,
28    "label" : {
29      "name" : "Production",
30      "color" : "#FF5F00",
31      "description" : null
32    },
33    "position" : 3,
34    "max_issue_count": 0,
35    "max_issue_weight": 0,
36    "limit_metric":  null
37  }
38]

检索一个看板列表#

从议题看板中检索指定的列表。

plaintext
GET /projects/:id/boards/:board_id/lists/:list_id

属性	类型	是否必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
board_id	integer	是	看板的 ID。
list_id	integer	是	看板列表的 ID。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/boards/1/lists/1"

示例响应：

json
1{
2  "id" : 1,
3  "label" : {
4    "name" : "Testing",
5    "color" : "#F0AD4E",
6    "description" : null
7  },
8  "position" : 1,
9  "max_issue_count": 0,
10  "max_issue_weight": 0,
11  "limit_metric":  null
12}

创建看板列表#

创建一个新的议题看板列表。

plaintext
POST /projects/:id/boards/:board_id/lists

属性	类型	是否必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
board_id	integer	是	看板的 ID。
label_id	integer	否	标签的 ID。
assignee_id	integer	否	用户的 ID。仅专业版和旗舰版。
milestone_id	integer	否	里程碑的 ID。仅专业版和旗舰版。
iteration_id	integer	否	迭代的 ID。仅专业版和旗舰版。

标签、指派人及里程碑参数互斥，即每个请求中仅能接受其中一项。请查阅议题看板文档以获取每种列表类型所需许可证的更多信息。

shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/boards/1/lists" \
  --data "label_id=5"

示例响应：

json
1{
2  "id" : 1,
3  "label" : {
4    "name" : "Testing",
5    "color" : "#F0AD4E",
6    "description" : null
7  },
8  "position" : 1,
9  "max_issue_count": 0,
10  "max_issue_weight": 0,
11  "limit_metric":  null
12}

更新看板列表#

更新议题看板中指定列表的位置。

plaintext
PUT /projects/:id/boards/:board_id/lists/:list_id

属性	类型	是否必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
board_id	integer	是	看板的 ID。
list_id	integer	是	看板列表的 ID。
position	integer	是	列表的位置。

shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/boards/1/lists/1" \
  --data "position=2"

示例响应：

json
1{
2  "id" : 1,
3  "label" : {
4    "name" : "Testing",
5    "color" : "#F0AD4E",
6    "description" : null
7  },
8  "position" : 1,
9  "max_issue_count": 0,
10  "max_issue_weight": 0,
11  "limit_metric":  null
12}

从看板中删除列表#

从议题看板中删除指定的列表。

前提条件：

满足以下任一条件：
- 拥有项目的计划者、报告者、Security Manager、开发者、维护者或所有者角色。
- 管理员权限。

plaintext
DELETE /projects/:id/boards/:board_id/lists/:list_id

属性	类型	是否必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
board_id	integer	是	看板的 ID。
list_id	integer	是	看板列表的 ID。

shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/boards/1/lists/1"