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