Epics API

原文：https://docs.gitlab.com/ee/api/epics.html

Epics API

版本历史

对史诗的每个 API 调用都必须经过身份验证.

如果用户不是组的成员，并且该组是私有的，则对该组的GET请求将导致404状态代码.

如果没有史诗功能，将返回403状态代码.

Epic issues API

史诗问题 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

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

  1. GET /groups/:id/epics
  2. GET /groups/:id/epics?author_id=5
  3. GET /groups/:id/epics?labels=bug,reproduced
  4. 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 中引入 
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics"

响应示例：

  1. [  {  "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

取得史诗

  1. GET /groups/:id/epics/:epic_iid
Attribute Type Required Description
id integer/string yes 认证用户拥有的组的 ID 或URL 编码路径
epic_iid integer/string yes 史诗的内部 ID. 
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5"

响应示例：

  1. {  "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字段进行配置.

  1. 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 起） 
  1. curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics?title=Epic&description=Epic%20description"

响应示例：

  1. {  "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字段进行配置.

  1. 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 开始） 
  1. curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5?title=New%20Title"

响应示例：

  1. {  "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

删除史诗

  1. DELETE /groups/:id/epics/:epic_iid
Attribute Type Required Description
id integer/string yes 认证用户拥有的组的 ID 或URL 编码路径
epic_iid integer/string yes 史诗的内部 ID. 
  1. curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5"

Create a todo

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

  1. POST /groups/:id/epics/:epic_iid/todo
Attribute Type Required Description
id integer/string yes 认证用户拥有的组的 ID 或URL 编码路径
epic_iid integer yes 群组史诗的内部 ID 
  1. curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5/todo"

响应示例：

  1. {  "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"  }