API de registre virtuel Maven

{{< details >}}

• Édition : Premium, Ultimate
• Offre : GitLab.com, GitLab Self-Managed, GitLab Dedicated
• Statut : Bêta

{{< /details >}}

{{< history >}}

• Introduit dans GitLab 17.4 avec un flag nommé virtual_registry_maven. Désactivé par défaut.
• Le feature flag a été modifié vers maven_virtual_registry dans GitLab 18.1. Désactivé par défaut. L'indicateur de fonctionnalité virtual_registry_maven a été supprimé.
• Passage de l'expérimentation à la version bêta dans GitLab 18.1.
• Activé sur GitLab.com, GitLab Self-Managed et GitLab Dedicated dans GitLab 18.2.

{{< /history >}}

[!flag] La disponibilité de ces endpoints est contrôlée par un feature flag. Pour plus d'informations, consultez l'historique.

Utilisez cette API pour :

• Créer et gérer des registres virtuels Maven.
• Configurer des registres en amont.
• Gérer les entrées de cache.
• Gérer les téléchargements et les chargements de packages.

Gérer les registres virtuels Maven {#manage-maven-virtual-registries}

Utilisez les endpoints suivants pour créer et gérer des registres virtuels Maven.

Lister tous les registres virtuels {#list-all-virtual-registries}

{{< history >}}

• downloads_count et downloaded_at introduits dans GitLab 18.4.

{{< /history >}}

Liste tous les registres virtuels Maven pour un groupe spécifié.

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

Attributs pris en charge :

Exemple de requête :

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"

Exemple de réponse :

[
  {
    "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"
  }
]

Créer un registre virtuel {#create-a-virtual-registry}

Crée un registre virtuel Maven pour un groupe spécifié.

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

Exemple de requête :

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"

Exemple de réponse :

{
  "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"
}

Récupérer un registre virtuel {#retrieve-a-virtual-registry}

Récupère un registre virtuel Maven spécifié.

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

Paramètres :

Exemple de requête :

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

Exemple de réponse :

{
  "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"
}

Mettre à jour un registre virtuel {#update-a-virtual-registry}

Met à jour un registre virtuel Maven spécifié.

PATCH /virtual_registries/packages/maven/registries/:id

Exemple de requête :

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"

En cas de succès, renvoie un code de statut 200 OK.

Supprimer un registre virtuel {#delete-a-virtual-registry}

[!warning] La suppression d'un registre virtuel supprime également tous les registres en amont associés qui ne sont pas partagés avec d'autres registres virtuels, ainsi que leurs entrées de cache.

Supprime un registre virtuel Maven spécifié.

DELETE /virtual_registries/packages/maven/registries/:id

Exemple de requête :

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"

En cas de succès, renvoie un code de statut 204 No Content.

Supprimer les entrées de cache d'un registre virtuel {#delete-cache-entries-for-a-virtual-registry}

{{< history >}}

• Introduit dans GitLab 18.2 avec un indicateur nommé maven_virtual_registry. Activé par défaut.

{{< /history >}}

Planifie la suppression de toutes les entrées de cache dans tous les registres en amont exclusifs pour un registre virtuel Maven. La suppression des entrées de cache n'est pas planifiée pour les registres en amont associés à d'autres registres virtuels.

DELETE /virtual_registries/packages/maven/registries/:id/cache

Exemple de requête :

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"

En cas de succès, renvoie un code de statut 204 No Content.

Gérer les registres en amont {#manage-upstream-registries}

Utilisez les endpoints suivants pour configurer et gérer les registres Maven en amont.

Lister tous les registres en amont {#list-all-upstream-registries}

{{< history >}}

• Introduit dans GitLab 18.3 avec un flag nommé maven_virtual_registry. Activé par défaut.
• upstream_name introduit dans GitLab 18.4.

{{< /history >}}

Liste tous les registres Maven en amont pour un groupe principal spécifié.

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

Attributs pris en charge :

Exemple de requête :

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"

Exemple de réponse :

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

Tester la connexion au registre en amont avant la création {#test-upstream-registry-connection-before-creation}

{{< history >}}

• Introduit dans GitLab 18.3 avec un flag nommé maven_virtual_registry. Activé par défaut.

{{< /history >}}

Teste la connexion à un registre Maven en amont qui n'a pas encore été ajouté au registre virtuel. Cet endpoint valide la connectivité et les identifiants avant de créer le registre en amont.

POST /groups/:id/-/virtual_registries/packages/maven/upstreams/test

Attributs pris en charge :

[!note] Vous devez inclure à la fois username et password dans la requête, ou n'inclure ni l'un ni l'autre. Si non défini, une requête publique (anonyme) est utilisée pour tester la connexion.

Flux de test {#test-workflow}

L'endpoint test envoie une requête HEAD à l'URL en amont fournie en utilisant un chemin de test pour valider la connectivité et l'authentification. La réponse reçue de la requête HEAD est interprétée comme suit :

Exemple de requête :

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/upstreams/test" \
     --data '{"url": "https://repo.maven.apache.org/maven2"}'

Exemple de réponse :

{
  "success": true
}

Lister tous les registres en amont pour un registre virtuel {#list-all-upstream-registries-for-a-virtual-registry}

Liste tous les registres Maven en amont pour un registre virtuel spécifié.

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

Attributs pris en charge :

Exemple de requête :

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"

Exemple de réponse :

[
  {
    "id": 1,
    "group_id": 5,
    "url": "https://repo.maven.apache.org/maven2",
    "name": "Maven Central",
    "description": "Maven Central repository",
    "cache_validity_hours": 24,
    "metadata_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
    }
  }
]

Créer un registre en amont {#create-an-upstream-registry}

{{< history >}}

• metadata_cache_validity_hours introduit dans GitLab 18.3.

{{< /history >}}

Crée un registre en amont pour un registre virtuel Maven spécifié.

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

[!note] Vous devez inclure à la fois username et password dans la requête, ou ne pas les inclure du tout. Si non défini, une requête publique (anonyme) est utilisée pour accéder au registre en amont.

Vous ne pouvez pas ajouter deux registres en amont avec la même URL et les mêmes identifiants (username et password) au même groupe principal. À la place, vous pouvez :

• Définir des identifiants différents pour chaque registre en amont avec la même URL.
• Associer un registre en amont à plusieurs registres virtuels.

Exemple de requête :

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, "metadata_cache_validity_hours": 1}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1/upstreams"

Exemple de réponse :

{
  "id": 1,
  "group_id": 5,
  "url": "https://repo.maven.apache.org/maven2",
  "name": "Maven Central",
  "description": "Maven Central repository",
  "cache_validity_hours": 48,
  "metadata_cache_validity_hours": 1,
  "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
  }
}

Récupérer un registre en amont {#retrieve-an-upstream-registry}

Récupère un registre en amont spécifié.

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

Paramètres :

Exemple de requête :

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

Exemple de réponse :

{
  "id": 1,
  "group_id": 5,
  "url": "https://repo.maven.apache.org/maven2",
  "name": "Maven Central",
  "description": "Maven Central repository",
  "cache_validity_hours": 24,
  "metadata_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
    }
  ]
}

Mettre à jour un registre en amont {#update-an-upstream-registry}

{{< history >}}

• metadata_cache_validity_hours introduit dans GitLab 18.3.

{{< /history >}}

Met à jour un registre en amont spécifié.

PATCH /virtual_registries/packages/maven/upstreams/:id

[!note] Vous devez fournir au moins un des paramètres optionnels dans votre requête.

Les valeurs username et password doivent être fournies ensemble, ou ne pas être fournies du tout. Si non défini, une requête publique (anonyme) est utilisée pour accéder au registre en amont.

Exemple de requête :

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"

En cas de succès, renvoie un code de statut 200 OK.

Mettre à jour la position d'un registre en amont {#update-an-upstream-registry-position}

Met à jour la position d'un registre en amont dans une liste ordonnée pour un registre virtuel Maven.

PATCH /virtual_registries/packages/maven/registry_upstreams/:id

Exemple de requête :

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"

En cas de succès, renvoie un code de statut 200 OK.

Supprimer un registre en amont {#delete-an-upstream-registry}

Supprime un registre en amont spécifié.

DELETE /virtual_registries/packages/maven/upstreams/:id

Exemple de requête :

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"

En cas de succès, renvoie un code de statut 204 No Content.

Associer un registre en amont à un registre virtuel {#associate-an-upstream-registry-with-a-virtual-registry}

{{< history >}}

• Introduite dans GitLab 18.1 avec un indicateur nommé maven_virtual_registry. Désactivé par défaut.
• Activé sur GitLab.com, GitLab Self-Managed et GitLab Dedicated dans GitLab 18.2.

{{< /history >}}

Associe un registre en amont existant à un registre virtuel Maven spécifié.

POST /virtual_registries/packages/maven/registry_upstreams

Exemple de requête :

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"

Exemple de réponse :

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

Dissocier un registre en amont d'un registre virtuel {#disassociate-an-upstream-registry-from-a-virtual-registry}

{{< history >}}

• Introduite dans GitLab 18.1 avec un indicateur nommé maven_virtual_registry. Désactivé par défaut.
• Activé sur GitLab.com, GitLab Self-Managed et GitLab Dedicated dans GitLab 18.2.

{{< /history >}}

Dissocie un registre en amont d'un registre virtuel Maven spécifié.

DELETE /virtual_registries/packages/maven/registry_upstreams/:id

Exemple de requête :

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"

En cas de succès, renvoie un code de statut 204 No Content.

Supprimer les entrées de cache d'un registre en amont {#delete-cache-entries-for-an-upstream-registry}

{{< history >}}

• Introduit dans GitLab 18.2 avec un indicateur nommé maven_virtual_registry. Activé par défaut.

{{< /history >}}

Planifie la suppression de toutes les entrées de cache pour un registre en amont spécifié.

DELETE /virtual_registries/packages/maven/upstreams/:id/cache

Exemple de requête :

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"

En cas de succès, renvoie un code de statut 204 No Content.

Tester la connexion au registre en amont {#test-upstream-registry-connection}

{{< history >}}

• Introduit dans GitLab 18.3 avec un flag nommé maven_virtual_registry. Activé par défaut.

{{< /history >}}

Teste la connexion à un registre Maven en amont spécifié.

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

Fonctionnement du test {#how-the-test-works}

L'endpoint effectue une requête HEAD vers l'URL en amont en utilisant le chemin de test pour valider la connectivité et l'authentification. Si le registre en amont possède un artefact en cache, son chemin relatif est utilisé pour le test. Sinon, un chemin factice est utilisé. La réponse reçue de la requête HEAD est interprétée comme suit :

[!note] Les réponses 2XX (trouvé) et 404 (non trouvé) indiquent toutes deux une connectivité et une authentification réussies auprès du registre en amont. Le test vérifie que GitLab peut atteindre et s'authentifier auprès du registre en amont, et non si un artefact spécifique existe.

Exemple de requête :

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

Exemple de réponse :

{
  "success": true
}

Tester la connexion au registre en amont avec des paramètres de substitution {#test-upstream-registry-connection-with-override-parameters}

{{< history >}}

• Introduit dans GitLab 18.7 avec un flag nommé maven_virtual_registry. Activé par défaut.

{{< /history >}}

Teste la connexion à un registre Maven en amont spécifié avec des substitutions de paramètres optionnelles.

Ainsi, vous pouvez tester les modifications apportées à l'URL, au nom d'utilisateur ou au mot de passe avant de mettre à jour la configuration du registre en amont.

POST /virtual_registries/packages/maven/upstreams/:id/test

Attributs pris en charge :

Fonctionnement du test {#how-the-test-works-1}

L'endpoint effectue une requête HEAD vers l'URL en amont en utilisant le chemin de test pour valider la connectivité et l'authentification. Si le registre en amont possède un artefact en cache, le chemin relatif du registre en amont est utilisé pour le test. Sinon, un chemin de substitution est utilisé.

Le comportement du test dépend des paramètres fournis :

• Aucun paramètre : Teste le registre en amont avec sa configuration actuelle (URL, nom d'utilisateur et mot de passe existants)
• Substitution d'URL : Teste la connectivité vers la nouvelle URL ; le nom d'utilisateur et le mot de passe doivent être fournis ensemble ou pas du tout
• Substitution d'identifiants : Teste l'URL existante avec de nouveaux identifiants

La réponse reçue de la requête HEAD est interprétée comme suit :

[!note] Les réponses 2XX (trouvé) et 404 (non trouvé) indiquent toutes deux une connectivité et une authentification réussies auprès du registre en amont. Le test ne vérifie pas si un artefact spécifique existe.

Exemple de requête (test de la configuration existante) :

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

Exemple de requête (test avec substitution d'URL et sans identifiants) :

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

Exemple de requête (test avec substitution d'URL et d'identifiants) :

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"url": "<https://new-repo.example.com/maven2>", "username": "<newuser>", "password": "<newpass>"}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1/test"

Exemple de requête (test avec substitution d'identifiants) :

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"username": "<newuser>", "password": "<newpass>"}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1/test"

Exemple de réponse :

{
  "success": true
}

Gérer les entrées de cache {#manage-cache-entries}

Utilisez les endpoints suivants pour gérer les entrées de cache d'un registre virtuel Maven.

Lister toutes les entrées de cache du registre en amont {#list-all-upstream-registry-cache-entries}

Liste toutes les entrées de cache pour un registre Maven en amont spécifié.

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

Attributs pris en charge :

Exemple de requête :

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"

Exemple de réponse :

[
  {
    "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",
    "downloads_count": 6,
    "downloaded_at": "2024-06-05T14:58:32.855Z"
  }
]

Supprimer une entrée de cache du registre en amont {#delete-an-upstream-registry-cache-entry}

Supprime une entrée de cache spécifiée pour un registre Maven en amont.

DELETE /virtual_registries/packages/maven/cache_entries/*id

Exemple de requête :

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="

En cas de succès, renvoie un code de statut 204 No Content.

Gérer les opérations sur les packages {#manage-package-operations}

Utilisez les endpoints suivants pour gérer les opérations sur les packages pour un registre virtuel Maven.

[!warning] Ces endpoints sont destinés à un usage interne par GitLab et ne sont généralement pas conçus pour une utilisation manuelle.

Ces endpoints ne respectent pas les méthodes d'authentification de l'API REST. Pour plus d'informations sur les en-têtes et les types de jetons pris en charge, consultez Registre virtuel Maven. Les méthodes d'authentification non documentées pourraient être supprimées à l'avenir.

Télécharger un package {#download-a-package}

Télécharge un package depuis un registre virtuel Maven spécifié. Pour accéder à cette ressource, vous devez vous authentifier auprès du registre.

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

Attributs pris en charge :

Exemple de requête :

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

En cas de succès, renvoie 200 OK et les en-têtes de réponse suivants :

• x-checksum-sha1 : Somme de contrôle SHA1 du fichier
• x-checksum-md5 : Somme de contrôle MD5 du fichier
• Content-Type : Le type MIME du fichier
• Content-Length : La taille du fichier en octets

Charger un package {#upload-a-package}

Charge un package vers un registre virtuel Maven spécifié. Cet endpoint est accessible uniquement par GitLab Workhorse.

POST /virtual_registries/packages/maven/:id/*path/upload

En-têtes de requête :

• Etag : Balise d'entité pour le fichier
• GitLab-Workhorse-Send-Dependency-Content-Type : Type de contenu du fichier
• Upstream-GID : ID global de la cible en amont

En cas de succès, renvoie un code de statut 200 OK.