グループラベルAPI

GitLab 11.8 で導入されました

このAPIはグループラベルの管理をサポートします。ユーザーはグループラベルの一覧、作成、更新、削除ができます。さらに、ユーザーはグループラベルを購読したり、購読を解除したりすることができます。

note
GitLab 12.7 でレスポンス JSON にdescription_html - が追加されました。

グループラベルの一覧

指定されたグループのすべてのラベルを取得します。

GET /groups/:id/labels
属性種類必須説明
id整数/文字列yes認証されたユーザーが所有するグループのID またはURL エンコードされたパス
with_countsbooleanいいえイシューやマージリクエストの数を含めるかどうか。デフォルトはfalse(GitLab 12.2 で導入)
include_ancestor_groupsbooleanいいえ祖先グループを含めます。デフォルトはtrueです。
include_descendant_groupsbooleanいいえ子孫グループを含めます。デフォルトはfalse。 GitLab 13.6 で導入
only_group_labelsbooleanいいえグループラベルのみを含めるかプロジェクトラベルも含めるかを切り替えます。デフォルトはtrue。 GitLab 13.6 で導入
search文字列です。いいえラベルをフィルタリングするキーワード。GitLab 13.6 で導入
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整数または文字列。yes認証されたユーザーが所有するグループのID またはURL エンコードされたパス
label_id整数または文字列。yesグループのラベルのIDまたはタイトル。
include_ancestor_groupsbooleanいいえ祖先グループを含めます。デフォルトはtrueです。
include_descendant_groupsbooleanいいえ子孫グループを含めます。デフォルトはfalse。 GitLab 13.6 で導入
only_group_labelsbooleanいいえグループラベルのみを含めるかプロジェクトラベルも含めるかを切り替えます。デフォルトはtrue。 GitLab 13.6 で導入
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整数/文字列yes認証ユーザーが所有するグループのIDまたはURLエンコードされたパス
name文字列です。yesラベルの名前
color文字列です。yesラベルの色を、先頭の’#’記号付きの6桁の16進数表記(例えば#FFAABB)またはCSSカラー名のいずれかで指定します。
description文字列です。いいえラベルの説明、
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
}

グループラベルの更新

既存のグループラベルを更新します。グループラベルを更新するには、少なくとも1つのパラメータが必要です。

PUT /groups/:id/labels/:label_id
属性種類必須説明
id整数または文字列。yes認証ユーザーが所有するグループのIDまたはURLエンコードされたパス
label_id整数または文字列。yesグループのラベルのIDまたはタイトル。
new_name文字列です。いいえラベルの新しい名前
color文字列です。いいえラベルの色を、先頭の’#’記号付きの6桁の16進数表記(例えば#FFAABB)またはCSSカラー名のいずれかで指定します。
description文字列です。いいえラベルの説明。
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
}
note
パラメータにname を含む古いエンドポイントPUT /groups/:id/labels はまだ利用可能ですが、非推奨です。

グループラベルの削除

指定した名前のグループラベルを削除します。

DELETE /groups/:id/labels/:label_id
属性種類必須説明
id整数または文字列。yes認証ユーザーが所有するグループのIDまたはURLエンコードされたパス
label_id整数または文字列。yesグループのラベルのIDまたはタイトル。
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/bug"
note
パラメータにname を含む古いエンドポイントDELETE /groups/:id/labels はまだ利用可能ですが、非推奨です。

グループラベルの購読

認証済みユーザーをグループラベルに登録し、通知を受け取ります。ユーザーがすでにそのラベルを購読している場合は、ステータスコード304 が返されます。

POST /groups/:id/labels/:label_id/subscribe
属性種類必須説明
id整数または文字列。yes認証ユーザーが所有するグループのIDまたはURLエンコードされたパス
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
}

グループラベルからの退会

認証済みユーザがグループラベルからの通知を受け取らないようにします。ユーザーがそのラベルを購読していない場合は、ステータスコード304 が返されます。

POST /groups/:id/labels/:label_id/unsubscribe
属性種類必須説明
id整数または文字列。yes認証ユーザーが所有するグループのIDまたはURLエンコードされたパス
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
}