294.md

# Project badges API

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

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

# Project badges API[](#project-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 取代.

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

获取项目徽章及其组徽章的列表.

```
GET /projects/: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/projects/:id/badges" 
```

响应示例：

```
[  {  "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":  "project"  },  {  "name":  "Pipeline",  "id":  2,  "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 project[](#get-a-badge-of-a-project "Permalink")

获取项目的徽章.

```
GET /projects/: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/projects/: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":  "project"  } 
```

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

将徽章添加到项目.

```
POST /projects/: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/projects/: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":  "project"  } 
```

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

更新项目的徽章.

```
PUT /projects/: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/projects/: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":  "project"  } 
```

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

从项目中删除徽章. 使用此端点将仅删除项目的标志.

```
DELETE /projects/: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/projects/:id/badges/:badge_id" 
```

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

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

```
GET /projects/: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/projects/: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",  } 
```