# Group badges API

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

*   [Placeholder tokens](#placeholder-tokens)
*   [List all badges of a group](#list-all-badges-of-a-group)
*   [Get a badge of a group](#get-a-badge-of-a-group)
*   [Add a badge to a group](#add-a-badge-to-a-group)
*   [Edit a badge of a group](#edit-a-badge-of-a-group)
*   [Remove a badge from a group](#remove-a-badge-from-a-group)
*   [Preview a badge from a group](#preview-a-badge-from-a-group)

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

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

## Placeholder tokens[](#placeholder-tokens "Permalink")

徽章支持占位符，这些占位符将在链接和图像 URL 中被实时替换. 允许的占位符为：

*   **％{project_path}** ：将被项目路径替换.
*   **％{project_id}** ：将被项目 ID 取代.
*   **％{default_branch}** ：将被项目默认分支替换.
*   **％{commit_sha}** ：将由上一个项目的提交 SHA 替换.

由于这些端点不在项目上下文中，因此用于替换占位符的信息将在创建日期之前来自第一组项目. 如果该组没有任何项目，则将返回带有占位符的原始 URL.

## List all badges of a group[](#list-all-badges-of-a-group "Permalink")

获取小组徽章的列表.

```
GET /groups/:id/badges 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `name` | string | no | 要返回的徽章名称（区分大小写）. |

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/badges?name=Coverage" 
```

响应示例：

```
[  {  "name":  "Coverage",  "id":  1,  "link_url":  "http://example.com/ci_status.svg?project=%{project_path}&ref=%{default_branch}",  "image_url":  "https://shields.io/my/badge",  "rendered_link_url":  "http://example.com/ci_status.svg?project=example-org/example-project&ref=master",  "rendered_image_url":  "https://shields.io/my/badge",  "kind":  "group"  }  ] 
```

## Get a badge of a group[](#get-a-badge-of-a-group "Permalink")

获取组的徽章.

```
GET /groups/:id/badges/:badge_id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `badge_id` | integer | yes | 徽章 ID |

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id" 
```

响应示例：

```
{  "id":  1,  "link_url":  "http://example.com/ci_status.svg?project=%{project_path}&ref=%{default_branch}",  "image_url":  "https://shields.io/my/badge",  "rendered_link_url":  "http://example.com/ci_status.svg?project=example-org/example-project&ref=master",  "rendered_image_url":  "https://shields.io/my/badge",  "kind":  "group"  } 
```

## Add a badge to a group[](#add-a-badge-to-a-group "Permalink")

将徽章添加到组.

```
POST /groups/:id/badges 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `link_url` | string | yes | 徽章链接的 URL |
| `image_url` | string | yes | 徽章图片的网址 |

```
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/master&image_url=https://shields.io/my/badge1&position=0" "https://gitlab.example.com/api/v4/groups/:id/badges" 
```

响应示例：

```
{  "id":  1,  "link_url":  "https://gitlab.com/gitlab-org/gitlab-foss/commits/master",  "image_url":  "https://shields.io/my/badge1",  "rendered_link_url":  "https://gitlab.com/gitlab-org/gitlab-foss/commits/master",  "rendered_image_url":  "https://shields.io/my/badge1",  "kind":  "group"  } 
```

## Edit a badge of a group[](#edit-a-badge-of-a-group "Permalink")

Updates a badge of a group.

```
PUT /groups/:id/badges/:badge_id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `badge_id` | integer | yes | 徽章 ID |
| `link_url` | string | no | 徽章链接的 URL |
| `image_url` | string | no | 徽章图片的网址 |

```
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id" 
```

响应示例：

```
{  "id":  1,  "link_url":  "https://gitlab.com/gitlab-org/gitlab-foss/commits/master",  "image_url":  "https://shields.io/my/badge",  "rendered_link_url":  "https://gitlab.com/gitlab-org/gitlab-foss/commits/master",  "rendered_image_url":  "https://shields.io/my/badge",  "kind":  "group"  } 
```

## Remove a badge from a group[](#remove-a-badge-from-a-group "Permalink")

从组中删除徽章.

```
DELETE /groups/:id/badges/:badge_id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `badge_id` | integer | yes | 徽章 ID |

```
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id" 
```

## Preview a badge from a group[](#preview-a-badge-from-a-group "Permalink")

返回解析占位符插值后的`link_url`和`image_url`最终 URL.

```
GET /groups/:id/badges/render 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `link_url` | string | yes | 徽章链接的 URL |
| `image_url` | string | yes | 徽章图片的网址 |

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/badges/render?link_url=http%3A%2F%2Fexample.com%2Fci_status.svg%3Fproject%3D%25%7Bproject_path%7D%26ref%3D%25%7Bdefault_branch%7D&image_url=https%3A%2F%2Fshields.io%2Fmy%2Fbadge" 
```

响应示例：

```
{  "link_url":  "http://example.com/ci_status.svg?project=%{project_path}&ref=%{default_branch}",  "image_url":  "https://shields.io/my/badge",  "rendered_link_url":  "http://example.com/ci_status.svg?project=example-org/example-project&ref=master",  "rendered_image_url":  "https://shields.io/my/badge",  } 
```