Help us learn about your current experience with the documentation. Take the survey.

主题 API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用此 API 与项目主题进行交互。更多信息请参阅 project topics。

列出主题

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

GET /topics

支持的属性：

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

示例请求：

curl --request GET \
  --url "https://gitlab.example.com/api/v4/topics?search=git"

示例响应：

[
  {
    "id": 1,
    "name": "gitlab",
    "title": "GitLab",
    "description": "GitLab 是一个开源的端到端软件开发平台，内置版本控制、问题跟踪、代码审查、CI/CD 等功能。",
    "total_projects_count": 1000,
    "organization_id": 1,
    "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon"
  },
  {
    "id": 3,
    "name": "git",
    "title": "Git",
    "description": "Git 是一个免费的开源分布式版本控制系统，旨在以速度和效率处理从小型到大型项目的所有事务。",
    "total_projects_count": 900,
    "organization_id": 1,
    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon"
  },
  {
    "id": 2,
    "name": "git-lfs",
    "title": "Git LFS",
    "description": null,
    "total_projects_count": 300,
    "organization_id": 1,
    "avatar_url": null
  }
]

获取主题

通过 ID 获取项目主题。

GET /topics/:id

支持的属性：

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

示例请求：

curl --request GET \
  --url "https://gitlab.example.com/api/v4/topics/1"

示例响应：

{
  "id": 1,
  "name": "gitlab",
  "title": "GitLab",
  "description": "GitLab 是一个开源的端到端软件开发平台，内置版本控制、问题跟踪、代码审查、CI/CD 等功能。",
  "total_projects_count": 1000,
  "organization_id": 1,
  "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon"
}

列出分配给主题的项目

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

GET /projects?topic=<topic_name>

创建项目主题

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

POST /topics

支持的属性：

属性	类型	必需	描述
`name`	string	是	Slug（名称）
`title`	string	是	标题
`avatar`	file	否	头像
`description`	string	否	描述
`organization_id`	integer	否	主题的组织 ID。警告：此属性是实验性的，未来可能会更改。有关组织的更多信息，请参阅 Organizations API

示例请求：

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

示例响应：

{
  "id": 1,
  "name": "topic1",
  "title": "Topic 1",
  "description": null,
  "total_projects_count": 0,
  "organization_id": 1,
  "avatar_url": null
}

更新项目主题

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

PUT /topics/:id

支持的属性：

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

示例请求：

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

示例响应：

{
  "id": 1,
  "name": "topic1",
  "title": "Topic 1",
  "description": null,
  "total_projects_count": 0,
  "organization_id": 1,
  "avatar_url": null
}

上传主题头像

要从文件系统上传头像文件，请使用 --form 参数。此参数会导致 cURL 使用 Content-Type: multipart/form-data 头发布数据。file= 参数必须指向文件系统中的文件，并且前面必须加上 @。例如：

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

删除主题头像

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

示例请求：

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

删除项目主题

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

DELETE /topics/:id

支持的属性：

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

示例请求：

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

合并主题

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

POST /topics/merge

支持的属性：

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

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

示例请求：

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

示例响应：

{
  "id": 1,
  "name": "topic1",
  "title": "Topic 1",
  "description": null,
  "total_projects_count": 0,
  "organization_id": 1,
  "avatar_url": null
}