主题 API

Tier: 基础版，专业版，旗舰版
Offering: JihuLab.com，私有化部署

使用此 API 与项目主题互动。有关更多信息，请参阅项目主题。

列出主题#

返回极狐GitLab 实例中按相关项目数量排序的项目主题列表。

plaintext
GET /topics

支持的属性：

属性	类型	是否必需	描述
page	integer	No	要检索的页面。默认为 1。
per_page	integer	No	每页返回的记录数。默认为 20。
search	string	No	根据 name 搜索主题。
without_projects	boolean	No	将结果限制为没有分配项目的主题。

示例请求：

shell
curl "https://gitlab.example.com/api/v4/topics?search=git"

示例响应：

json
1[
2  {
3    "id": 1,
4    "name": "gitlab",
5    "title": "GitLab",
6    "description": "GitLab is an open source end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more.",
7    "total_projects_count": 1000,
8    "organization_id": 1,
9    "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon"
10  },
11  {
12    "id": 3,
13    "name": "git",
14    "title": "Git",
15    "description": "Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.",
16    "total_projects_count": 900,
17    "organization_id": 1,
18    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon"
19  },
20  {
21    "id": 2,
22    "name": "git-lfs",
23    "title": "Git LFS",
24    "description": null,
25    "total_projects_count": 300,
26    "organization_id": 1,
27    "avatar_url": null
28  }
29]

获取主题#

通过 ID 获取项目主题。

plaintext
GET /topics/:id

支持的属性：

属性	类型	是否必需	描述
id	integer	Yes	项目主题的 ID

示例请求：

shell
curl "https://gitlab.example.com/api/v4/topics/1"

示例响应：

json
1{
2  "id": 1,
3  "name": "gitlab",
4  "title": "GitLab",
5  "description": "GitLab is an open source end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more.",
6  "total_projects_count": 1000,
7  "organization_id": 1,
8  "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon"
9}

列出分配给主题的项目#

使用 Projects API 列出分配给特定主题的所有项目。

plaintext
GET /projects?topic=<topic_name>

创建项目主题#

创建新的项目主题。仅限管理员使用。

plaintext
POST /topics

支持的属性：

属性	类型	是否必需	描述
name	string	Yes	Slug (名称)
title	string	Yes	标题
avatar	file	No	头像
description	string	No	描述
organization_id	integer	No	主题的组织 ID。WARNING: 此属性是实验性的，未来可能会发生变化。有关组织的更多信息，请参阅 Organizations API

示例请求：

shell
curl --request POST \
     --data "name=topic1&title=Topic 1" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/topics"

示例响应：

json
1{
2  "id": 1,
3  "name": "topic1",
4  "title": "Topic 1",
5  "description": null,
6  "total_projects_count": 0,
7  "organization_id": 1,
8  "avatar_url": null
9}

更新项目主题#

更新项目主题。仅限管理员使用。

plaintext
PUT /topics/:id

支持的属性：

属性	类型	是否必需	描述
id	integer	Yes	项目主题的 ID
avatar	file	No	头像
description	string	No	描述
name	string	No	Slug (名称)
title	string	No	标题

示例请求：

shell
curl --request PUT \
     --data "name=topic1" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/topics/1"

示例响应：

json
1{
2  "id": 1,
3  "name": "topic1",
4  "title": "Topic 1",
5  "description": null,
6  "total_projects_count": 0,
7  "organization_id": 1,
8  "avatar_url": null
9}

上传主题头像#

要从文件系统上传头像文件，请使用 --form 参数。此参数使 cURL 使用 Content-Type: multipart/form-data 标头发布数据。file= 参数必须指向文件系统上的文件，并以 @ 为前缀。例如：

shell
curl --request PUT \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/topics/1" \
     --form "avatar=@/tmp/example.png"

删除主题头像#

要删除主题头像，请为 avatar 属性使用空值。

示例请求：

shell
curl --request PUT \
     --data "avatar=" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/topics/1"

删除项目主题#

您必须是管理员才能删除项目主题。删除项目主题时，还会删除项目的主题分配。

plaintext
DELETE /topics/:id

支持的属性：

属性	类型	是否必需	描述
id	integer	Yes	项目主题的 ID

示例请求：

shell
curl --request DELETE \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/topics/1"

合并主题#

History

在极狐GitLab 15.4 中 Introduced。

您必须是管理员才能将源主题合并到目标主题中。合并主题时，您将删除源主题并将所有分配的项目移动到目标主题。

plaintext
POST /topics/merge

支持的属性：

属性	类型	是否必需	描述
source_topic_id	integer	Yes	源项目主题的 ID
target_topic_id	integer	Yes	目标项目主题的 ID

`source_topic_id` 和 `target_topic_id` 必须属于同一组织。

示例请求：

shell
curl --request POST \
     --data "source_topic_id=2&target_topic_id=1" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/topics/merge"

示例响应：

json
1{
2  "id": 1,
3  "name": "topic1",
4  "title": "Topic 1",
5  "description": null,
6  "total_projects_count": 0,
7  "organization_id": 1,
8  "avatar_url": null
9}