极狐 GitLab Logo

史诗议题 API

  • Tier: 专业版，旗舰版
  • Offering: JihuLab.com，私有化部署
史诗 REST API 已在极狐GitLab 17.0 中被弃用，而且计划在 API v5 中移除。在极狐GitLab 17.4 及以后版本，如果[启用了新的史诗外观](../user/group/epics/epic_work_items.md)，请使用工作条目 API。更多详情，可以查看[如何迁移既有 API 的指南](graphql/epic_work_items_api_migration_guide.md)。此变更是一个破坏性变更。

每个对史诗议题 API 端点的 API 调用都必须经过认证。

如果用户不是群组的成员，并且群组是私有的，那么对该群组的 GET 请求会返回 404 状态码。

史诗仅在极狐GitLab 专业版和旗舰版 中可用。如果史诗功能不可用，则返回 403 状态码。

史诗议题分页#

API 结果是分页的。返回多个议题的请求默认每次返回 20 个结果。

列出史诗的议题#

获取分配给史诗的所有议题，并且经过认证的用户可以访问这些议题。

plaintext
GET /groups/:id/epics/:epic_iid/issues
属性类型必需描述
idinteger/string是群组的 ID 或 URL 编码路径
epic_iidinteger/string是史诗的内部 ID。
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5/issues/"

示例响应：

json
1[
2  {
3    "id": 76,
4    "iid": 6,
5    "project_id": 8,
6    "title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
7    "description" : "Ratione dolores corrupti mollitia soluta quia.",
8    "state": "opened",
9    "created_at": "2017-11-15T13:39:24.670Z",
10    "updated_at": "2018-01-04T10:49:19.506Z",
11    "closed_at": null,
12    "labels": [],
13    "milestone": {
14      "id": 38,
15      "iid": 3,
16      "project_id": 8,
17      "title": "v2.0",
18      "description": "In tempore culpa inventore quo accusantium.",
19      "state": "closed",
20      "created_at": "2017-11-15T13:39:13.825Z",
21      "updated_at": "2017-11-15T13:39:13.825Z",
22      "due_date": null,
23      "start_date": null
24    },
25    "assignees": [{
26      "id": 7,
27      "name": "Pamella Huel",
28      "username": "arnita",
29      "state": "active",
30      "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",
31      "web_url": "http://localhost:3001/arnita"
32    }],
33    "assignee": {
34      "id": 7,
35      "name": "Pamella Huel",
36      "username": "arnita",
37      "state": "active",
38      "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",
39      "web_url": "http://localhost:3001/arnita"
40    },
41    "author": {
42      "id": 13,
43      "name": "Michell Johns",
44      "username": "chris_hahn",
45      "state": "active",
46      "avatar_url": "http://www.gravatar.com/avatar/30e3b2122ccd6b8e45e8e14a3ffb58fc?s=80&d=identicon",
47      "web_url": "http://localhost:3001/chris_hahn"
48    },
49    "user_notes_count": 8,
50    "upvotes": 0,
51    "downvotes": 0,
52    "due_date": null,
53    "confidential": false,
54    "weight": null,
55    "discussion_locked": null,
56    "web_url": "http://localhost:3001/h5bp/html5-boilerplate/issues/6",
57    "time_stats": {
58      "time_estimate": 0,
59      "total_time_spent": 0,
60      "human_time_estimate": null,
61      "human_total_time_spent": null
62    },
63    "_links":{
64      "self": "http://localhost:3001/api/v4/projects/8/issues/6",
65      "notes": "http://localhost:3001/api/v4/projects/8/issues/6/notes",
66      "award_emoji": "http://localhost:3001/api/v4/projects/8/issues/6/award_emoji",
67      "project": "http://localhost:3001/api/v4/projects/8"
68    },
69    "epic_issue_id": 2
70  }
71]

NOTE: assignee 列已弃用，现在我们将其显示为单一尺寸数组 assignees 以符合极狐GitLab API。

将议题分配给史诗#

创建史诗 - 议题关联。如果相关议题属于另一个史诗，则从该史诗解除分配。

plaintext
POST /groups/:id/epics/:epic_iid/issues/:issue_id
属性类型必需描述
idinteger/string是群组的 ID 或 URL 编码路径
epic_iidinteger/string是史诗的内部 ID。
issue_idinteger/string是议题的 ID。
shell
curl --header POST "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5/issues/55"

示例响应：

json
1{
2  "id": 11,
3  "epic": {
4    "id": 30,
5    "iid": 5,
6    "title": "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.",
7    "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
8    "author": {
9      "id": 7,
10      "name": "Pamella Huel",
11      "username": "arnita",
12      "state": "active",
13      "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",
14      "web_url": "http://localhost:3001/arnita"
15    },
16    "start_date": null,
17    "end_date": null
18  },
19  "issue": {
20    "id": 55,
21    "iid": 13,
22    "project_id": 8,
23    "title": "Beatae laborum voluptatem voluptate eligendi ex accusamus.",
24    "description": "Quam veritatis debitis omnis aliquam sit.",
25    "state": "opened",
26    "created_at": "2017-11-05T13:59:12.782Z",
27    "updated_at": "2018-01-05T10:33:03.900Z",
28    "closed_at": null,
29    "labels": [],
30    "milestone": {
31      "id": 48,
32      "iid": 6,
33      "project_id": 8,
34      "title": "Sprint - Sed sed maxime temporibus ipsa ullam qui sit.",
35      "description": "Quos veritatis qui expedita sunt deleniti accusamus.",
36      "state": "active",
37      "created_at": "2017-11-05T13:59:12.445Z",
38      "updated_at": "2017-11-05T13:59:12.445Z",
39      "due_date": "2017-11-13",
40      "start_date": "2017-11-05"
41    },
42    "assignees": [{
43      "id": 10,
44      "name": "Lu Mayer",
45      "username": "kam",
46      "state": "active",
47      "avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
48      "web_url": "http://localhost:3001/kam"
49    }],
50    "assignee": {
51      "id": 10,
52      "name": "Lu Mayer",
53      "username": "kam",
54      "state": "active",
55      "avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
56      "web_url": "http://localhost:3001/kam"
57    },
58    "author": {
59      "id": 25,
60      "name": "User 3",
61      "username": "user3",
62      "state": "active",
63      "avatar_url": "http://www.gravatar.com/avatar/97d6d9441ff85fdc730e02a6068d267b?s=80&d=identicon",
64      "web_url": "http://localhost:3001/user3"
65    },
66    "user_notes_count": 0,
67    "upvotes": 0,
68    "downvotes": 0,
69    "due_date": null,
70    "confidential": false,
71    "weight": null,
72    "discussion_locked": null,
73    "web_url": "http://localhost:3001/h5bp/html5-boilerplate/issues/13",
74    "time_stats": {
75      "time_estimate": 0,
76      "total_time_spent": 0,
77      "human_time_estimate": null,
78      "human_total_time_spent": null
79    }
80  }
81}

NOTE: assignee 列已弃用，现在我们将其显示为单一尺寸数组 assignees 以符合极狐GitLab API。

从史诗中移除议题#

移除史诗 - 议题关联。

plaintext
DELETE /groups/:id/epics/:epic_iid/issues/:epic_issue_id
属性类型必需描述
idinteger/string是群组的 ID 或 URL 编码路径
epic_iidinteger/string是史诗的内部 ID。
epic_issue_idinteger/string是议题 - 史诗关联的 ID。
shell
curl --header DELETE "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5/issues/11"

示例响应：

json
1{
2  "id": 11,
3  "epic": {
4    "id": 30,
5    "iid": 5,
6    "title": "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.",
7    "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
8    "author": {
9      "id": 7,
10      "name": "Pamella Huel",
11      "username": "arnita",
12      "state": "active",
13      "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",
14      "web_url": "http://localhost:3001/arnita"
15    },
16    "start_date": null,
17    "end_date": null
18  },
19  "issue": {
20    "id": 223,
21    "iid": 13,
22    "project_id": 8,
23    "title": "Beatae laborum voluptatem voluptate eligendi ex accusamus.",
24    "description": "Quam veritatis debitis omnis aliquam sit.",
25    "state": "opened",
26    "created_at": "2017-11-05T13:59:12.782Z",
27    "updated_at": "2018-01-05T10:33:03.900Z",
28    "closed_at": null,
29    "labels": [],
30    "milestone": {
31      "id": 48,
32      "iid": 6,
33      "project_id": 8,
34      "title": "Sprint - Sed sed maxime temporibus ipsa ullam qui sit.",
35      "description": "Quos veritatis qui expedita sunt deleniti accusamus.",
36      "state": "active",
37      "created_at": "2017-11-05T13:59:12.445Z",
38      "updated_at": "2017-11-05T13:59:12.445Z",
39      "due_date": "2017-11-13",
40      "start_date": "2017-11-05"
41    },
42    "assignees": [{
43      "id": 10,
44      "name": "Lu Mayer",
45      "username": "kam",
46      "state": "active",
47      "avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
48      "web_url": "http://localhost:3001/kam"
49    }],
50    "assignee": {
51      "id": 10,
52      "name": "Lu Mayer",
53      "username": "kam",
54      "state": "active",
55      "avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
56      "web_url": "http://localhost:3001/kam"
57    },
58    "author": {
59      "id": 25,
60      "name": "User 3",
61      "username": "user3",
62      "state": "active",
63      "avatar_url": "http://www.gravatar.com/avatar/97d6d9441ff85fdc730e02a6068d267b?s=80&d=identicon",
64      "web_url": "http://localhost:3001/user3"
65    },
66    "user_notes_count": 0,
67    "upvotes": 0,
68    "downvotes": 0,
69    "due_date": null,
70    "confidential": false,
71    "weight": null,
72    "discussion_locked": null,
73    "web_url": "http://localhost:3001/h5bp/html5-boilerplate/issues/13",
74    "time_stats": {
75      "time_estimate": 0,
76      "total_time_spent": 0,
77      "human_time_estimate": null,
78      "human_total_time_spent": null
79    }
80  }
81}

NOTE: assignee 列已弃用，现在我们将其显示为单一尺寸数组 assignees 以符合极狐GitLab API。

更新史诗 - 议题关联#

更新史诗 - 议题关联。

plaintext
PUT /groups/:id/epics/:epic_iid/issues/:epic_issue_id
属性类型必需描述
idinteger/string是群组的 ID 或 URL 编码路径
epic_iidinteger/string是史诗的内部 ID。
epic_issue_idinteger/string是议题 - 史诗关联的 ID。
move_before_idinteger/string否应放置在问题链接之前的议题 - 史诗关联 ID。
move_after_idinteger/string否应放置在问题链接之后的议题 - 史诗关联 ID。
shell
curl --header PUT "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5/issues/11?move_before_id=20"

示例响应：

json
1[
2  {
3    "id": 30,
4    "iid": 6,
5    "project_id": 8,
6    "title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
7    "description" : "Ratione dolores corrupti mollitia soluta quia.",
8    "state": "opened",
9    "created_at": "2017-11-15T13:39:24.670Z",
10    "updated_at": "2018-01-04T10:49:19.506Z",
11    "closed_at": null,
12    "labels": [],
13    "milestone": {
14      "id": 38,
15      "iid": 3,
16      "project_id": 8,
17      "title": "v2.0",
18      "description": "In tempore culpa inventore quo accusantium.",
19      "state": "closed",
20      "created_at": "2017-11-15T13:39:13.825Z",
21      "updated_at": "2017-11-15T13:39:13.825Z",
22      "due_date": null,
23      "start_date": null
24    },
25    "assignees": [{
26      "id": 7,
27      "name": "Pamella Huel",
28      "username": "arnita",
29      "state": "active",
30      "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",
31      "web_url": "http://localhost:3001/arnita"
32    }],
33    "assignee": {
34      "id": 7,
35      "name": "Pamella Huel",
36      "username": "arnita",
37      "state": "active",
38      "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",
39      "web_url": "http://localhost:3001/arnita"
40    },
41    "author": {
42      "id": 13,
43      "name": "Michell Johns",
44      "username": "chris_hahn",
45      "state": "active",
46      "avatar_url": "http://www.gravatar.com/avatar/30e3b2122ccd6b8e45e8e14a3ffb58fc?s=80&d=identicon",
47      "web_url": "http://localhost:3001/chris_hahn"
48    },
49    "user_notes_count": 8,
50    "upvotes": 0,
51    "downvotes": 0,
52    "due_date": null,
53    "confidential": false,
54    "weight": null,
55    "discussion_locked": null,
56    "web_url": "http://localhost:3001/h5bp/html5-boilerplate/issues/6",
57    "time_stats": {
58      "time_estimate": 0,
59      "total_time_spent": 0,
60      "human_time_estimate": null,
61      "human_total_time_spent": null
62    },
63    "_links":{
64      "self": "http://localhost:3001/api/v4/projects/8/issues/6",
65      "notes": "http://localhost:3001/api/v4/projects/8/issues/6/notes",
66      "award_emoji": "http://localhost:3001/api/v4/projects/8/issues/6/award_emoji",
67      "project": "http://localhost:3001/api/v4/projects/8"
68    },
69    "subscribed": true,
70    "epic_issue_id": 11,
71    "relative_position": 55
72  }
73]