Epics API
- Epic issues API
- Milestone dates integration
- Epics pagination
- List epics for a group
- Single epic
- New epic
- Update epic
- Delete epic
- Create a todo
Epics API
版本历史
- 在GitLab Ultimate 10.2 中引入.
- 单级史诗在 12.8 中移至 GitLab Premium .
对史诗的每个 API 调用都必须经过身份验证.
如果用户不是组的成员,并且该组是私有的,则对该组的GET
请求将导致404
状态代码.
如果没有史诗功能,将返回403
状态代码.
Epic issues API
Milestone dates integration
在 GitLab 11.3 中引入 .
由于可以从相关的发行里程碑动态地获取开始日期和截止日期,因此当用户具有编辑权限时,将显示其他字段. 其中包括两个布尔字段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
Epics pagination
默认情况下,因为 API 结果是分页的,所以GET
请求一次返回 20 个结果.
阅读有关分页的更多信息.
弃用:不建议使用响应中的reference
属性,而推荐使用references
. >推出了GitLab 12.6注意: > references.relative
相对于正在请求史诗的组. 从史诗组的原始组中提取史诗时, relative
格式将与short
格式相同,而在请求的交叉组中, relative
格式应与full
格式相同.
List epics for a group
获取请求的组及其子组的所有史诗.
GET /groups/:id/epics
GET /groups/:id/epics?author_id=5
GET /groups/:id/epics?labels=bug,reproduced
GET /groups/:id/epics?state=opened
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the group owned by the authenticated user |
author_id |
integer | no | 返回由给定用户id 创建的史诗 |
labels |
string | no | 返回与以逗号分隔的标签名称列表匹配的史诗. 可以使用史诗组或父组的标签名称 |
with_labels_details |
boolean | no | 如果为true ,则响应将为标签字段中的每个标签返回更多详细信息:name , :color , :description , :description_html , :text_color . 默认值为false . 在GitLab 12.7 中引入 |
order_by |
string | no | 返回按created_at 或updated_at 字段排序的史诗. 默认为created_at |
sort |
string | no | 返回按asc 或desc 排列的史诗. 默认为desc |
search |
string | no | 根据title 和description 搜索史诗 |
state |
string | no | 根据state 搜索史诗,可能的过滤条件: opened , closed 和all ,默认值: all |
created_after |
datetime | no | 返回在给定时间或之后创建的史诗 |
created_before |
datetime | no | 返回在给定时间或之前创建的史诗 |
updated_after |
datetime | no | 返回在给定时间或之后更新的史诗 |
updated_before |
datetime | no | 返回在给定时间或之前更新的史诗 |
include_ancestor_groups |
boolean | no | 包括请求组祖先的史诗. 默认为false |
include_descendant_groups |
boolean | no | 包括请求组后代的史诗. 默认为true |
my_reaction_emoji |
string | no | 返回给定表情符号由已认证用户做出反应的史诗. None 返回没有反应的史诗. 给定至少一个反应, Any 回报史诗. 在GitLab 13.0 中引入 |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics"
响应示例:
[ { "id": 29, "iid": 4, "group_id": 7, "parent_id": 23, "title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.", "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.", "state": "opened", "confidential": "false", "web_url": "http://localhost:3001/groups/test/-/epics/4", "reference": "&4", "references": { "short": "&4", "relative": "&4", "full": "test&4" }, "author": { "id": 10, "name": "Lu Mayer", "username": "kam", "state": "active", "avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon", "web_url": "http://localhost:3001/kam" }, "start_date": null, "start_date_is_fixed": false, "start_date_fixed": null, "start_date_from_milestones": null, //deprecated in favor of start_date_from_inherited_source "start_date_from_inherited_source": null, "end_date": "2018-07-31", //deprecated in favor of due_date "due_date": "2018-07-31", "due_date_is_fixed": false, "due_date_fixed": null, "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source "due_date_from_inherited_source": "2018-07-31", "created_at": "2018-07-17T13:36:22.770Z", "updated_at": "2018-07-18T12:22:05.239Z", "closed_at": "2018-08-18T12:22:05.239Z", "labels": [], "upvotes": 4, "downvotes": 0 }, { "id": 50, "iid": 35, "group_id": 17, "parent_id": 19, "title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.", "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.", "state": "opened", "web_url": "http://localhost:3001/groups/test/sample/-/epics/4", "reference": "&4", "references": { "short": "&4", "relative": "sample&4", "full": "test/sample&4" }, "author": { "id": 10, "name": "Lu Mayer", "username": "kam", "state": "active", "avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon", "web_url": "http://localhost:3001/kam" }, "start_date": null, "start_date_is_fixed": false, "start_date_fixed": null, "start_date_from_milestones": null, //deprecated in favor of start_date_from_inherited_source "start_date_from_inherited_source": null, "end_date": "2018-07-31", //deprecated in favor of due_date "due_date": "2018-07-31", "due_date_is_fixed": false, "due_date_fixed": null, "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source "due_date_from_inherited_source": "2018-07-31", "created_at": "2018-07-17T13:36:22.770Z", "updated_at": "2018-07-18T12:22:05.239Z", "closed_at": "2018-08-18T12:22:05.239Z", "labels": [], "upvotes": 4, "downvotes": 0 } ]
Single epic
取得史诗
GET /groups/:id/epics/:epic_iid
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | 认证用户拥有的组的 ID 或URL 编码路径 |
epic_iid |
integer/string | yes | 史诗的内部 ID. |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5"
响应示例:
{ "id": 30, "iid": 5, "group_id": 7, "title": "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.", "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.", "state": "opened", "web_url": "http://localhost:3001/groups/test/-/epics/5", "reference": "&5", "references": { "short": "&5", "relative": "&5", "full": "test&5" }, "author":{ "id": 7, "name": "Pamella Huel", "username": "arnita", "state": "active", "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon", "web_url": "http://localhost:3001/arnita" }, "start_date": null, "start_date_is_fixed": false, "start_date_fixed": null, "start_date_from_milestones": null, //deprecated in favor of start_date_from_inherited_source "start_date_from_inherited_source": null, "end_date": "2018-07-31", //deprecated in favor of due_date "due_date": "2018-07-31", "due_date_is_fixed": false, "due_date_fixed": null, "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source "due_date_from_inherited_source": "2018-07-31", "created_at": "2018-07-17T13:36:22.770Z", "updated_at": "2018-07-18T12:22:05.239Z", "closed_at": "2018-08-18T12:22:05.239Z", "labels": [], "upvotes": 4, "downvotes": 0, "subscribed": true }
New epic
创建一个新的史诗.
注意:从 GitLab 11.3开始,不应再直接分配start_date
和end_date
,因为它们现在表示复合值. 您可以改为通过*_is_fixed
和*_fixed
字段进行配置.
POST /groups/:id/epics
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | 认证用户拥有的组的 ID 或URL 编码路径 |
title |
string | yes | 史诗的标题 |
labels |
string | no | 以逗号分隔的标签列表 |
description |
string | no | 史诗般的描述. 限制为 1,048,576 个字符. |
confidential |
boolean | no | 史诗是否应该保密. 如果禁用confidential_epics 功能标志,将被忽略. |
start_date_is_fixed |
boolean | no | 开始日期是从start_date_fixed 还是从里程碑(自 11.3 开始) |
start_date_fixed |
string | no | 史诗的固定开始日期(自 11.3 开始) |
due_date_is_fixed |
boolean | no | 是否应从due_date_fixed 或里程碑(从 11.3 开始)中due_date_fixed 到期日期 |
due_date_fixed |
string | no | 史诗的固定到期日(自 11.3 开始) |
parent_id |
integer/string | no | 父级史诗的 ID(自 11.11 起) |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics?title=Epic&description=Epic%20description"
响应示例:
{ "id": 33, "iid": 6, "group_id": 7, "title": "Epic", "description": "Epic description", "state": "opened", "confidential": "false", "web_url": "http://localhost:3001/groups/test/-/epics/6", "reference": "&6", "references": { "short": "&6", "relative": "&6", "full": "test&6" }, "author": { "name" : "Alexandra Bashirian", "avatar_url" : null, "state" : "active", "web_url" : "https://gitlab.example.com/eileen.lowe", "id" : 18, "username" : "eileen.lowe" }, "start_date": null, "start_date_is_fixed": false, "start_date_fixed": null, "start_date_from_milestones": null, //deprecated in favor of start_date_from_inherited_source "start_date_from_inherited_source": null, "end_date": "2018-07-31", //deprecated in favor of due_date "due_date": "2018-07-31", "due_date_is_fixed": false, "due_date_fixed": null, "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source "due_date_from_inherited_source": "2018-07-31", "created_at": "2018-07-17T13:36:22.770Z", "updated_at": "2018-07-18T12:22:05.239Z", "closed_at": "2018-08-18T12:22:05.239Z", "labels": [], "upvotes": 4, "downvotes": 0 }
Update epic
更新史诗.
注意:从 GitLab 11.3开始,不应再直接分配start_date
和end_date
,因为它们现在表示复合值. 您可以改为通过*_is_fixed
和*_fixed
字段进行配置.
PUT /groups/:id/epics/:epic_iid
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | 认证用户拥有的组的 ID 或URL 编码路径 |
epic_iid |
integer/string | yes | 史诗的内部 ID |
title |
string | no | 史诗的标题 |
description |
string | no | 史诗的描述. 限制为 1,048,576 个字符. |
confidential |
boolean | no | 史诗是否应该保密. 如果禁用confidential_epics 功能标志,将被忽略. |
labels |
string | no | 以逗号分隔的标签列表 |
start_date_is_fixed |
boolean | no | 开始日期是从start_date_fixed 还是从里程碑(自 11.3 开始) |
start_date_fixed |
string | no | 史诗的固定开始日期(自 11.3 开始) |
due_date_is_fixed |
boolean | no | 是否应从due_date_fixed 或里程碑(从 11.3 开始)中due_date_fixed 到期日期 |
due_date_fixed |
string | no | 史诗的固定到期日(自 11.3 开始) |
state_event |
string | no | 史诗般的状态事件. 设置为close 以关闭史诗,然后reopen 以重新打开(自 11.4 开始) |
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5?title=New%20Title"
响应示例:
{ "id": 33, "iid": 6, "group_id": 7, "title": "New Title", "description": "Epic description", "state": "opened", "confidential": "false", "web_url": "http://localhost:3001/groups/test/-/epics/6", "reference": "&6", "references": { "short": "&6", "relative": "&6", "full": "test&6" }, "author": { "name" : "Alexandra Bashirian", "avatar_url" : null, "state" : "active", "web_url" : "https://gitlab.example.com/eileen.lowe", "id" : 18, "username" : "eileen.lowe" }, "start_date": null, "start_date_is_fixed": false, "start_date_fixed": null, "start_date_from_milestones": null, //deprecated in favor of start_date_from_inherited_source "start_date_from_inherited_source": null, "end_date": "2018-07-31", //deprecated in favor of due_date "due_date": "2018-07-31", "due_date_is_fixed": false, "due_date_fixed": null, "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source "due_date_from_inherited_source": "2018-07-31", "created_at": "2018-07-17T13:36:22.770Z", "updated_at": "2018-07-18T12:22:05.239Z", "closed_at": "2018-08-18T12:22:05.239Z", "labels": [], "upvotes": 4, "downvotes": 0 }
Delete epic
删除史诗
DELETE /groups/:id/epics/:epic_iid
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | 认证用户拥有的组的 ID 或URL 编码路径 |
epic_iid |
integer/string | yes | 史诗的内部 ID. |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5"
Create a todo
在史诗上为当前用户手动创建待办事项. 如果该史诗上已经存在用户的待办事项,则返回状态码304
.
POST /groups/:id/epics/:epic_iid/todo
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | 认证用户拥有的组的 ID 或URL 编码路径 |
epic_iid |
integer | yes | 群组史诗的内部 ID |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5/todo"
响应示例:
{ "id": 112, "group": { "id": 1, "name": "Gitlab", "path": "gitlab", "kind": "group", "full_path": "base/gitlab", "parent_id": null }, "author": { "name": "Administrator", "username": "root", "id": 1, "state": "active", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", "web_url": "https://gitlab.example.com/root" }, "action_name": "marked", "target_type": "epic", "target": { "id": 30, "iid": 5, "group_id": 1, "title": "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.", "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.", "author":{ "id": 7, "name": "Pamella Huel", "username": "arnita", "state": "active", "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon", "web_url": "http://localhost:3001/arnita" }, "web_url": "http://localhost:3001/groups/test/-/epics/5", "reference": "&5", "references": { "short": "&5", "relative": "&5", "full": "test&5" }, "start_date": null, "end_date": null, "created_at": "2018-01-21T06:21:13.165Z", "updated_at": "2018-01-22T12:41:41.166Z", "closed_at": "2018-08-18T12:22:05.239Z" }, "target_url": "https://gitlab.example.com/groups/epics/5", "body": "Vel voluptas atque dicta mollitia adipisci qui at.", "state": "pending", "created_at": "2016-07-01T11:09:13.992Z" }