311.md

# Epics API

> 原文：[https://docs.gitlab.com/ee/api/epics.html](https://docs.gitlab.com/ee/api/epics.html)

*   [Epic issues API](#epic-issues-api)
*   [Milestone dates integration](#milestone-dates-integration)
*   [Epics pagination](#epics-pagination)
*   [List epics for a group](#list-epics-for-a-group)
*   [Single epic](#single-epic)
*   [New epic](#new-epic)
*   [Update epic](#update-epic)
*   [Delete epic](#delete-epic)
*   [Create a todo](#create-a-todo)

# Epics API[](#epics-api-premium "Permalink")

版本历史

*   在[GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2 中引入.
*   单级史诗在 12.8 [中移至](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) [GitLab Premium](https://about.gitlab.com/pricing/) .

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

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

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

## Epic issues API[](#epic-issues-api "Permalink")

[史诗问题 API](epic_issues.html)使您可以与[史诗相关的问题](epic_issues.html)进行交互.

## Milestone dates integration[](#milestone-dates-integration "Permalink")

在 GitLab 11.3 中[引入](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6448) .

由于可以从相关的发行里程碑动态地获取开始日期和截止日期，因此当用户具有编辑权限时，将显示其他字段. 其中包括两个布尔字段`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[](#epics-pagination "Permalink")

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

阅读有关[分页的](README.html#pagination)更多信息.

**弃用：不建议使用**响应中的`reference`属性，而推荐使用`references` . >推出了[GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354)**注意：** > `references.relative`相对于正在请求史诗的组. 从史诗组的原始组中提取史诗时， `relative`格式将与`short`格式相同，而在请求的交叉组中， `relative`格式应与`full`格式相同.

## List epics for a group[](#list-epics-for-a-group "Permalink")

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

```
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](README.html#namespaced-path-encoding) 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 中](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413)引入 |
| `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 中](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31479)引入 |

```
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[](#single-epic "Permalink")

取得史诗

```
GET /groups/:id/epics/:epic_iid 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `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[](#new-epic "Permalink")

创建一个新的史诗.

**注意：**从 GitLab [11.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6448)开始，不应再直接分配`start_date`和`end_date` ，因为它们现在表示复合值. 您可以改为通过`*_is_fixed`和`*_fixed`字段进行配置.

```
POST /groups/:id/epics 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `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[](#update-epic "Permalink")

更新史诗.

**注意：**从 GitLab [11.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6448)开始，不应再直接分配`start_date`和`end_date` ，因为它们现在表示复合值. 您可以改为通过`*_is_fixed`和`*_fixed`字段进行配置.

```
PUT /groups/:id/epics/:epic_iid 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `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-epic "Permalink")

删除史诗

```
DELETE /groups/:id/epics/:epic_iid 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `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[](#create-a-todo "Permalink")

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

```
POST /groups/:id/epics/:epic_iid/todo 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `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"  } 
```