Epics API · Gitlab 中文文檔

# 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" } ```