Epics API
Epics API
版本历史
- 在GitLab Ultimate 10.2 中引入.
- 单级史诗在 12.8 GitLab Premium .
对史诗的每个 API 调用都必须经过身份验证.
如果用户不是组的成员,并且该组是私有的,则对该组的请求将导致404
状态代码.
如果没有史诗功能,将返回403
状态代码.
使您可以与史诗相关的问题进行交互.
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
Epics pagination
阅读有关分页的更多信息.
弃用:不建议使用响应中的reference
属性,而推荐使用references
. >推出了注意: > references.relative
相对于正在请求史诗的组. 从史诗组的原始组中提取史诗时, relative
格式将与short
格式相同,而在请求的交叉组中, relative
格式应与full
格式相同.
获取请求的组及其子组的所有史诗.
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"
响应示例:
New epic
创建一个新的史诗.
POST /groups/:id/epics
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 }
更新史诗.
注意:从 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 开始) |
响应示例:
{ "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
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5"
Create a todo
在史诗上为当前用户手动创建待办事项. 如果该史诗上已经存在用户的待办事项,则返回状态码304
.
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | 认证用户拥有的 ID 或URL 编码路径 |
integer | yes | 群组史诗的内部 ID |
响应示例:
{ "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" }