企业🤖AI Agent构建引擎，智能编排和调试，一键部署，支持私有化部署方案 广告
# 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" } ```