本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 Maven 快照
<a name="maven-snapshots"></a>

 Maven *快照*是 Maven 套件的特殊版本，參考最新的生產分支程式碼。這是最終發行版本之前的開發版本。您可以透過附加到套件版本的尾碼`SNAPSHOT`來識別 Maven 套件的快照版本。例如， 版本的快照`1.1`為 `1.1-SNAPSHOT`。如需詳細資訊，請參閱 Apache Maven 專案網站上的[什麼是 SNAPSHOT 版本？](https://maven.apache.org/guides/getting-started/index.html#What_is_a_SNAPSHOT_version)。

 AWS CodeArtifact 支援發佈和使用 Maven 快照。使用以時間為基礎的版本編號的唯一快照是唯一支援的快照。CodeArtifact 不支援 Maven 2 用戶端產生的非唯一快照。您可以將支援的 Maven 快照發佈至任何 CodeArtifact 儲存庫。

**Topics**
+ [CodeArtifact 中的快照發佈](#maven-snapshot-publishing)
+ [使用快照版本](#maven-consuming-snapshot-versions)
+ [刪除快照版本](#maven-deleting-snapshot-versions)
+ [使用 curl 發佈快照](#maven-snapshot-publishing-curl)
+ [快照和外部連線](#maven-snapshot-external-connections)
+ [快照和上游儲存庫](#maven-snapshot-upstream-repositories)

## CodeArtifact 中的快照發佈
<a name="maven-snapshot-publishing"></a>

AWS CodeArtifact 支援用戶端在發佈快照時使用的請求模式`mvn`，例如 。因此，您可以遵循建置工具或套件管理員的文件，而無需詳細了解 Maven 快照的發佈方式。如果您正在做更複雜的事，本節會詳細說明 CodeArtifact 如何處理快照。

 當 Maven 快照發佈至 CodeArtifact 儲存庫時，其先前版本會保留在稱為組建的新版本中。每次發佈 Maven 快照時，都會建立新的建置版本。所有舊版的快照都會保留在其建置版本中。發佈 Maven 快照時，其套件版本狀態會設為 ，`Published`而包含先前版本的組建狀態會設為 `Unlisted`。此行為僅適用於套件版本具有 `-SNAPSHOT`做為尾碼的 Maven 套件版本。

例如，名為 的 maven 套件快照版本`com.mycompany.myapp:pkg-1`會上傳至名為 的 CodeArtifact 儲存庫`my-maven-repo`。快照版本為 `1.0-SNAPSHOT`。目前尚未`com.mycompany.myapp:pkg-1`發佈 的版本。首先，初始建置的資產會發佈在下列路徑：

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

請注意，時間戳記`20210728.194552-1`是由發佈快照建置的用戶端產生。

上傳 .pom 和 .jar 檔案後，儲存庫中唯一存在`com.mycompany.myapp:pkg-1`的 版本是 `1.0-20210728.194552-1`。即使上述路徑中指定的版本為 ，也會發生這種情況`1.0-SNAPSHOT`。目前套件版本狀態為 `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"
}
```

接著，用戶端會上傳套件版本的 `maven-metadata.xml` 檔案：

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

成功上傳 maven-metadata.xml 檔案時，CodeArtifact 會建立`1.0-SNAPSHOT`套件版本，並將`1.0-20210728.194552-1`版本設定為 `Unlisted`。

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

此時，快照版本`1.0-SNAPSHOT`可以在組建中使用。雖然儲存庫 `com.mycompany.myapp:pkg-1`中有兩個版本的 `my-maven-repo`，但它們都包含相同的資產。

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

在 `--package-version` 參數變更為 的情況下執行先前顯示的相同`list-package-version-assets`命令，`1.0-20210728.194552-1`會產生相同的輸出。

當 的其他組建`1.0-SNAPSHOT`新增至儲存庫時，會為每個新組建建立新的`Unlisted`套件版本。每次`1.0-SNAPSHOT`都會更新 版本的資產，讓版本一律參考該版本的最新組建。`1.0-SNAPSHOT` 使用最新資產更新 是透過上傳新建置`maven-metadata.xml`的檔案來啟動。

## 使用快照版本
<a name="maven-consuming-snapshot-versions"></a>

如果您請求快照，`Published`則會傳回狀態為 的版本。這一律是 Maven 快照的最新版本。您也可以使用建置版本編號 （例如，`1.0-20210728.194552-1`) 來請求特定建置快照，而不是 URL 路徑中的快照版本 （例如，`1.0-SNAPSHOT`)。若要查看 Maven 快照的建置版本，請使用 CodeArtifact API 指南中的 [ListPackageVersions ](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListPackageVersions.html) API，並將狀態參數設定為 `Unlisted`。 *CodeArtifact * 

## 刪除快照版本
<a name="maven-deleting-snapshot-versions"></a>

若要刪除 Maven 快照的所有建置版本，請使用 [DeletePackageVersions](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DeletePackageVersions.html) API，指定您要刪除的版本。

## 使用 curl 發佈快照
<a name="maven-snapshot-publishing-curl"></a>

如果您現有的快照版本存放在 Amazon Simple Storage Service (Amazon S3) 或其他成品儲存庫產品中，建議您將其重新發佈至 AWS CodeArtifact。由於 CodeArtifact 如何支援 Maven 快照 （請參閱[CodeArtifact 中的快照發佈](#maven-snapshot-publishing))，使用 等一般 HTTP 用戶端發佈快照比發佈 Maven 發行版本`curl`更為複雜，如中所述[使用 curl 發佈](maven-curl.md)。請注意，如果您使用 `mvn`或 等 Maven 用戶端建置和部署快照版本，則此區段無關`gradle`。您需要遵循該用戶端的文件。

發佈快照版本涉及發佈一個或多個快照版本的組建。在 CodeArtifact 中，如果有 *n* 個快照版本的組建，將會有 *n \$1 1* 個 CodeArtifact 版本：*n* 個全部組建版本的狀態為 `Unlisted`，以及一個快照版本 （最新發佈的組建） 的狀態為 `Published`。快照版本 （即版本字串包含「-SNAPSHOT」的版本，包含一組與最新發佈組建相同的資產。使用 建立此結構的最簡單方式`curl`如下：

1. 使用 發佈所有建置的所有資產`curl`。

1. 使用 發佈最後一個組建`maven-metadata.xml`的檔案 （即具有最新日期時間戳記的組建）`curl`。這將在版本字串中建立具有「`-SNAPSHOT`」且具有正確資產集的版本。

1. 使用 [UpdatePackageVersionsStatus](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdatePackageVersionsStatus.html) API，將所有非最新建置版本的狀態設定為 `Unlisted`。

 使用下列`curl`命令來發佈`1.0-SNAPSHOT`套件快照版本的快照資產 （例如 .jar 和 .pom 檔案）`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
```

使用這些範例時：
+ 將 *my\$1domain* 取代為您的 CodeArtifact 網域名稱。
+ 以 CodeArtifact 網域擁有者的 AWS 帳戶 ID 取代 *111122223333*。
+ 將 *us-west-2* 取代 AWS 區域 為您的 CodeArtifact 網域所在的 。
+ 將 *my\$1maven\$1repo* 取代為您的 CodeArtifact 儲存庫名稱。

**重要**  
您必須在 `--data-binary` 參數的值前面加上 `@` 字元。將值放入引號時，`@`必須包含在引號內。

您可以為每個組建上傳兩個以上的資產。例如，除了主要 JAR 和 之外，可能還有 Javadoc 和來源 JAR 檔案`pom.xml`。不需要發佈套件版本資產的檢查總和檔案，因為 CodeArtifact 會自動為每個上傳的資產產生檢查總和。若要驗證資產是否已正確上傳，請使用 `list-package-version-assets`命令擷取產生的檢查總和，並將其與原始檢查總和進行比較。如需 CodeArtifact 如何處理 Maven 檢查總和的詳細資訊，請參閱 [使用 Maven 檢查總和](maven-checksums.md)。

使用下列 curl 命令發佈最新建置版本的 `maven-metadata.xml` 檔案：

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

`maven-metadata.xml` 檔案必須至少參考 `<snapshotVersions>`元素中最新建置版本的其中一個資產。此外，`<timestamp>`值必須存在，且必須符合資產檔案名稱中的時間戳記。例如，對於先前發佈的`20210729.171330-2`組建， 的內容`maven-metadata.xml`會是：

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

在 發佈`maven-metadata.xml`之後，最後一個步驟是將所有其他組建版本 （也就是除了最新組建以外的所有組建版本） 設定為套件版本狀態為 `Unlisted`。例如，如果`1.0-SNAPSHOT`版本有兩個組建，且第一個組建為 `20210728.194552-1`，則將該組建設定為 的命令`Unlisted`為：

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

## 快照和外部連線
<a name="maven-snapshot-external-connections"></a>

Maven 快照無法透過外部連線從 Maven 公有儲存庫擷取。 AWS CodeArtifact 僅支援匯入 Maven 發行版本。

## 快照和上游儲存庫
<a name="maven-snapshot-upstream-repositories"></a>

一般而言，Maven 快照在與上游儲存庫搭配使用時的運作方式與 Maven 發行版本相同，但如果您計劃將相同套件版本的快照發佈到兩個與上游關係的儲存庫，則會有限制。例如，假設 AWS CodeArtifact 網域中有兩個儲存庫，`R`而 `U`，其中 `U`是 的上游`R`。如果您在 中發佈新組建`R`，當 Maven 用戶端請求該快照版本的最新組建時，CodeArtifact 會從 傳回最新版本`U`。這可能是非預期的，因為最新版本現在位於 中`R`，而不是 `U`。有兩種方法可以避免這種情況：

1. 如果 `1.0-SNAPSHOT`中`1.0-SNAPSHOT`存在 `R`，請勿發佈快照版本的組建，例如 。 `U`

1. 使用 CodeArtifact 套件原始伺服器控制，在 中停用該套件上的上游`R`。後者可讓您在 中發佈 的`1.0-SNAPSHOT`組建`R`，但也會`R`防止 從`U`尚未保留的任何其他版本取得該套件。