Labels API · Gitlab 中文文檔

# Labels API > 原文：[https://docs.gitlab.com/ee/api/labels.html](https://docs.gitlab.com/ee/api/labels.html) * [List labels](#list-labels) * [Get a single project label](#get-a-single-project-label) * [Create a new label](#create-a-new-label) * [Delete a label](#delete-a-label) * [Edit an existing label](#edit-an-existing-label) * [Promote a project label to a group label](#promote-a-project-label-to-a-group-label) * [Subscribe to a label](#subscribe-to-a-label) * [Unsubscribe from a label](#unsubscribe-from-a-label) # Labels API[](#labels-api "Permalink") **注意：** `description_html`已添加到[GitLab 12.7 中的](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413)響應 JSON. ## List labels[](#list-labels "Permalink") 獲取給定項目的所有標簽. 默認情況下，此請求一次返回 20 個結果，因為 API 結果[是分頁的](README.html#pagination) . ``` GET /projects/:id/labels ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer/string | yes | 經過身份驗證的用戶擁有[的項目](README.html#namespaced-path-encoding)的 ID 或[URL 編碼路徑](README.html#namespaced-path-encoding) | | `with_counts` | boolean | no | 是否包括發布和合并請求計數. 默認為`false` . *（ [在 GitLab 12.2 中引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543) ）* | | `include_ancestor_groups` | boolean | no | 包括祖先組. 默認為`true` . | ``` curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels?with_counts=true" ``` 響應示例： ``` [ { "id" : 1, "name" : "bug", "color" : "#d9534f", "text_color" : "#FFFFFF", "description": "Bug reported by user", "description_html": "Bug reported by user", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 1, "subscribed": false, "priority": 10, "is_project_label": true }, { "id" : 4, "color" : "#d9534f", "text_color" : "#FFFFFF", "name" : "confirmed", "description": "Confirmed issue", "description_html": "Confirmed issue", "open_issues_count": 2, "closed_issues_count": 5, "open_merge_requests_count": 0, "subscribed": false, "priority": null, "is_project_label": true }, { "id" : 7, "name" : "critical", "color" : "#d9534f", "text_color" : "#FFFFFF", "description": "Critical issue. Need fix ASAP", "description_html": "Critical issue. Need fix ASAP", "open_issues_count": 1, "closed_issues_count": 3, "open_merge_requests_count": 1, "subscribed": false, "priority": null, "is_project_label": true }, { "id" : 8, "name" : "documentation", "color" : "#f0ad4e", "text_color" : "#FFFFFF", "description": "Issue about documentation", "description_html": "Issue about documentation", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 2, "subscribed": false, "priority": null, "is_project_label": false }, { "id" : 9, "color" : "#5cb85c", "text_color" : "#FFFFFF", "name" : "enhancement", "description": "Enhancement proposal", "description_html": "Enhancement proposal", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 1, "subscribed": true, "priority": null, "is_project_label": true } ] ``` ## Get a single project label[](#get-a-single-project-label "Permalink") 獲取給定項目的單個標簽. ``` GET /projects/:id/labels/:label_id ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer/string | yes | 經過身份驗證的用戶擁有[的項目](README.html#namespaced-path-encoding)的 ID 或[URL 編碼路徑](README.html#namespaced-path-encoding) | | `label_id` | 整數或字符串 | yes | 項目標簽的 ID 或標題. | | `include_ancestor_groups` | boolean | no | 包括祖先組. 默認為`true` . | ``` curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/bug" ``` 響應示例： ``` { "id" : 1, "name" : "bug", "color" : "#d9534f", "text_color" : "#FFFFFF", "description": "Bug reported by user", "description_html": "Bug reported by user", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 1, "subscribed": false, "priority": 10, "is_project_label": true } ``` ## Create a new label[](#create-a-new-label "Permalink") 使用給定的名稱和顏色為給定的存儲庫創建一個新標簽. ``` POST /projects/:id/labels ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer/string | yes | 經過身份驗證的用戶擁有[的項目](README.html#namespaced-path-encoding)的 ID 或[URL 編碼路徑](README.html#namespaced-path-encoding) | | `name` | string | yes | 標簽名稱 | | `color` | string | yes | 標簽的顏色以 6 位十六進制表示法加上前導"＃"符號（例如#FFAABB）或[CSS 顏色名稱之一給出](https://s0developer0mozilla0org.icopy.site/en-US/docs/Web/CSS/color_value) | | `description` | string | no | 標簽說明 | | `priority` | integer | no | 標簽的優先級. 必須大于或等于零或為`null`才能刪除優先級. | ``` curl --data "name=feature&color=#5843AD" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels" ``` 響應示例： ``` { "id" : 10, "name" : "feature", "color" : "#5843AD", "text_color" : "#FFFFFF", "description":null, "description_html":null, "open_issues_count": 0, "closed_issues_count": 0, "open_merge_requests_count": 0, "subscribed": false, "priority": null, "is_project_label": true } ``` ## Delete a label[](#delete-a-label "Permalink") 刪除具有給定名稱的標簽. ``` DELETE /projects/:id/labels/:label_id ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer/string | yes | 經過身份驗證的用戶擁有[的項目](README.html#namespaced-path-encoding)的 ID 或[URL 編碼路徑](README.html#namespaced-path-encoding) | | `label_id` | 整數或字符串 | yes | 群組標簽的 ID 或標題. | ``` curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/bug" ``` **注意：**參數中帶有`name`的較舊的端點`DELETE /projects/:id/labels`仍然可用，但已棄用. ## Edit an existing label[](#edit-an-existing-label "Permalink") 用新名稱或新顏色更新現有標簽. 至少需要一個參數來更新標簽. ``` PUT /projects/:id/labels/:label_id ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer/string | yes | 經過身份驗證的用戶擁有[的項目](README.html#namespaced-path-encoding)的 ID 或[URL 編碼路徑](README.html#namespaced-path-encoding) | | `label_id` | 整數或字符串 | yes | 群組標簽的 ID 或標題. | | `new_name` | string | 是，如果未提供`color` | 標簽的新名稱 | | `color` | string | 是，如果未提供`new_name` | 標簽的顏色以 6 位十六進制表示法加上前導"＃"符號（例如#FFAABB）或[CSS 顏色名稱之一給出](https://s0developer0mozilla0org.icopy.site/en-US/docs/Web/CSS/color_value) | | `description` | string | no | 標簽的新說明 | | `priority` | integer | no | 標簽的新優先級. 必須大于或等于零或為`null`才能刪除優先級. | ``` curl --request PUT --data "new_name=docs&color=#8E44AD&description=Documentation" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/documentation" ``` 響應示例： ``` { "id" : 8, "name" : "docs", "color" : "#8E44AD", "text_color" : "#FFFFFF", "description": "Documentation", "description_html": "Documentation", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 2, "subscribed": false, "priority": null, "is_project_label": true } ``` **注意：**參數中帶有`name`或`label_id`的較早的端點`PUT /projects/:id/labels`仍然可用，但已棄用. ## Promote a project label to a group label[](#promote-a-project-label-to-a-group-label "Permalink") 在 GitLab 12.3 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25218) . 將項目標簽提升為組標簽. ``` PUT /projects/:id/labels/:label_id/promote ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer/string | yes | 經過身份驗證的用戶擁有[的項目](README.html#namespaced-path-encoding)的 ID 或[URL 編碼路徑](README.html#namespaced-path-encoding) | | `label_id` | 整數或字符串 | yes | 群組標簽的 ID 或標題. | ``` curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/documentation/promote" ``` 響應示例： ``` { "id" : 8, "name" : "documentation", "color" : "#8E44AD", "description": "Documentation", "description_html": "Documentation", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 2, "subscribed": false } ``` **注意：**在參數中帶有`name`的較早的端點`PUT /projects/:id/labels/promote`仍然可用，但已棄用. ## Subscribe to a label[](#subscribe-to-a-label "Permalink") 將經過身份驗證的用戶訂閱標簽以接收通知. 如果用戶已經訂閱了標簽，則返回狀態碼`304` . ``` POST /projects/:id/labels/:label_id/subscribe ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer/string | yes | 經過身份驗證的用戶擁有[的項目](README.html#namespaced-path-encoding)的 ID 或[URL 編碼路徑](README.html#namespaced-path-encoding) | | `label_id` | 整數或字符串 | yes | 項目標簽的 ID 或標題 | ``` curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/labels/1/subscribe" ``` 響應示例： ``` { "id" : 1, "name" : "bug", "color" : "#d9534f", "text_color" : "#FFFFFF", "description": "Bug reported by user", "description_html": "Bug reported by user", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 1, "subscribed": true, "priority": null, "is_project_label": true } ``` ## Unsubscribe from a label[](#unsubscribe-from-a-label "Permalink") Unsubscribes the authenticated user from a label to not receive notifications from it. If the user is not subscribed to the label, the status code `304` is returned. ``` POST /projects/:id/labels/:label_id/unsubscribe ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer/string | yes | 經過身份驗證的用戶擁有[的項目](README.html#namespaced-path-encoding)的 ID 或[URL 編碼路徑](README.html#namespaced-path-encoding) | | `label_id` | 整數或字符串 | yes | 項目標簽的 ID 或標題 | ``` curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/labels/1/unsubscribe" ```