Utiliser les instantanés Maven

Un instantané Maven est une version spéciale d'un package Maven qui fait référence au dernier code de branche de production. Il s'agit d'une version de développement qui précède la version finale. Vous pouvez identifier une version instantanée d'un package Maven à l'aide du suffixe SNAPSHOT ajouté à la version du package. Par exemple, l'instantané de la version 1.1 est1.1-SNAPSHOT. Pour plus d'informations, voir Qu'est-ce qu'une version SNAPSHOT ? sur le site Web du projet Apache Maven.

AWS CodeArtifact prend en charge la publication et la consommation d'instantanés Maven. Les instantanés uniques qui utilisent un numéro de version basé sur le temps sont les seuls instantanés pris en charge. CodeArtifact ne prend pas en charge les instantanés non uniques générés par les clients Maven 2. Vous pouvez publier un instantané Maven compatible dans n'importe quel CodeArtifact référentiel.

Publication d'instantanés dans CodeArtifact

AWS CodeArtifact prend en charge les modèles de demande que les clients, par exemplemvn, utilisent lors de la publication de snapshots. De ce fait, vous pouvez suivre la documentation de votre outil de génération ou de votre gestionnaire de packages sans avoir une compréhension détaillée de la manière dont les instantanés Maven sont publiés. Si vous effectuez une opération plus complexe, cette section décrit en détail comment CodeArtifact gérer les instantanés.

Lorsqu'un instantané Maven est publié dans un CodeArtifact référentiel, sa version précédente est préservée dans une nouvelle version appelée build. Chaque fois qu'un instantané Maven est publié, une nouvelle version de build est créée. Toutes les versions précédentes d'un instantané sont conservées dans ses versions de compilation. Lorsqu'un instantané Maven est publié, le statut de la version de son package est défini sur Published et le statut de la version contenant la version précédente est défini sur. Unlisted Ce comportement s'applique uniquement aux versions de package Maven dont le suffixe est -SNAPSHOT la version du package.

Par exemple, les versions instantanées d'un package maven appelé com.mycompany.myapp:pkg-1 sont téléchargées dans un CodeArtifact référentiel appelémy-maven-repo. La version instantanée est1.0-SNAPSHOT. Jusqu'à présent, aucune version de com.mycompany.myapp:pkg-1 n'a été publiée. Tout d'abord, les actifs de la version initiale sont publiés sur les chemins suivants :

PUT maven/my-maven-repo/com/mycompany/myapp/pkg-1/1.0-SNAPSHOT/pkg-1-1.0-20210728.194552-1.jar
PUT maven/my-maven-repo/com/mycompany/myapp/pkg-1/1.0-SNAPSHOT/pkg-1-1.0-20210728.194552-1.pom

Notez que l'horodatage 20210728.194552-1 est généré par le client qui publie les versions instantanées.

Une fois les fichiers .pom et .jar chargés, la seule version com.mycompany.myapp:pkg-1 qui existe dans le référentiel est. 1.0-20210728.194552-1 Cela se produit même si la version spécifiée dans le chemin précédent est1.0-SNAPSHOT. L'état de la version du package à ce stade estUnfinished.

aws codeartifact list-package-versions --domain my-domain --repository \
  my-maven-repo --package pkg-1 --namespace com.mycompany.myapp --format maven
{
    "versions": [
        {
            "version": "1.0-20210728.194552-1",
            "revision": "GipMW+599JmwTcTLaXo9YvDsVQ2bcrrk/02rWJhoKUU=",
            "status": "Unfinished"
        }
    ],
    "defaultDisplayVersion": null,
    "format": "maven",
    "package": "pkg-1",
    "namespace": "com.mycompany.myapp"
}

Ensuite, le client télécharge le maven-metadata.xml fichier correspondant à la version du package :

PUT my-maven-repo/com/mycompany/myapp/pkg-1/1.0-SNAPSHOT/maven-metadata.xml

Lorsque le fichier maven-metadata.xml est correctement chargé, CodeArtifact crée la version 1.0-SNAPSHOT du package et définit la 1.0-20210728.194552-1 version surUnlisted.

aws codeartifact list-package-versions --domain my-domain --repository \
  my-maven-repo --package pkg-1 --namespace com.mycompany.myapp --format maven
{
    "versions": [
        {
            "version": "1.0-20210728.194552-1",
            "revision": "GipMW+599JmwTcTLaXo9YvDsVQ2bcrrk/02rWJhoKUU=",
            "status": "Unlisted"
        },
        {
            "version": "1.0-SNAPSHOT",
            "revision": "tWu8n3IX5HR82vzVZQAxlwcvvA4U/+S80edWNAkil24=",
            "status": "Published"
        }
    ],
    "defaultDisplayVersion": "1.0-SNAPSHOT",
    "format": "maven",
    "package": "pkg-1",
    "namespace": "com.mycompany.myapp"
}

À ce stade, la version instantanée 1.0-SNAPSHOT peut être utilisée dans une version. Bien qu'il existe deux versions de com.mycompany.myapp:pkg-1 dans le référentielmy-maven-repo, elles contiennent toutes les deux les mêmes actifs.

aws codeartifact list-package-version-assets --domain my-domain --repository \
  my-maven-repo --format maven --namespace com.mycompany.myapp \
 --package pkg-1 --package-version 1.0-SNAPSHOT--query 'assets[*].name'
[ 
     "pkg-1-1.0-20210728.194552-1.jar",
     "pkg-1-1.0-20210728.194552-1.pom"
]

L'exécution de la même list-package-version-assets commande que celle indiquée précédemment avec le --package-version paramètre modifié 1.0-20210728.194552-1 permet d'obtenir une sortie identique.

Au fur et à mesure que des versions supplémentaires de 1.0-SNAPSHOT sont ajoutées au référentiel, une nouvelle version de Unlisted package est créée pour chaque nouvelle version. Les actifs de la version 1.0-SNAPSHOT sont mis à jour à chaque fois afin que la version fasse toujours référence à la dernière version pour cette version. La mise à jour du 1.0-SNAPSHOT avec les dernières ressources est lancée en téléchargeant le maven-metadata.xml fichier pour la nouvelle version.

Consommation de versions instantanées

Si vous demandez un instantané, la version avec le statut Published est renvoyée. Il s'agit toujours de la version la plus récente de l'instantané Maven. Vous pouvez également demander une version particulière d'un instantané en utilisant le numéro de version du build (par exemple,1.0-20210728.194552-1) au lieu de la version instantanée (par exemple,1.0-SNAPSHOT) dans le chemin URL. Pour voir les versions de compilation d'un instantané Maven, utilisez l'ListPackageVersions API du guide des CodeArtifact API et définissez le paramètre d'Unlistedétat sur.

Supprimer des versions de snapshots

Pour supprimer toutes les versions de build d'un instantané Maven, utilisez l'DeletePackageVersionsAPI en spécifiant les versions que vous souhaitez supprimer.

Publication d'instantanés avec curl

Si vous avez des versions de snapshots stockées dans Amazon Simple Storage Service (Amazon S3) ou dans un autre produit de référentiel d'artefacts, vous souhaiterez peut-être les republier sur. AWS CodeArtifact En raison de la prise CodeArtifact en charge des instantanés Maven (voirPublication d'instantanés dans CodeArtifact), la publication d'instantanés avec un client HTTP générique tel que la publication de versions de Maven curl est plus complexe que la publication de versions de Maven, comme décrit dans. Publier avec curl Notez que cette section n'est pas pertinente si vous créez et déployez des versions de snapshots avec un client Maven tel que mvn ougradle. Vous devez suivre la documentation relative à ce client.

La publication d'une version instantanée implique la publication d'une ou plusieurs versions d'une version instantanée. Dans CodeArtifact, s'il existe n versions d'une version instantanée, il y aura n + 1 CodeArtifact versions : n versions de version avec un statut deUnlisted, et une version instantanée (la dernière version publiée) avec un statut dePublished. La version instantanée (c'est-à-dire la version dont la chaîne de version contient « -SNAPSHOT ») contient un ensemble d'actifs identique à celui de la dernière version publiée. La méthode la plus simple pour créer cette structure curl est la suivante :

1. Publiez tous les actifs de toutes les versions à l'aide decurl.

2. Publiez le maven-metadata.xml fichier de la dernière version (c'est-à-dire la version avec l'horodatage le plus récent) avec. curl Cela créera une version avec « -SNAPSHOT » dans la chaîne de version et avec le bon ensemble d'actifs.

3. Utilisez l'UpdatePackageVersionsStatusAPI pour définir le statut de toutes les versions de version non récentes surUnlisted.

Utilisez les curl commandes suivantes pour publier les actifs de capture d'écran (tels que les fichiers .jar et .pom) pour la version instantanée 1.0-SNAPSHOT d'un package : com.mycompany.app:pkg-1

curl --user "aws:$CODEARTIFACT_AUTH_TOKEN" -H "Content-Type: application/octet-stream" \
     -X PUT https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/maven/my_maven_repo/com/mycompany/app/pkg-1/1.0-SNAPSHOT/pkg-1-1.0-20210729.171330-2.jar \
     --data-binary @pkg-1-1.0-20210728.194552-1.jar

curl --user "aws:$CODEARTIFACT_AUTH_TOKEN" -H "Content-Type: application/octet-stream" \
     -X PUT https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/maven/my_maven_repo/com/mycompany/app/pkg-1/1.0-SNAPSHOT/pkg-1-1.0-20210729.171330-2.pom \
     --data-binary @pkg-1-1.0-20210728.194552-1.pom

Lorsque vous utilisez ces exemples :

• Remplacez my_domain par votre nom de CodeArtifact domaine.

• Remplacez 111122223333 par l' Compte AWS ID du propriétaire de votre domaine. CodeArtifact

• Remplacez us-west-2 par celui dans lequel se trouve Région AWS votre domaine. CodeArtifact

• Remplacez my_maven_repo par le nom de votre dépôt. CodeArtifact

Important

Vous devez préfixer la valeur du --data-binary paramètre par le @ caractère. Lorsque vous mettez la valeur entre guillemets, @ celle-ci doit être incluse entre guillemets.

Vous pouvez avoir plus de deux actifs à télécharger pour chaque build. Par exemple, il peut y avoir des fichiers Javadoc et JAR source en plus du JAR principal et. pom.xml Il n'est pas nécessaire de publier des fichiers de somme de contrôle pour les actifs de la version du package, car des sommes de contrôle CodeArtifact sont automatiquement générées pour chaque ressource téléchargée. Pour vérifier que les actifs ont été chargés correctement, récupérez les sommes de contrôle générées à l'aide de la list-package-version-assets commande et comparez-les aux sommes de contrôle d'origine. Pour plus d'informations sur le mode de CodeArtifact gestion des checksums Maven, consultez. Utilisation des totaux de contrôle de contrôle de contrôle

Utilisez la commande curl suivante pour publier le maven-metadata.xml fichier correspondant à la dernière version de build :

curl --user "aws:$CODEARTIFACT_AUTH_TOKEN" -H "Content-Type: application/octet-stream" \
     -X PUT https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/maven/my_maven_repo/com/mycompany/app/pkg-1/1.0-SNAPSHOT/maven-metadata.xml \
     --data-binary @maven-metadata.xml

Le maven-metadata.xml fichier doit faire référence à au moins un des actifs de la dernière version de build de l'<snapshotVersions>élément. En outre, la <timestamp> valeur doit être présente et correspondre à l'horodatage figurant dans les noms des fichiers d'actifs. Par exemple, pour le 20210729.171330-2 build publié précédemment, le contenu de maven-metadata.xml serait :

<?xml version="1.0" encoding="UTF-8"?>
<metadata>
  <groupId>com.mycompany.app</groupId>
  <artifactId>pkg-1</artifactId>
  <version>1.0-SNAPSHOT</version>
  <versioning>
    <snapshot>
      <timestamp>20210729.171330</timestamp>
      <buildNumber>2</buildNumber>
    </snapshot>
    <lastUpdated>20210729171330</lastUpdated>
    <snapshotVersions>
      <snapshotVersion>
        <extension>jar</extension>
        <value>1.0-20210729.171330-2</value>
        <updated>20210729171330</updated>
      </snapshotVersion>
      <snapshotVersion>
        <extension>pom</extension>
        <value>1.0-20210729.171330-2</value>
        <updated>20210729171330</updated>
      </snapshotVersion>
    </snapshotVersions>
  </versioning>
</metadata>

Après maven-metadata.xml la publication, la dernière étape consiste à définir toutes les autres versions de build (c'est-à-dire toutes les versions de build à l'exception de la dernière version) pour qu'elles aient le statut de version du package deUnlisted. Par exemple, si la 1.0-SNAPSHOT version comporte deux versions, la première étant la version20210728.194552-1, la commande permettant de définir cette version Unlisted est la suivante :

aws codeartifact update-package-versions-status --domain my-domain --domain-owner 111122223333 \
   --repository my-maven-repo --format maven --namespace com.mycompany.app --package pkg-1 \
   --versions 1.0-20210728.194552-1 --target-status Unlisted

Instantanés et connexions externes

Les instantanés Maven ne peuvent pas être récupérés depuis un dépôt public Maven via une connexion externe. AWS CodeArtifact ne prend en charge que l'importation des versions de Maven.

Instantanés et référentiels en amont

En général, les instantanés Maven fonctionnent de la même manière que les versions de Maven lorsqu'ils sont utilisés avec des référentiels en amont. Supposons, par exemple, qu'il existe deux référentiels dans un AWS CodeArtifact domaine R et U que se U trouve un dépôt en amont deR. Dans ce cas, vous pouvez publier librement des versions instantanées d'un package donné (tel que 1.0-SNAPSHOT ofcom.mycompany.app:pkg-1) à la fois sur R etU. Cependant, certains comportements importants doivent être compris lorsque vous utilisez des versions de snapshots provenant R du référentiel en aval.

1. S'il 1.0-SNAPSHOT est présent dansR, seuls les actifs de 1.0-SNAPSHOT in R peuvent être récupérés à l'aide d'un gestionnaire de packages configuré pour récupérer les packages. R Vous ne pouvez pas récupérer un 1.0-SNAPSHOT actif U viaR. Cela est dû au fait que la version instantanée dans U est masquée par la version dansR. Ce comportement est identique à celui des versions de Maven et à celui des autres formats de package. Dans le schéma, un GET de /maven/R/com/mycompany/myapp/pkg-1/1.0-SNAPSHOT/pkg-1-1.0-20221231.002230-3.jar renverra un code de réponse HTTP 200 (OK), mais un GET de /maven/R/com/mycompany/myapp/pkg-1/1.0-SNAPSHOT/pkg-1-1.0-20221220.150959-1.jar renverra un code de réponse HTTP 404 (Introuvable).

2. S'il 1.0-SNAPSHOT est présent dans, U mais pas dedansR, vous pouvez extraire des actifs 1.0-SNAPSHOT deR. Cela entraînera 1.0-SNAPSHOT son maintien dansR, comme dans une version finale.

3. Une fois 1.0-SNAPSHOT conservé dansR, vous pouvez publier des versions supplémentaires de 1.0-SNAPSHOT inU. Toutefois, ils ne seront pas accessibles depuis en R raison du comportement décrit au point (1). Cela signifie que la justification standard de l'utilisation de versions instantanées, c'est-à-dire la consommation de la dernière version d'une dépendance par le biais d'une version instantanée spécifique, ne fonctionne pas comme prévu dans le cadre d'une relation en amont. Même si les nouvelles versions de 1.0-SNAPSHOT sont publiées surU, les consommateurs ne peuvent pas accéder à la dernière version de 1.0-SNAPSHOT fromR. Pour contourner ce problème, supprimez régulièrement la version 1.0-SNAPSHOT dans R ou configurez le client pour extraire les versions 1.0-SNAPSHOT deU.

4. Les versions de génération de Unlisted snapshots sont accessibles depuis le référentiel en aval. Dans le diagramme, un GET de /maven/R/com/mycompany/myapp/pkg-1/1.0-20221220.150959-1/pkg-1-1.0-20221220.150959-1.jar renverra un code de réponse 200 (OK). Même si cela demande un actif présent dans le référentiel en amont, étant donné que la version est traitée à l'aide de la chaîne de version de construction (1.0-20221220.150959-1), l'actif peut être récupéré via le référentiel en aval. Cela GET entraînera également la conservation 1.0-20221220.150959-1 de la version dansR, avec un statut de version du package deUnlisted.