# Group Labels API

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

*   [List group labels](#list-group-labels)
*   [Get a single group label](#get-a-single-group-label)
*   [Create a new group label](#create-a-new-group-label)
*   [Update a group label](#update-a-group-label)
*   [Delete a group label](#delete-a-group-label)
*   [Subscribe to a group label](#subscribe-to-a-group-label)
*   [Unsubscribe from a group label](#unsubscribe-from-a-group-label)

# Group Labels API[](#group-labels-api "Permalink")

在 GitLab 11.8 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21368) .

该 API 支持[组标签的](../user/project/labels.html#project-labels-and-group-labels)管理. 它允许列出，创建，更新和删除组标签. 此外，用户可以订阅和取消订阅组标签.

**注意：** `description_html`已添加到[GitLab 12.7 中的](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413)响应 JSON.

## List group labels[](#list-group-labels "Permalink")

获取给定组的所有标签.

```
GET /groups/: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/groups/5/labels?with_counts=true" 
```

响应示例：

```
[  {  "id":  7,  "name":  "bug",  "color":  "#FF0000",  "text_color"  :  "#FFFFFF",  "description":  null,  "description_html":  null,  "open_issues_count":  0,  "closed_issues_count":  0,  "open_merge_requests_count":  0,  "subscribed":  false  },  {  "id":  4,  "name":  "feature",  "color":  "#228B22",  "text_color"  :  "#FFFFFF",  "description":  null,  "description_html":  null,  "open_issues_count":  0,  "closed_issues_count":  0,  "open_merge_requests_count":  0,  "subscribed":  false  }  ] 
```

## Get a single group label[](#get-a-single-group-label "Permalink")

获取给定组的单个标签.

```
GET /groups/: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/groups/5/labels/bug" 
```

Example response:

```
{  "id":  7,  "name":  "bug",  "color":  "#FF0000",  "text_color"  :  "#FFFFFF",  "description":  null,  "description_html":  null,  "open_issues_count":  0,  "closed_issues_count":  0,  "open_merge_requests_count":  0,  "subscribed":  false  } 
```

## Create a new group label[](#create-a-new-group-label "Permalink")

为给定的组创建一个新的组标签.

```
POST /groups/: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 | 标签的说明， |

```
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"name": "Feature Proposal", "color": "#FFA500", "description": "Describes new ideas" }' "https://gitlab.example.com/api/v4/groups/5/labels" 
```

响应示例：

```
{  "id":  9,  "name":  "Feature Proposal",  "color":  "#FFA500",  "text_color"  :  "#FFFFFF",  "description":  "Describes new ideas",  "description_html":  "Describes new ideas",  "open_issues_count":  0,  "closed_issues_count":  0,  "open_merge_requests_count":  0,  "subscribed":  false  } 
```

## Update a group label[](#update-a-group-label "Permalink")

更新现有的组标签. 至少需要一个参数来更新组标签.

```
PUT /groups/: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 | no | 标签的新名称 |
| `color` | string | no | 标签的颜色以 6 位十六进制表示法加上前导"＃"符号（例如#FFAABB）或[CSS 颜色名称之一给出](https://s0developer0mozilla0org.icopy.site/en-US/docs/Web/CSS/color_value) |
| `description` | string | no | 标签的描述. |

```
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"new_name": "Feature Idea" }' "https://gitlab.example.com/api/v4/groups/5/labels/Feature%20Proposal" 
```

响应示例：

```
{  "id":  9,  "name":  "Feature Idea",  "color":  "#FFA500",  "text_color"  :  "#FFFFFF",  "description":  "Describes new ideas",  "description_html":  "Describes new ideas",  "open_issues_count":  0,  "closed_issues_count":  0,  "open_merge_requests_count":  0,  "subscribed":  false  } 
```

**注意：**参数中带有`name`的较早的端点`PUT /groups/:id/labels`仍然可用，但已弃用.

## Delete a group label[](#delete-a-group-label "Permalink")

删除具有给定名称的组标签.

```
DELETE /groups/: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/groups/5/labels/bug" 
```

**注意：**参数中带有`name`的较旧的端点`DELETE /groups/:id/labels`仍然可用，但已弃用.

## Subscribe to a group label[](#subscribe-to-a-group-label "Permalink")

将经过身份验证的用户订阅到组标签以接收通知. 如果用户已经订阅了标签，则返回状态码`304` .

```
POST /groups/: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/groups/5/labels/9/subscribe" 
```

响应示例：

```
{  "id":  9,  "name":  "Feature Idea",  "color":  "#FFA500",  "text_color"  :  "#FFFFFF",  "description":  "Describes new ideas",  "description_html":  "Describes new ideas",  "open_issues_count":  0,  "closed_issues_count":  0,  "open_merge_requests_count":  0,  "subscribed":  true  } 
```

## Unsubscribe from a group label[](#unsubscribe-from-a-group-label "Permalink")

从组标签退订已认证的用户以不接收来自该组标签的通知. 如果用户未订阅标签，则返回状态码`304` .

```
POST /groups/: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/groups/5/labels/9/unsubscribe" 
```

响应示例：

```
{  "id":  9,  "name":  "Feature Idea",  "color":  "#FFA500",  "text_color"  :  "#FFFFFF",  "description":  "Describes new ideas",  "description_html":  "Describes new ideas",  "open_issues_count":  0,  "closed_issues_count":  0,  "open_merge_requests_count":  0,  "subscribed":  false  } 
```