Help us learn about your current experience with the documentation. Take the survey.

组标签 API

  • 层级：免费、专业、旗舰
  • 产品：GitLab.com、GitLab 自托管、GitLab 专属

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

列出组标签

获取指定组的所有标签。

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 否 用于过滤标签的关键词。 
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 /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。 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/bug"

示例响应：

{
  "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
}

创建新的组标签

为指定组创建新的组标签。

POST /groups/:id/labels
属性 类型 必需 描述
id integer/string 是 组的 ID 或URL 编码路径
name string 是 标签的名称
color string 是 标签的颜色，以 6 位十六进制表示法给出，带有前导 ‘#’ 符号（例如，#FFAABB）或CSS 颜色名称之一
description string 否 标签的描述 
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
}

更新组标签

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

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 否 标签的描述。 
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
}

一个较旧的端点 PUT /groups/:id/labels（参数中包含 name）仍然可用，但已弃用。

删除组标签

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

DELETE /groups/:id/labels/:label_id
属性 类型 必需 描述
id integer or string 是 组的 ID 或URL 编码路径
label_id integer or string 是 组标签的 ID 或标题。 
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。

POST /groups/:id/labels/:label_id/subscribe
属性 类型 必需 描述
id integer or string 是 组的 ID 或URL 编码路径
label_id integer or string 是 组标签的 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
}

取消订阅组标签

将已认证的用户从组标签中取消订阅，以不再接收来自它的通知。如果用户未订阅该标签，则返回状态码 304。

POST /groups/:id/labels/:label_id/unsubscribe
属性 类型 必需 描述
id integer or string 是 组的 ID 或URL 编码路径
label_id integer or string 是 组标签的 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
}