极狐 GitLab Logo

史诗 API（已弃用）

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

每次对史诗的 API 调用都必须经过认证。

如果用户不是私有群组的成员，对该群组的 GET 请求将导致 404 状态码。

如果史诗功能不可用，将返回 403 状态码。

史诗议题 API#

史诗议题 API 允许您与与史诗相关的议题进行交互。

里程碑日期集成#

由于开始日期和截止日期可以动态地从相关议题的里程碑中获取，当用户具有编辑权限时，将显示其他字段。这些包括两个布尔字段 start_date_is_fixed 和 due_date_is_fixed，以及四个日期字段 start_date_fixed、start_date_from_inherited_source、due_date_fixed 和 due_date_from_inherited_source。

  • end_date 已被弃用，建议使用 due_date。
  • start_date_from_milestones 已被弃用，建议使用 start_date_from_inherited_source。
  • due_date_from_milestones 已被弃用，建议使用 due_date_from_inherited_source。

史诗分页#

默认情况下，GET 请求一次返回 20 个结果，因为 API 结果是分页的。

阅读更多关于 分页 的内容。

在极狐GitLab 12.6 及更高版本中，响应中的 `reference` 属性已被弃用，建议使用 `references`。
`references.relative` 是相对于请求史诗的群组。当从其原始群组获取史诗时，`relative` 格式与 `short` 格式相同。当跨群组请求史诗时，`relative` 格式预计与 `full` 格式相同。

列出群组的史诗#

获取请求群组及其子群组的所有史诗。

plaintext
GET /groups/:id/epics
GET /groups/:id/epics?author_id=5
GET /groups/:id/epics?labels=bug,reproduced
GET /groups/:id/epics?state=opened
属性类型必需描述
idinteger/string是群组的 ID 或 URL 编码路径
author_idinteger否返回由给定用户 id 创建的史诗
author_usernamestring否返回由给定 username 创建的用户的史诗
labelsstring否返回与用逗号分隔的标签名称匹配的史诗。可以使用史诗群组或父群组的标签名称
with_labels_detailsboolean否如果 true，响应在标签字段中返回每个标签的更多详细信息：:name、:color、:description、:description_html、:text_color。默认值为 false。
order_bystring否返回按 created_at、updated_at 或 title 字段排序的史诗。默认值为 created_at
sortstring否返回以 asc 或 desc 顺序排序的史诗。默认值为 desc
searchstring否根据史诗的 title 和 description 搜索史诗
statestring否根据史诗的 state 搜索史诗，可能的过滤器：opened、closed 和 all，默认值：all
created_afterdatetime否返回在给定时间或之后创建的史诗。期望为 ISO 8601 格式（2019-03-15T08:00:00Z）
created_beforedatetime否返回在给定时间或之前创建的史诗。期望为 ISO 8601 格式（2019-03-15T08:00:00Z）
updated_afterdatetime否返回在给定时间或之后更新的史诗。期望为 ISO 8601 格式（2019-03-15T08:00:00Z）
updated_beforedatetime否返回在给定时间或之前更新的史诗。期望为 ISO 8601 格式（2019-03-15T08:00:00Z）
include_ancestor_groupsboolean否包含来自请求群组祖先的史诗。默认值为 false
include_descendant_groupsboolean否包含来自请求群组后代的史诗。默认值为 true
my_reaction_emojistring否返回由认证用户通过给定表情符号做出反应的史诗。None 返回未给予反应的史诗。Any 返回给予至少一个反应的史诗。
notHash否返回不匹配提供参数的史诗。接受：author_id、author_username 和 labels。
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics"

示例响应：

json
1[
2  {
3  "id": 29,
4  "iid": 4,
5  "group_id": 7,
6  "parent_id": 23,
7  "parent_iid": 3,
8  "title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",
9  "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
10  "state": "opened",
11  "confidential": "false",
12  "web_url": "http://gitlab.example.com/groups/test/-/epics/4",
13  "reference": "&4",
14  "references": {
15    "short": "&4",
16    "relative": "&4",
17    "full": "test&4"
18  },
19  "author": {
20    "id": 10,
21    "name": "Lu Mayer",
22    "username": "kam",
23    "state": "active",
24    "avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
25    "web_url": "http://gitlab.example.com/kam"
26  },
27  "start_date": null,
28  "start_date_is_fixed": false,
29  "start_date_fixed": null,
30  "start_date_from_milestones": null,       //deprecated in favor of start_date_from_inherited_source
31  "start_date_from_inherited_source": null,
32  "end_date": "2018-07-31",                 //deprecated in favor of due_date
33  "due_date": "2018-07-31",
34  "due_date_is_fixed": false,
35  "due_date_fixed": null,
36  "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
37  "due_date_from_inherited_source": "2018-07-31",
38  "created_at": "2018-07-17T13:36:22.770Z",
39  "updated_at": "2018-07-18T12:22:05.239Z",
40  "closed_at": "2018-08-18T12:22:05.239Z",
41  "labels": [],
42  "upvotes": 4,
43  "downvotes": 0,
44  "color": "#1068bf",
45  "_links":{
46      "self": "http://gitlab.example.com/api/v4/groups/7/epics/4",
47      "epic_issues": "http://gitlab.example.com/api/v4/groups/7/epics/4/issues",
48      "group":"http://gitlab.example.com/api/v4/groups/7",
49      "parent":"http://gitlab.example.com/api/v4/groups/7/epics/3"
50  }
51  },
52  {
53  "id": 50,
54  "iid": 35,
55  "group_id": 17,
56  "parent_id": 19,
57  "parent_iid": 1,
58  "title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",
59  "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
60  "state": "opened",
61  "web_url": "http://gitlab.example.com/groups/test/sample/-/epics/35",
62  "reference": "&4",
63  "references": {
64    "short": "&4",
65    "relative": "sample&4",
66    "full": "test/sample&4"
67  },
68  "author": {
69    "id": 10,
70    "name": "Lu Mayer",
71    "username": "kam",
72    "state": "active",
73    "avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
74    "web_url": "http://gitlab.example.com/kam"
75  },
76  "start_date": null,
77  "start_date_is_fixed": false,
78  "start_date_fixed": null,
79  "start_date_from_milestones": null,       //deprecated in favor of start_date_from_inherited_source
80  "start_date_from_inherited_source": null,
81  "end_date": "2018-07-31",                 //deprecated in favor of due_date
82  "due_date": "2018-07-31",
83  "due_date_is_fixed": false,
84  "due_date_fixed": null,
85  "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
86  "due_date_from_inherited_source": "2018-07-31",
87  "created_at": "2018-07-17T13:36:22.770Z",
88  "updated_at": "2018-07-18T12:22:05.239Z",
89  "closed_at": "2018-08-18T12:22:05.239Z",
90  "imported": false,
91  "imported_from": "none",
92  "labels": [],
93  "upvotes": 4,
94  "downvotes": 0,
95  "color": "#1068bf",
96  "_links":{
97      "self": "http://gitlab.example.com/api/v4/groups/17/epics/35",
98      "epic_issues": "http://gitlab.example.com/api/v4/groups/17/epics/35/issues",
99      "group":"http://gitlab.example.com/api/v4/groups/17",
100      "parent":"http://gitlab.example.com/api/v4/groups/17/epics/1"
101  }
102  }
103]

单个史诗#

获取单个史诗

plaintext
GET /groups/:id/epics/:epic_iid
属性类型必需描述
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"

示例响应：

json
1{
2  "id": 30,
3  "iid": 5,
4  "group_id": 7,
5  "parent_id": null,
6  "parent_iid": null,
7  "title": "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.",
8  "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
9  "state": "opened",
10  "imported": false,
11  "imported_from": "none",
12  "web_url": "http://gitlab.example.com/groups/test/-/epics/5",
13  "reference": "&5",
14  "references": {
15    "short": "&5",
16    "relative": "&5",
17    "full": "test&5"
18  },
19  "author":{
20    "id": 7,
21    "name": "Pamella Huel",
22    "username": "arnita",
23    "state": "active",
24    "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",
25    "web_url": "http://gitlab.example.com/arnita"
26  },
27  "start_date": null,
28  "start_date_is_fixed": false,
29  "start_date_fixed": null,
30  "start_date_from_milestones": null,       //deprecated in favor of start_date_from_inherited_source
31  "start_date_from_inherited_source": null,
32  "end_date": "2018-07-31",                 //deprecated in favor of due_date
33  "due_date": "2018-07-31",
34  "due_date_is_fixed": false,
35  "due_date_fixed": null,
36  "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
37  "due_date_from_inherited_source": "2018-07-31",
38  "created_at": "2018-07-17T13:36:22.770Z",
39  "updated_at": "2018-07-18T12:22:05.239Z",
40  "closed_at": "2018-08-18T12:22:05.239Z",
41  "labels": [],
42  "upvotes": 4,
43  "downvotes": 0,
44  "color": "#1068bf",
45  "subscribed": true,
46  "_links":{
47      "self": "http://gitlab.example.com/api/v4/groups/7/epics/5",
48      "epic_issues": "http://gitlab.example.com/api/v4/groups/7/epics/5/issues",
49      "group":"http://gitlab.example.com/api/v4/groups/7",
50      "parent": null
51  }
52}

新建史诗#

创建一个新史诗。

从极狐GitLab 11.3 开始，`start_date` 和 `end_date` 不再应直接分配，因为它们现在表示复合值。您可以通过 `*_is_fixed` 和 `*_fixed` 字段进行配置。
plaintext
POST /groups/:id/epics
属性类型必需描述
idinteger/string是群组的 ID 或 URL 编码路径
titlestring是史诗的标题
labelsstring否用逗号分隔的标签列表
descriptionstring否史诗的描述。限制为 1,048,576 个字符。
colorstring否史诗的颜色。位于名为 epic_highlight_color 的功能标志后面（默认禁用）
confidentialboolean否史诗是否应为保密
created_atstring否史诗创建时间。日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z 。需要管理员或项目/群组所有者权限
start_date_is_fixedboolean否开始日期是否应从 start_date_fixed 或里程碑中获取
start_date_fixedstring否史诗的固定开始日期
due_date_is_fixedboolean否截止日期是否应从 due_date_fixed 或里程碑中获取
due_date_fixedstring否史诗的固定截止日期
parent_idinteger/string否父史诗的 ID
shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics?title=Epic&description=Epic%20description&parent_id=29"

示例响应：

json
1{
2  "id": 33,
3  "iid": 6,
4  "group_id": 7,
5  "parent_id": 29,
6  "parent_iid": 4,
7  "title": "Epic",
8  "description": "Epic description",
9  "state": "opened",
10  "imported": false,
11  "imported_from": "none",
12  "confidential": "false",
13  "web_url": "http://gitlab.example.com/groups/test/-/epics/6",
14  "reference": "&6",
15  "references": {
16    "short": "&6",
17    "relative": "&6",
18    "full": "test&6"
19  },
20  "author": {
21    "name" : "Alexandra Bashirian",
22    "avatar_url" : null,
23    "state" : "active",
24    "web_url" : "https://gitlab.example.com/eileen.lowe",
25    "id" : 18,
26    "username" : "eileen.lowe"
27  },
28  "start_date": null,
29  "start_date_is_fixed": false,
30  "start_date_fixed": null,
31  "start_date_from_milestones": null,       //deprecated in favor of start_date_from_inherited_source
32  "start_date_from_inherited_source": null,
33  "end_date": "2018-07-31",                 //deprecated in favor of due_date
34  "due_date": "2018-07-31",
35  "due_date_is_fixed": false,
36  "due_date_fixed": null,
37  "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
38  "due_date_from_inherited_source": "2018-07-31",
39  "created_at": "2018-07-17T13:36:22.770Z",
40  "updated_at": "2018-07-18T12:22:05.239Z",
41  "closed_at": "2018-08-18T12:22:05.239Z",
42  "labels": [],
43  "upvotes": 4,
44  "downvotes": 0,
45  "color": "#1068bf",
46  "_links":{
47    "self": "http://gitlab.example.com/api/v4/groups/7/epics/6",
48    "epic_issues": "http://gitlab.example.com/api/v4/groups/7/epics/6/issues",
49    "group":"http://gitlab.example.com/api/v4/groups/7",
50    "parent": "http://gitlab.example.com/api/v4/groups/7/epics/4"
51  }
52}

更新史诗#

更新史诗。

plaintext
PUT /groups/:id/epics/:epic_iid
属性类型必需描述
idinteger/string是群组的 ID 或 URL 编码路径
epic_iidinteger/string是史诗的内部 ID
add_labelsstring否要添加到议题的用逗号分隔的标签名称。
confidentialboolean否史诗是否应为保密
descriptionstring否史诗的描述。限制为 1,048,576 个字符。
due_date_fixedstring否史诗的固定截止日期
due_date_is_fixedboolean否截止日期是否应从 due_date_fixed 或里程碑中获取
labelsstring否议题的用逗号分隔的标签名称。设置为空字符串以取消分配所有标签。
parent_idinteger/string否父史诗的 ID。
remove_labelsstring否要从议题中删除的用逗号分隔的标签名称。
start_date_fixedstring否史诗的固定开始日期
start_date_is_fixedboolean否开始日期是否应从 start_date_fixed 或里程碑中获取
state_eventstring否史诗的状态事件。设置 close 以关闭史诗，设置 reopen 以重新打开它
titlestring否史诗的标题
updated_atstring否史诗更新的时间。日期时间字符串，ISO 8601 格式，例如 2016-03-11T03:45:40Z 。需要管理员或项目/群组所有者权限
colorstring否史诗的颜色。位于名为 epic_highlight_color 的功能标志后面（默认禁用）
shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5?title=New%20Title&parent_id=29"

示例响应：

json
1{
2  "id": 33,
3  "iid": 6,
4  "group_id": 7,
5  "parent_id": 29,
6  "parent_iid": 4,
7  "title": "New Title",
8  "description": "Epic description",
9  "state": "opened",
10  "imported": false,
11  "imported_from": "none",
12  "confidential": "false",
13  "web_url": "http://gitlab.example.com/groups/test/-/epics/6",
14  "reference": "&6",
15  "references": {
16    "short": "&6",
17    "relative": "&6",
18    "full": "test&6"
19  },
20  "author": {
21    "name" : "Alexandra Bashirian",
22    "avatar_url" : null,
23    "state" : "active",
24    "web_url" : "https://gitlab.example.com/eileen.lowe",
25    "id" : 18,
26    "username" : "eileen.lowe"
27  },
28  "start_date": null,
29  "start_date_is_fixed": false,
30  "start_date_fixed": null,
31  "start_date_from_milestones": null,       //deprecated in favor of start_date_from_inherited_source
32  "start_date_from_inherited_source": null,
33  "end_date": "2018-07-31",                 //deprecated in favor of due_date
34  "due_date": "2018-07-31",
35  "due_date_is_fixed": false,
36  "due_date_fixed": null,
37  "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
38  "due_date_from_inherited_source": "2018-07-31",
39  "created_at": "2018-07-17T13:36:22.770Z",
40  "updated_at": "2018-07-18T12:22:05.239Z",
41  "closed_at": "2018-08-18T12:22:05.239Z",
42  "labels": [],
43  "upvotes": 4,
44  "downvotes": 0,
45  "color": "#1068bf"
46}

删除史诗#

History
    • 在极狐GitLab 16.11 中发生变更。在 16.11 及更早版本中，如果你删除了史诗，其所有子史诗和它们的子代也会被删除。如果需要，你可以在你将其删除之前从父史诗删除子史诗。

删除一个史诗

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

创建待办事项#

手动为当前用户在史诗上创建待办事项。如果用户在该史诗上已经存在待办事项，则返回状态码 304。

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

示例响应：

json
1{
2  "id": 112,
3  "group": {
4    "id": 1,
5    "name": "Gitlab",
6    "path": "gitlab",
7    "kind": "group",
8    "full_path": "base/gitlab",
9    "parent_id": null
10  },
11  "author": {
12    "name": "Administrator",
13    "username": "root",
14    "id": 1,
15    "state": "active",
16    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
17    "web_url": "https://gitlab.example.com/root"
18  },
19  "action_name": "marked",
20  "target_type": "epic",
21  "target": {
22    "id": 30,
23    "iid": 5,
24    "group_id": 1,
25    "title": "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.",
26    "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
27    "author":{
28      "id": 7,
29      "name": "Pamella Huel",
30      "username": "arnita",
31      "state": "active",
32      "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",
33      "web_url": "http://gitlab.example.com/arnita"
34    },
35    "web_url": "http://gitlab.example.com/groups/test/-/epics/5",
36    "reference": "&5",
37    "references": {
38      "short": "&5",
39      "relative": "&5",
40      "full": "test&5"
41    },
42    "start_date": null,
43    "end_date": null,
44    "created_at": "2018-01-21T06:21:13.165Z",
45    "updated_at": "2018-01-22T12:41:41.166Z",
46    "closed_at": "2018-08-18T12:22:05.239Z"
47  },
48  "target_url": "https://gitlab.example.com/groups/epics/5",
49  "body": "Vel voluptas atque dicta mollitia adipisci qui at.",
50  "state": "pending",
51  "created_at": "2016-07-01T11:09:13.992Z"
52}