Usar snapshot do Maven

Um snapshot do Maven é uma versão especial de um pacote do Maven que se refere ao código de ramificação de produção mais recente. É uma versão de desenvolvimento que precede a versão final de lançamento. Você pode identificar a versão de snapshot de um pacote do Maven pelo sufixo SNAPSHOT anexado à versão do pacote. Por exemplo, o snapshot da versão 1.1 é 1.1-SNAPSHOT. Para obter mais informações, consulte O que é uma versão de SNAPSHOT? no site do Apache Maven Project.

AWS CodeArtifact suporta a publicação e o consumo de instantâneos do Maven. Instantâneos exclusivos que usam um número de versão baseado em tempo são os únicos instantâneos compatíveis. CodeArtifact não suporta instantâneos não exclusivos que são gerados por clientes Maven 2. Você pode publicar um snapshot compatível do Maven em qualquer CodeArtifact repositório.

Publicação de instantâneos em CodeArtifact

AWS CodeArtifact suporta os padrões de solicitação que os clientes, por exemplomvn, usam ao publicar instantâneos. Por isso, você pode seguir a documentação da sua ferramenta de compilação ou gerenciador de pacotes sem ter uma compreensão detalhada de como os snapshots do Maven são publicados. Se você estiver fazendo algo mais complexo, esta seção descreve em detalhes como CodeArtifact lidar com instantâneos.

Quando um snapshot do Maven é publicado em um CodeArtifact repositório, sua versão anterior é preservada em uma nova versão chamada compilação. Cada vez que um snapshot do Maven é publicado, uma nova versão de compilação é criada. Todas as versões anteriores de um snapshot são mantidas em suas versões de compilação. Quando um snapshot do Maven é publicado, o status da versão do pacote é definido como Published e o status da compilação que contém a versão anterior é definido como Unlisted. Esse comportamento se aplica somente às versões do pacote Maven onde o sufixo é -SNAPSHOT.

Por exemplo, versões instantâneas de um pacote maven chamado com.mycompany.myapp:pkg-1 são carregadas em um CodeArtifact repositório chamado. my-maven-repo A versão de snapshot é 1.0-SNAPSHOT. Até o momento, nenhuma versão do com.mycompany.myapp:pkg-1 foi publicada. Primeiro, os ativos da compilação inicial são publicados nos seguintes caminhos:

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

Observe que o timestamp 20210728.194552-1 é gerado pelo cliente que publica as compilações do snapshot.

Depois que os arquivos .pom e .jar forem carregados, a única versão do com.mycompany.myapp:pkg-1 presente no repositório será 1.0-20210728.194552-1. Isso acontece mesmo que a versão especificada no caminho anterior seja 1.0-SNAPSHOT. O status da versão do pacote nesse momento é Unfinished.

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

Em seguida, o cliente faz o upload do arquivo maven-metadata.xml para a versão do pacote:

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

Quando o arquivo maven-metadata.xml é carregado com sucesso, CodeArtifact cria a versão do 1.0-SNAPSHOT pacote e define a 1.0-20210728.194552-1 versão comoUnlisted.

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

Nesse ponto, a versão de snapshot 1.0-SNAPSHOT pode ser consumida em uma compilação. Embora existam duas versões do com.mycompany.myapp:pkg-1 no repositório my-maven-repo, ambas contêm os mesmos ativos.

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

Executar o mesmo comando list-package-version-assets mostrado anteriormente com o parâmetro --package-version alterado para 1.0-20210728.194552-1 resulta em uma saída idêntica.

À medida que outras compilações do 1.0-SNAPSHOT são adicionadas ao repositório, uma nova versão Unlisted do pacote é criada para cada nova compilação. Os ativos da versão 1.0-SNAPSHOT são atualizados todas as vezes, para que a versão sempre se refira à compilação mais recente. A atualização do 1.0-SNAPSHOT com os ativos mais recentes é iniciada com o upload do arquivo maven-metadata.xml para a nova compilação.

Consumir versões de snapshot

Se você solicitar um snapshot, a versão com o status Published será retornada. É sempre a versão mais recente de snapshot do Maven. Você também pode solicitar uma compilação específica de um snapshot usando o número da versão da compilação (por exemplo, 1.0-20210728.194552-1) em vez da versão de snapshot (por exemplo, 1.0-SNAPSHOT) no caminho do URL. Para ver as versões de compilação de um snapshot do Maven, use a ListPackageVersions API no Guia da CodeArtifact API e defina o parâmetro de status como. Unlisted

Excluir versões de snapshot

Para excluir todas as versões de compilação de um snapshot do Maven, use a DeletePackageVersionsAPI, especificando as versões que você deseja excluir.

Publicação de snapshot com curl

Se você tiver versões de snapshots existentes armazenadas no Amazon Simple Storage Service (Amazon S3) ou em outro produto de repositório de artefatos, talvez queira republicá-las no. AWS CodeArtifact Devido à forma como CodeArtifact suporta instantâneos do Maven (consultePublicação de instantâneos em CodeArtifact), publicar instantâneos com um cliente HTTP genérico, como o, curl é mais complexo do que publicar versões de lançamento do Maven, conforme descrito em. Publicar com curl Observe que esta seção não será relevante se você estiver criando e implantando versões de snapshot com um cliente Maven como mvn ou gradle. É preciso seguir a documentação desse cliente.

Publicar uma versão de snapshot envolve a publicação de uma ou mais compilações. Em CodeArtifact, se houver n compilações de uma versão de instantâneo, haverá n + 1 CodeArtifact versões: n versões de compilação, todas com um status deUnlisted, e uma versão de instantâneo (a última compilação publicada) com um status de. Published A versão de snapshot (ou seja, a versão com uma string de versão que contém “-SNAPSHOT”) contém um conjunto de ativos idêntico ao da compilação mais recente publicada. A forma mais fácil de criar essa estrutura usando curl é a seguinte:

1. Publique todos os ativos de todas as compilações usando curl.

2. Publique o arquivo maven-metadata.xml da compilação mais recente (ou seja, a compilação com a marca de data e hora mais recente) com curl. Isso criará uma versão com “-SNAPSHOT” na string da versão e com o conjunto correto de ativos.

3. Use a UpdatePackageVersionsStatusAPI para definir o status de todas as versões de compilação não mais recentes comoUnlisted.

Use os comandos curl a seguir para publicar ativos de snapshots (como arquivos. jar e .pom) para a versão 1.0-SNAPSHOT de snapshot de um pacote 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

Ao usar esses exemplos:

• Substitua my_domain pelo nome do seu CodeArtifact domínio.

• Substitua 111122223333 pelo Conta da AWS ID do proprietário do seu domínio. CodeArtifact

• Substitua us-west-2 Região da AWS pelo em que CodeArtifact seu domínio está localizado.

• Substitua my_maven_repo pelo nome do seu repositório. CodeArtifact

Importante

Será preciso prefixar o valor do parâmetro --data-binary com o caractere @. Ao colocar o valor entre aspas, @ deve ser incluído entre aspas.

Você pode ter mais de dois ativos para carregar em cada compilação. Por exemplo, pode haver arquivos Javadoc e JAR de origem, além do JAR principal e pom.xml. Não é necessário publicar arquivos de soma de verificação para os ativos da versão do pacote porque gera CodeArtifact automaticamente somas de verificação para cada ativo carregado. Para verificar se os ativos foram carregados corretamente, busque as somas de verificação geradas usando o comando list-package-version-assets e compare-as com as originais. Para obter mais informações sobre como CodeArtifact manipula as somas de verificação do Maven, consulte. Usar somas de verificação do Maven

Use o comando curl a seguir para publicar o arquivo maven-metadata.xml para a versão de compilação mais recente:

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

O arquivo maven-metadata.xml deve fazer referência a pelo menos um dos ativos na versão de compilação mais recente do elemento <snapshotVersions>. Além disso, o valor <timestamp> deve estar presente e corresponder ao timestamp nos nomes dos arquivos do ativo. Por exemplo, para a compilação de 20210729.171330-2 publicada anteriormente, o conteúdo de maven-metadata.xml deve ser:

<?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>

Depois da publicação de maven-metadata.xml, a última etapa é definir que todas as outras versões de compilação (ou seja, todas as versões de compilação, exceto a compilação mais recente) tenham o status de versão do pacote de Unlisted. Por exemplo, se a versão 1.0-SNAPSHOT tiver duas compilações, sendo a primeira compilação 20210728.194552-1, o comando para definir essa compilação como Unlisted será:

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

Snapshots e conexões externas

Os instantâneos do Maven não podem ser obtidos de um repositório público do Maven por meio de uma conexão externa. AWS CodeArtifact só suporta a importação de versões de lançamento do Maven.

Snapshots e repositórios upstream

Em geral, os snapshots do Maven funcionam da mesma forma que as versões de lançamento do Maven, quando usadas com repositórios upstream. Por exemplo, digamos que há dois repositórios em um AWS CodeArtifact domínio R eU, onde U está um upstream de. R Nessa situação, você pode publicar livremente compilações de snapshots de um determinado pacote (como 1.0-SNAPSHOT de com.mycompany.app:pkg-1) tanto em R quanto em U. No entanto, há alguns comportamentos importantes a serem compreendidos ao consumir compilações de snapshots do R ( repositório downstream).

1. Se 1.0-SNAPSHOT estiver presente em R, somente os ativos de 1.0-SNAPSHOT em R poderão ser recuperados com um gerenciador de pacotes configurado para buscar pacotes do R. Você não pode recuperar um ativo de 1.0-SNAPSHOT em U através de R. Isso ocorre porque a versão de snapshot em U é sombreada pela versão em R. Esse comportamento é idêntico ao das versões de lançamento do Maven e ao de outros formatos de pacote. No diagrama, um GET de /maven/R/com/mycompany/myapp/pkg-1/1.0-SNAPSHOT/pkg-1-1.0-20221231.002230-3.jar retornará um código de resposta HTTP 200 (OK), mas um GET de /maven/R/com/mycompany/myapp/pkg-1/1.0-SNAPSHOT/pkg-1-1.0-20221220.150959-1.jar retornará um código de resposta HTTP 404 (Não encontrado).

2. Se 1.0-SNAPSHOT estiver presente em U, mas não dentro de R, você pode extrair ativos de 1.0-SNAPSHOT do R. Isso fará com 1.0-SNAPSHOT que seja mantido em R, da mesma forma que em uma versão de lançamento.

3. Depois de 1.0-SNAPSHOT ser mantido em R, você pode publicar compilações adicionais de 1.0-SNAPSHOT em U. No entanto, eles não ficarão acessíveis a parti de R devido ao comportamento descrito no ponto (1). Isso significa que a lógica padrão para usar versões de snapshot, ou seja, consumir a versão mais recente de uma dependência por meio de uma versão de snapshot específica, não funciona conforme o esperado em um relacionamento upstream. Mesmo que as novas versões do 1.0-SNAPSHOT sejam publicadas no U, os consumidores não conseguirão acessar a compilação mais recente do 1.0-SNAPSHOT a partir de R. Para contornar isso, exclua periodicamente a versão 1.0-SNAPSHOT em R ou configure o cliente para extrair versões de 1.0-SNAPSHOT a partir de U.

4. As versões de compilação de snapshot de Unlisted podem ser acessadas no repositório downstream. No diagrama, um GET de /maven/R/com/mycompany/myapp/pkg-1/1.0-20221220.150959-1/pkg-1-1.0-20221220.150959-1.jar retornará um código de resposta 200 (OK). Mesmo que um ativo presente no repositório upstream seja solicitado, como a versão é endereçada usando a string de versão de compilação (1.0-20221220.150959-1), o ativo poderá ser obtido por meio do repositório downstream. Esse GET também fará com que a versão 1.0-20221220.150959-1 seja mantida em R, com um status de versão do pacote de Unlisted.