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

Maven 虚拟注册表 API

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

这些端点的可用性由一个功能标志控制。 更多信息请查看历史记录。 这些端点处于 beta 阶段。 在使用它们之前，请仔细阅读文档。

使用此 API 创建和管理 Maven 虚拟注册表、配置上游注册表、管理缓存条目以及处理包的下载和上传。

管理虚拟注册表

使用以下端点创建和管理 Maven 虚拟注册表。

列出所有虚拟注册表

列出组的所有 Maven 虚拟注册表。

GET /groups/:id/-/virtual_registries/packages/maven/registries

支持的属性：

属性 类型 必需 描述
id string/integer 是 组 ID 或完整组路径。必须是顶级组。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"

示例响应：

[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-virtual-registry",
    "description": "My virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]

创建虚拟注册表

为组创建 Maven 虚拟注册表。

POST /groups/:id/-/virtual_registries/packages/maven/registries
属性 类型 必需 描述
id string/integer 是 组 ID 或完整组路径。必须是顶级组。
name string 是 虚拟注册表的名称。
description string 否 虚拟注册表的描述。

示例请求：

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data '{"name": "my-virtual-registry", "description": "My virtual registry"}' \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"

示例响应：

{
  "id": 1,
  "group_id": 5,
  "name": "my-virtual-registry",
  "description": "My virtual registry",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z"
}

获取虚拟注册表

获取特定的 Maven 虚拟注册表。

GET /virtual_registries/packages/maven/registries/:id

参数：

属性 类型 必需 描述
id integer 是 Maven 虚拟注册表的 ID。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1"

示例响应：

{
  "id": 1,
  "group_id": 5,
  "name": "my-virtual-registry",
  "description": "My virtual registry",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z"
}

更新虚拟注册表

更新特定的 Maven 虚拟注册表。

PATCH /virtual_registries/packages/maven/registries/:id
属性 类型 必需 描述
id integer 是 Maven 虚拟注册表的 ID。
name string 是 虚拟注册表的名称。
description string 否 虚拟注册表的描述。

示例请求：

curl --request PATCH \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"name": "my-virtual-registry", "description": "My virtual registry"}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1"

如果成功，返回 200 OK 状态码。

删除虚拟注册表

删除虚拟注册表也会删除所有未与其他虚拟注册表共享的关联上游注册表及其缓存条目。

删除特定的 Maven 虚拟注册表。

DELETE /virtual_registries/packages/maven/registries/:id
属性 类型 必需 描述
id integer 是 Maven 虚拟注册表的 ID。

示例请求：

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1"

如果成功，返回 204 No Content 状态码。

删除虚拟注册表的缓存条目

为 Maven 虚拟注册表的所有独占上游注册表安排删除所有缓存条目。对于与其他虚拟注册表关联的上游注册表，不会安排删除缓存条目。

DELETE /virtual_registries/packages/maven/registries/:id/cache
属性 类型 必需 描述
id integer 是 Maven 虚拟注册表的 ID。

示例请求：

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1/cache"

如果成功，返回 204 No Content 状态码。

管理上游注册表

使用以下端点配置和管理上游 Maven 注册表。

列出顶级组的所有上游注册表

列出顶级组的所有上游注册表。

GET /groups/:id/-/virtual_registries/packages/maven/upstreams

支持的属性：

属性 类型 必需 描述
id string/integer 是 组 ID 或完整组路径。必须是顶级组。
page integer 否 页码。默认为 1。
per_page integer 否 每页项目数。默认为 20。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/upstreams"

示例响应：

[
  {
    "id": 1,
    "group_id": 5,
    "url": "https://repo.maven.apache.org/maven2",
    "name": "Maven Central",
    "description": "Maven Central repository",
    "cache_validity_hours": 24,
    "username": "user",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]

列出虚拟注册表的所有上游注册表

列出 Maven 虚拟注册表的所有上游注册表。

GET /virtual_registries/packages/maven/registries/:id/upstreams

支持的属性：

属性 类型 必需 描述
id integer 是 Maven 虚拟注册表的 ID。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1/upstreams"

示例响应：

[
  {
    "id": 1,
    "group_id": 5,
    "url": "https://repo.maven.apache.org/maven2",
    "name": "Maven Central",
    "description": "Maven Central repository",
    "cache_validity_hours": 24,
    "username": "user",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z",
    "registry_upstream": {
      "id": 1,
      "registry_id": 1,
      "position": 1
    }
  }
]

创建上游注册表

向上游 Maven 虚拟注册表添加上游注册表。

POST /virtual_registries/packages/maven/registries/:id/upstreams
属性 类型 必需 描述
id integer 是 Maven 虚拟注册表的 ID。
url string 是 上游注册表的 URL。
username string 否 上游注册表的用户名。
password string 否 上游注册表的密码。
cache_validity_hours integer 否 缓存有效期。默认为 24 小时。

您必须在请求中同时包含 username 和 password，或者完全不包含。如果未设置，将使用公共（匿名）请求访问上游。

示例请求：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"url": "https://repo.maven.apache.org/maven2", "name": "Maven Central", "description": "Maven Central repository", "username": <your_username>, "password": <your_password>, "cache_validity_hours": 48}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1/upstreams"

示例响应：

{
  "id": 1,
  "group_id": 5,
  "url": "https://repo.maven.apache.org/maven2",
  "name": "Maven Central",
  "description": "Maven Central repository",
  "cache_validity_hours": 48,
  "username": "user",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z",
  "registry_upstream": {
    "id": 1,
    "registry_id": 1,
    "position": 1
  }
}

获取上游注册表

获取 Maven 虚拟注册表的特定上游注册表。

GET /virtual_registries/packages/maven/upstreams/:id

参数：

属性 类型 必需 描述
id integer 是 上游注册表的 ID。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1"

示例响应：

{
  "id": 1,
  "group_id": 5,
  "url": "https://repo.maven.apache.org/maven2",
  "name": "Maven Central",
  "description": "Maven Central repository",
  "cache_validity_hours": 24,
  "username": "user",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z",
  "registry_upstreams": [
    {
      "id": 1,
      "registry_id": 1,
      "position": 1
    }
  ]
}

更新上游注册表

更新 Maven 虚拟注册表的特定上游注册表。

PATCH /virtual_registries/packages/maven/upstreams/:id
属性 类型 必需 描述
id integer 是 上游注册表的 ID。
url string 否 上游注册表的 URL。
name string 否 上游注册表的名称。
description string 否 上游注册表的描述。
username string 否 上游注册表的用户名。
password string 否 上游注册表的密码。
cache_validity_hours integer 否 缓存有效期。默认为 24 小时。

您必须在请求中至少提供一个可选参数。

username 和 password 必须同时提供，或者完全不提供。如果未设置，将使用公共（匿名）请求访问上游。

示例请求：

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"cache_validity_hours": 72}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1"

如果成功，返回 200 OK 状态码。

更新上游注册表位置

更新 Maven 虚拟注册表的有序列表中上游注册表的位置。

PATCH /virtual_registries/packages/maven/registry_upstreams/:id
属性 类型 必需 描述
id integer 是 上游注册表的 ID。
position integer 是 上游注册表的位置。介于 1 和 20 之间。

示例请求：

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"position": 5}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registry_upstreams/1"

如果成功，返回 200 OK 状态码。

删除上游注册表

删除 Maven 虚拟注册表的特定上游注册表。

DELETE /virtual_registries/packages/maven/upstreams/:id
属性 类型 必需 描述
id integer 是 上游注册表的 ID。

示例请求：

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1"

如果成功，返回 204 No Content 状态码。

将上游与注册表关联

将现有的上游注册表与 Maven 虚拟注册表关联。

POST /virtual_registries/packages/maven/registry_upstreams
属性 类型 必需 描述
registry_id integer 是 Maven 虚拟注册表的 ID。
upstream_id integer 是 Maven 上游注册表的 ID。

示例请求：

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data '{"registry_id": 1, "upstream_id": 2}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registry_upstreams"

示例响应：

{
  "id": 5,
  "registry_id": 1,
  "upstream_id": 2,
  "position": 2
}

取消上游与注册表的关联

移除上游注册表与 Maven 虚拟注册表之间的关联。

如果这是上游的最后一个关联，移除关联将删除上游本身及其所有缓存条目。

DELETE /virtual_registries/packages/maven/registry_upstreams/:id
属性 类型 必需 描述
id integer 是 注册表上游关联的 ID。

示例请求：

curl --request DELETE \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registry_upstreams/1"

如果成功，返回 204 No Content 状态码。

删除上游注册表的缓存条目

为 Maven 虚拟注册表中的特定上游注册表安排删除所有缓存条目。

DELETE /virtual_registries/packages/maven/upstreams/:id/cache
属性 类型 必需 描述
id integer 是 上游注册表的 ID。

示例请求：

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1/cache"

如果成功，返回 204 No Content 状态码。

管理缓存条目

使用以下端点管理 Maven 虚拟注册表的缓存条目。

列出上游注册表缓存条目

列出 Maven 上游注册表的缓存条目。

GET /virtual_registries/packages/maven/upstreams/:id/cache_entries

支持的属性：

属性 类型 必需 描述
id integer 是 上游注册表的 ID。
search string 否 包相对路径的搜索查询（例如，foo/bar/mypkg）。
page integer 否 页码。默认为 1。
per_page integer 否 每页项目数。默认为 20。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1/cache_entries?search=foo/bar"

示例响应：

[
  {
    "id": "MTUgZm9vL2Jhci9teXBrZy8xLjAtU05BUFNIT1QvbXlwa2ctMS4wLVNOQVBTSE9ULmphcg==",
    "group_id": 5,
    "upstream_id": 1,
    "upstream_checked_at": "2024-05-30T12:28:27.855Z",
    "file_md5": "44f21d5190b5a6df8089f54799628d7e",
    "file_sha1": "74d101856d26f2db17b39bd22d3204021eb0bf7d",
    "size": 2048,
    "relative_path": "foo/bar/package-1.0.0.pom",
    "content_type": "application/xml",
    "upstream_etag": "\"686897696a7c876b7e\"",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]

删除上游注册表缓存条目

删除 Maven 上游注册表的特定缓存条目。

DELETE /virtual_registries/packages/maven/cache_entries/*id
属性 类型 必需 描述
id string 是 缓存条目的 base64 编码上游 ID 和相对路径（例如，‘Zm9vL2Jhci9teXBrZy5wb20=’）。

示例请求：

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/cache_entries/Zm9vL2Jhci9teXBrZy5wb20="

如果成功，返回 204 No Content 状态码。

管理包操作

使用以下端点管理 Maven 虚拟注册表的包操作。

这些端点仅供 GitLab 内部使用，通常不适用于手动调用。

这些端点不遵循 REST API 身份验证方法。 有关支持的标头和令牌类型的更多信息， 请参阅 Maven 虚拟注册表。未记录的身份验证方法将来可能会被移除。

下载包

从 Maven 虚拟注册表下载包。要访问此资源，您必须向注册表进行身份验证。

GET /virtual_registries/packages/maven/:id/*path

支持的属性：

属性 类型 必需 描述
id integer 是 Maven 虚拟注册表的 ID。
path string 是 完整包路径（例如，foo/bar/mypkg/1.0-SNAPSHOT/mypkg-1.0-SNAPSHOT.jar）。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/1/foo/bar/mypkg/1.0-SNAPSHOT/mypkg-1.0-SNAPSHOT.jar" \
     --output mypkg-1.0-SNAPSHOT.jar

如果成功，返回 200 OK 和 以下响应标头：

  • x-checksum-sha1: 文件的 SHA1 校验和
  • x-checksum-md5: 文件的 MD5 校验和
  • Content-Type: 文件的 MIME 类型
  • Content-Length: 文件大小（字节）

上传包

将包上传到 Maven 虚拟注册表。此端点仅可由 GitLab Workhorse 访问。

POST /virtual_registries/packages/maven/:id/*path/upload
属性 类型 必需 描述
id integer 是 Maven 虚拟注册表的 ID。
path string 是 完整包路径（例如，foo/bar/mypkg/1.0-SNAPSHOT/mypkg-1.0-SNAPSHOT.jar）。
file file 是 正在上传的文件。

请求标头：

  • Etag: 文件的实体标签
  • GitLab-Workhorse-Send-Dependency-Content-Type: 文件的内容类型
  • Upstream-GID: 目标上游的全局 ID

如果成功，返回 200 OK 状态码。