グループラベルAPI

GitLab 11.8 で導入されました。

グループラベルの管理APIです。 グループラベルの一覧表示、作成、更新、削除が可能で、グループラベルの購読、購読解除もできます。

注：description_html -はGitLab 12.7でレスポンスJSONに追加されました。

グループラベル一覧

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

GET /groups/:id/labels
属性 タイプ 必須 説明
id 整数/文字列 はい 認証されたユーザーが所有するグループのIDまたはURLエンコードされたパス。
with_counts ブーリアン いいえ イシューとマージリクエストのカウントを含めるかどうか。デフォルトはfalse。(GitLab 12.2 で導入)
include_ancestor_groups ブーリアン いいえ 祖先グループを含めます。 デフォルトは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 /groups/:id/labels/:label_id
属性 タイプ 必須 説明
id 整数/文字列 はい 認証されたユーザーが所有するグループのIDまたはURLエンコードされたパス。
label_id 整数または文字列 はい グループのラベルのIDまたはタイトル。
include_ancestor_groups ブーリアン いいえ 祖先グループを含めます。 デフォルトは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 整数/文字列 はい 認証されたユーザーが所有するグループのIDまたはURLエンコードされたパス。
name 列 はい ラベルの名前
color 列 はい ラベルの色を、先頭に’#’記号を付けた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 整数/文字列 はい 認証されたユーザーが所有するグループのIDまたはURLエンコードされたパス。
label_id 整数または文字列 はい グループのラベルの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
}
注意：パラメータにname を使った古いエンドポイントPUT /groups/:id/labels もまだ利用可能ですが、非推奨です。

グループラベルの削除

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

DELETE /groups/:id/labels/:label_id
属性 タイプ 必須 説明
id 整数/文字列 はい 認証されたユーザーが所有するグループのIDまたはURLエンコードされたパス。
label_id 整数または文字列 はい グループのラベルの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 もまだ利用可能ですが、非推奨です。

グループラベルの購読

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

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