群组标记 API

Tier: 基础版, 专业版, 旗舰版
Offering: JihuLab.com, 私有化部署

此 API 支持管理群组标签。它允许用户列出、创建、更新和删除群组标签。此外，用户还可以订阅和取消订阅群组标签。

列出群组标签#

获取给定群组的所有标签。

plaintext
GET /groups/:id/labels

属性	类型	必需	描述
id	integer/string	是	群组的 ID 或URL 编码路径。
with_counts	boolean	否	是否包含议题和合并请求计数。默认为 false。
include_ancestor_groups	boolean	否	包含上级群组。默认为 true。
include_descendant_groups	boolean	否	包含下级群组。默认为 false。
only_group_labels	boolean	否	切换为仅包含群组标签或项目标签。默认为 true。
search	string	否	按关键字过滤标签。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels?with_counts=true"

示例响应：

json
1[
2  {
3    "id": 7,
4    "name": "bug",
5    "color": "#FF0000",
6    "text_color" : "#FFFFFF",
7    "description": null,
8    "description_html": null,
9    "open_issues_count": 0,
10    "closed_issues_count": 0,
11    "open_merge_requests_count": 0,
12    "subscribed": false
13  },
14  {
15    "id": 4,
16    "name": "feature",
17    "color": "#228B22",
18    "text_color" : "#FFFFFF",
19    "description": null,
20    "description_html": null,
21    "open_issues_count": 0,
22    "closed_issues_count": 0,
23    "open_merge_requests_count": 0,
24    "subscribed": false
25  }
26]

获取单个群组标签#

获取给定群组的单个标签。

plaintext
GET /groups/:id/labels/:label_id

属性	类型	必需	描述
id	integer or string	是	群组的 ID 或URL 编码路径。
label_id	integer or string	是	群组标签的 ID 或标题。
include_ancestor_groups	boolean	否	包含上级群组。默认为 true。
include_descendant_groups	boolean	否	包含下级群组。默认为 false。
only_group_labels	boolean	否	切换为仅包含群组标签或项目标签。默认为 true。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/bug"

示例响应：

json
1{
2  "id": 7,
3  "name": "bug",
4  "color": "#FF0000",
5  "text_color" : "#FFFFFF",
6  "description": null,
7  "description_html": null,
8  "open_issues_count": 0,
9  "closed_issues_count": 0,
10  "open_merge_requests_count": 0,
11  "subscribed": false
12}

创建新的群组标签#

为给定群组创建新的群组标签。

plaintext
POST /groups/:id/labels

属性	类型	必需	描述
id	integer/string	是	群组的 ID 或URL 编码路径
name	string	是	标签的名称
color	string	是	标签的颜色，以 6 位十六进制格式表示，并以 # 号开头（例如，#FFAABB），或CSS 颜色名称之一
description	string	否	标签的描述，

shell
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"

示例响应：

json
1{
2  "id": 9,
3  "name": "Feature Proposal",
4  "color": "#FFA500",
5  "text_color" : "#FFFFFF",
6  "description": "Describes new ideas",
7  "description_html": "Describes new ideas",
8  "open_issues_count": 0,
9  "closed_issues_count": 0,
10  "open_merge_requests_count": 0,
11  "subscribed": false
12}

更新群组标签#

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

plaintext
PUT /groups/:id/labels/:label_id

属性	类型	必需	描述
id	integer or string	是	群组的 ID 或URL 编码路径
label_id	integer or string	是	群组标签的 ID 或标题。
new_name	string	否	标签的新名称
color	string	否	标签的颜色，以 6 位十六进制格式表示，并以 # 号开头（例如，#FFAABB），或CSS 颜色名称之一
description	string	否	标签的描述。

shell
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"

示例响应：

json
1{
2  "id": 9,
3  "name": "Feature Idea",
4  "color": "#FFA500",
5  "text_color" : "#FFFFFF",
6  "description": "Describes new ideas",
7  "description_html": "Describes new ideas",
8  "open_issues_count": 0,
9  "closed_issues_count": 0,
10  "open_merge_requests_count": 0,
11  "subscribed": false
12}

旧的端点 `PUT /groups/:id/labels` 带有 `name` 参数仍然可用，但已弃用。

删除群组标签#

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

plaintext
DELETE /groups/:id/labels/:label_id

属性	类型	必需	描述
id	integer or string	是	群组的 ID 或URL 编码路径
label_id	integer or string	是	群组标签的 ID 或标题。

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/bug"

旧的端点 `DELETE /groups/:id/labels` 带有 `name` 参数仍然可用，但已弃用。

订阅经过身份验证的用户以接收群组标签的通知。如果用户已订阅该标签，则返回状态代码 304。

plaintext
POST /groups/:id/labels/:label_id/subscribe

属性	类型	必需	描述
id	integer or string	是	群组的 ID 或URL 编码路径
label_id	integer or string	是	群组标签的 ID 或标题。

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/9/subscribe"

示例响应：

json
1{
2  "id": 9,
3  "name": "Feature Idea",
4  "color": "#FFA500",
5  "text_color" : "#FFFFFF",
6  "description": "Describes new ideas",
7  "description_html": "Describes new ideas",
8  "open_issues_count": 0,
9  "closed_issues_count": 0,
10  "open_merge_requests_count": 0,
11  "subscribed": true
12}

取消订阅群组标签#

取消订阅经过身份验证的用户以不接收来自群组标签的通知。如果用户未订阅该标签，则返回状态代码 304。

plaintext
POST /groups/:id/labels/:label_id/unsubscribe

属性	类型	必需	描述
id	integer or string	是	群组的 ID 或URL 编码路径
label_id	integer or string	是	群组标签的 ID 或标题。

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/9/unsubscribe"

示例响应：

json
1{
2  "id": 9,
3  "name": "Feature Idea",
4  "color": "#FFA500",
5  "text_color" : "#FFFFFF",
6  "description": "Describes new ideas",
7  "description_html": "Describes new ideas",
8  "open_issues_count": 0,
9  "closed_issues_count": 0,
10  "open_merge_requests_count": 0,
11  "subscribed": false
12}