软件包 API

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

History

在极狐GitLab 15.3 中，为项目级别的 API 引入了对极狐GitLab CI/CD 作业令牌认证的支持。

The API documentation of 极狐GitLab Packages.

列出软件包#

对于一个项目#

获取项目软件包的列表。所有类型的软件包都包含在结果中。在不使用身份验证访问时，仅返回公共项目的软件包。默认情况下，返回状态为 default、deprecated 和 error 的软件包。使用 status 参数查看其他软件包。

plaintext
GET /projects/:id/packages

属性	类型	必需	描述
id	integer/string	是	ID 或项目的 URL 编码路径。
order_by	string	否	用作排序的字段。可选项为 created_at (默认), name, version, 或 type。
sort	string	否	排序方向，可以是 asc (默认) 表示升序或 desc 表示降序。
package_type	string	否	按类型过滤返回的软件包。可选项为 conan, maven, npm, pypi, composer, nuget, helm, terraform_module, 或 golang。
package_name	string	否	通过名称进行模糊搜索来过滤项目软件包。
package_version	string	否	按版本过滤项目软件包。如果与 include_versionless 一起使用，则不返回无版本软件包。在极狐GitLab 16.6 中引入。
include_versionless	boolean	否	如果设置为 true，则响应中包含无版本的软件包。
status	string	否	按状态过滤返回的软件包。可选项为 default, hidden, processing, error, 或 pending_destruction。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages"

Deprecation:

响应中的 pipelines 属性已弃用，建议使用 list package pipelines endpoint，该功能在极狐GitLab 16.0 中引入。如果软件包没有任何流水线，则响应中不包含 pipelines 属性。否则，pipelines 属性返回一个空数组。

示例响应：

json
1[
2  {
3    "id": 1,
4    "name": "com/mycompany/my-app",
5    "version": "1.0-SNAPSHOT",
6    "package_type": "maven",
7    "created_at": "2019-11-27T03:37:38.711Z"
8  },
9  {
10    "id": 2,
11    "name": "@foo/bar",
12    "version": "1.0.3",
13    "package_type": "npm",
14    "created_at": "2019-11-27T03:37:38.711Z"
15  },
16  {
17    "id": 3,
18    "name": "Hello/0.1@mycompany/stable",
19    "conan_package_name": "Hello",
20    "version": "0.1",
21    "package_type": "conan",
22    "_links": {
23      "web_path": "/foo/bar/-/packages/3",
24      "delete_api_path": "https://gitlab.example.com/api/v4/projects/1/packages/3"
25    },
26    "created_at": "2029-12-16T20:33:34.316Z",
27    "tags": []
28  }
29]

默认情况下，GET 请求返回 20 个结果，因为 API 是分页的。

尽管您可以按状态过滤软件包，但处理状态为 processing 的软件包可能会导致数据格式错误或软件包损坏。

对于一个群组#

获取群组级别的项目软件包列表。在不使用身份验证访问时，仅返回公共项目的软件包。默认情况下，返回状态为 default、deprecated 和 error 的软件包。使用 status 参数查看其他软件包。

plaintext
GET /groups/:id/packages

属性	类型	必需	描述
id	integer/string	是	ID 或群组的 URL 编码路径。
exclude_subgroups	boolean	否	如果参数为 true，则不列出子群组中的项目软件包。默认值为 false。
order_by	string	否	用作排序的字段。可选项为 created_at (默认), name, version, type, 或 project_path。
sort	string	否	排序方向，可以是 asc (默认) 表示升序或 desc 表示降序。
package_type	string	否	按类型过滤返回的软件包。可选项为 conan, maven, npm, pypi, composer, nuget, helm, 或 golang。
package_name	string	否	通过名称进行模糊搜索来过滤项目软件包。
package_version	string	否	按版本过滤返回的软件包。如果与 include_versionless 一起使用，则不返回无版本软件包。在极狐GitLab 16.6 中引入。
include_versionless	boolean	否	如果设置为 true，则响应中包含无版本的软件包。
status	string	否	按状态过滤返回的软件包。可选项为 default, hidden, processing, error, 或 pending_destruction。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/packages?exclude_subgroups=false"

Deprecation:

示例响应：

json
1[
2  {
3    "id": 1,
4    "name": "com/mycompany/my-app",
5    "version": "1.0-SNAPSHOT",
6    "package_type": "maven",
7    "_links": {
8      "web_path": "/namespace1/project1/-/packages/1",
9      "delete_api_path": "/namespace1/project1/-/packages/1"
10    },
11    "created_at": "2019-11-27T03:37:38.711Z",
12    "pipelines": [
13      {
14        "id": 123,
15        "status": "pending",
16        "ref": "new-pipeline",
17        "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
18        "web_url": "https://example.com/foo/bar/pipelines/47",
19        "created_at": "2016-08-11T11:28:34.085Z",
20        "updated_at": "2016-08-11T11:32:35.169Z",
21        "user": {
22          "name": "Administrator",
23          "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon"
24        }
25      }
26    ]
27  },
28  {
29    "id": 2,
30    "name": "@foo/bar",
31    "version": "1.0.3",
32    "package_type": "npm",
33    "_links": {
34      "web_path": "/namespace1/project1/-/packages/1",
35      "delete_api_path": "/namespace1/project1/-/packages/1"
36    },
37    "created_at": "2019-11-27T03:37:38.711Z",
38    "pipelines": [
39      {
40        "id": 123,
41        "status": "pending",
42        "ref": "new-pipeline",
43        "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
44        "web_url": "https://example.com/foo/bar/pipelines/47",
45        "created_at": "2016-08-11T11:28:34.085Z",
46        "updated_at": "2016-08-11T11:32:35.169Z",
47        "user": {
48          "name": "Administrator",
49          "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon"
50        }
51      }
52    ]
53  }
54]

默认情况下，GET 请求返回 20 个结果，因为 API 是分页的。

_links 对象包含以下属性：

web_path: 您可以在极狐GitLab 中访问并查看软件包详细信息的路径。
delete_api_path: 删除软件包的 API 路径。仅当请求用户有权限时可用。

尽管您可以按状态过滤软件包，但处理状态为 processing 的软件包可能会导致数据格式错误或软件包损坏。

获取项目软件包#

获取单个项目软件包。仅返回状态为 default 或 deprecated 的软件包。

plaintext
GET /projects/:id/packages/:package_id

属性	类型	必需	描述
id	integer/string	是	ID 或项目的 URL 编码路径。
package_id	integer	是	软件包的 ID。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages/:package_id"

Deprecation:

示例响应：

json
1{
2  "id": 1,
3  "name": "com/mycompany/my-app",
4  "version": "1.0-SNAPSHOT",
5  "package_type": "maven",
6  "_links": {
7    "web_path": "/namespace1/project1/-/packages/1",
8    "delete_api_path": "/namespace1/project1/-/packages/1"
9  },
10  "created_at": "2019-11-27T03:37:38.711Z",
11  "last_downloaded_at": "2022-09-07T07:51:50.504Z",
12  "pipelines": [
13    {
14      "id": 123,
15      "status": "pending",
16      "ref": "new-pipeline",
17      "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
18      "web_url": "https://example.com/foo/bar/pipelines/47",
19      "created_at": "2016-08-11T11:28:34.085Z",
20      "updated_at": "2016-08-11T11:32:35.169Z",
21      "user": {
22        "name": "Administrator",
23        "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon"
24      }
25    }
26  ],
27  "versions": [
28    {
29      "id":2,
30      "version":"2.0-SNAPSHOT",
31      "created_at":"2020-04-28T04:42:11.573Z",
32      "pipelines": [
33        {
34          "id": 234,
35          "status": "pending",
36          "ref": "new-pipeline",
37          "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
38          "web_url": "https://example.com/foo/bar/pipelines/58",
39          "created_at": "2016-08-11T11:28:34.085Z",
40          "updated_at": "2016-08-11T11:32:35.169Z",
41          "user": {
42            "name": "Administrator",
43            "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon"
44          }
45        }
46      ]
47    }
48  ]
49}

_links 对象包含以下属性：

web_path: 您可以在极狐GitLab 中访问并查看软件包详细信息的路径。仅当软件包状态为 default 或 deprecated 时可用。
delete_api_path: 删除软件包的 API 路径。仅当请求用户有权限时可用。

列出软件包文件#

获取单个软件包的软件包文件列表。

plaintext
GET /projects/:id/packages/:package_id/package_files

属性	类型	必需	描述
id	integer/string	是	ID 或项目的 URL 编码路径
package_id	integer	是	软件包的 ID。
order_by	string	否	用作排序的字段。可选项为 id (默认), file_name, created_at。
sort	string	否	排序方向，可以是 asc (默认) 表示升序或 desc 表示降序。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages/:package_id/package_files"

示例响应：

json
1[
2  {
3    "id": 25,
4    "package_id": 4,
5    "created_at": "2018-11-07T15:25:52.199Z",
6    "file_name": "my-app-1.5-20181107.152550-1.jar",
7    "size": 2421,
8    "file_md5": "58e6a45a629910c6ff99145a688971ac",
9    "file_sha1": "ebd193463d3915d7e22219f52740056dfd26cbfe",
10    "file_sha256": "a903393463d3915d7e22219f52740056dfd26cbfeff321b",
11    "pipelines": [
12      {
13        "id": 123,
14        "status": "pending",
15        "ref": "new-pipeline",
16        "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
17        "web_url": "https://example.com/foo/bar/pipelines/47",
18        "created_at": "2016-08-11T11:28:34.085Z",
19        "updated_at": "2016-08-11T11:32:35.169Z",
20        "user": {
21          "name": "Administrator",
22          "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon"
23        }
24      }
25    ]
26  },
27  {
28    "id": 26,
29    "package_id": 4,
30    "created_at": "2018-11-07T15:25:56.776Z",
31    "file_name": "my-app-1.5-20181107.152550-1.pom",
32    "size": 1122,
33    "file_md5": "d90f11d851e17c5513586b4a7e98f1b2",
34    "file_sha1": "9608d068fe88aff85781811a42f32d97feb440b5",
35    "file_sha256": "2987d068fe88aff85781811a42f32d97feb4f092a399"
36  },
37  {
38    "id": 27,
39    "package_id": 4,
40    "created_at": "2018-11-07T15:26:00.556Z",
41    "file_name": "maven-metadata.xml",
42    "size": 767,
43    "file_md5": "6dfd0cce1203145a927fef5e3a1c650c",
44    "file_sha1": "d25932de56052d320a8ac156f745ece73f6a8cd2",
45    "file_sha256": "ac849d002e56052d320a8ac156f745ece73f6a8cd2f3e82"
46  }
47]

默认情况下，GET 请求返回 20 个结果，因为 API 是分页的。

列出软件包流水线#

History

引入于极狐GitLab 16.1。

获取单个软件包的流水线列表。结果按 id 降序排序。

结果是分页的，每页最多返回 20 条记录。

plaintext
GET /projects/:id/packages/:package_id/pipelines

属性	类型	必需	描述
id	integer/string	是	ID 或项目的 URL 编码路径
package_id	integer	是	软件包的 ID。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages/:package_id/pipelines"

示例响应：

json
1[
2  {
3    "id": 1,
4    "iid": 1,
5    "project_id": 9,
6    "sha": "2b6127f6bb6f475c4e81afcc2251e3f941e554f9",
7    "ref": "mytag",
8    "status": "failed",
9    "source": "push",
10    "created_at": "2023-02-01T12:19:21.895Z",
11    "updated_at": "2023-02-01T14:00:05.922Z",
12    "web_url": "http://gdk.test:3001/feature-testing/composer-repository/-/pipelines/1",
13    "user": {
14      "id": 1,
15      "username": "root",
16      "name": "Administrator",
17      "state": "active",
18      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
19      "web_url": "http://gdk.test:3001/root"
20    }
21  },
22  {
23    "id": 2,
24    "iid": 2,
25    "project_id": 9,
26    "sha": "e564015ac6cb3d8617647802c875b27d392f72a6",
27    "ref": "main",
28    "status": "canceled",
29    "source": "push",
30    "created_at": "2023-02-01T12:23:23.694Z",
31    "updated_at": "2023-02-01T12:26:28.635Z",
32    "web_url": "http://gdk.test:3001/feature-testing/composer-repository/-/pipelines/2",
33    "user": {
34      "id": 1,
35      "username": "root",
36      "name": "Administrator",
37      "state": "active",
38      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
39      "web_url": "http://gdk.test:3001/root"
40    }
41  }
42]

删除项目软件包#

删除项目软件包。

plaintext
DELETE /projects/:id/packages/:package_id

属性	类型	必需	描述
id	integer/string	是	ID 或项目的 URL 编码路径
package_id	integer	是	软件包的 ID。

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages/:package_id"

可能返回以下状态代码：

204 No Content: 软件包已成功删除。
403 Forbidden: 软件包被保护无法删除。
404 Not Found: 未找到软件包。

如果启用了请求转发，删除软件包可能会引入依赖混淆风险。

如果软件包受保护规则保护，则禁止删除该软件包。

删除软件包文件#

删除软件包文件可能会导致软件包损坏，使其无法使用或无法从您的软件包管理器客户端提取。在删除软件包文件时，请确保您了解所做的操作。

删除软件包文件：

plaintext
DELETE /projects/:id/packages/:package_id/package_files/:package_file_id

属性	类型	必需	描述
id	integer/string	是	ID 或项目的 URL 编码路径。
package_id	integer	是	软件包的 ID。
package_file_id	integer	是	软件包文件的 ID。

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages/:package_id/package_files/:package_file_id"

可能返回以下状态代码：

204 No Content: 软件包文件已成功删除。
403 Forbidden: 用户没有删除文件的权限或软件包被保护无法删除。
404 Not Found: 未找到软件包或软件包文件。

如果软件包文件所属的软件包受保护规则保护，则禁止删除软件包文件。