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

# 搭配貨運使用 CodeArtifact
使用貨運

這些主題說明如何搭配 CodeArtifact 使用 Rust 套件管理工具 Cargo。

**注意**  
CodeArtifact 僅支援 Cargo 1.74.0 及更高版本。Cargo 1.74.0 是支援 CodeArtifact 儲存庫身分驗證的最早版本。

**Topics**
+ [設定和使用貨運](configure-use-cargo.md)
+ [

# 貨運命令支援
](cargo-commands.md)

# 透過 CodeArtifact 設定和使用貨運
設定和使用貨運

您可以使用 Cargo 從 CodeArtifact 儲存庫發佈和下載木箱，或從 Rust 社群的木箱登錄檔 [crates.io](https://crates.io/) 擷取木箱。本主題說明如何設定 Cargo 來驗證和使用 CodeArtifact 儲存庫。

## 使用 CodeArtifact 設定貨運


若要使用 Cargo 從 AWS CodeArtifact 安裝和發佈箱子，您必須先使用 CodeArtifact 儲存庫資訊進行設定。請依照下列其中一個程序的步驟，使用 CodeArtifact 儲存庫端點資訊和登入資料來設定貨運。

### 使用主控台指示設定貨運


您可以使用 主控台中的組態指示，將 Cargo 連線至 CodeArtifact 儲存庫。主控台指示提供針對 CodeArtifact 儲存庫自訂的貨運組態。您可以使用此自訂組態來設定貨運，而無需尋找和填寫 CodeArtifact 資訊。

1. 開啟位於 [https://console.aws.amazon.com/codesuite/codeartifact/home](https://console.aws.amazon.com/codesuite/codeartifact/home) 的 AWS CodeArtifact 主控台。

1. 在導覽窗格中，選擇**儲存庫**，然後選擇要連線至貨運的儲存庫。

1. 選擇**檢視連線指示**。

1. 選擇您的作業系統。

1. 選擇**貨運**。

1. 遵循產生的說明，將貨運連線至 CodeArtifact 儲存庫。

### 手動設定貨運


如果您無法或不想使用主控台的組態指示，您可以使用下列指示手動將貨運連線至 CodeArtifact 儲存庫。

------
#### [ macOS and Linux ]

若要使用 CodeArtifact 設定 Cargo，您需要在 Cargo 組態中將 CodeArtifact 儲存庫定義為登錄檔，並提供登入資料。
+ 將 *my\$1registry* 取代為您的登錄檔名稱。
+ 以您的 CodeArtifact 網域名稱取代 *my\$1domain*。
+ 以網域擁有者 AWS 的帳戶 ID 取代 *111122223333*。如果您要存取您擁有之網域中的儲存庫，則不需要包含 `--domain-owner`。如需詳細資訊，請參閱[跨帳戶網域](domain-overview.md#domain-overview-cross-account)。
+ 將 *my\$1repo* 取代為您的 CodeArtifact 儲存庫名稱。

複製組態以發佈和下載 Cargo 套件到您的儲存庫，並將其儲存在`~/.cargo/config.toml`檔案中以供系統層級組態或專案層級組態`.cargo/config.toml`使用：

```
[registries.my_registry]
index = "sparse+https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/cargo/my_repo/"
credential-provider = "cargo:token-from-stdout aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --region us-west-2 --query authorizationToken --output text"

[registry]
default = "my_registry"

[source.crates-io]
replace-with = "my_registry"
```

------
#### [ Windows: Download packages only ]

若要使用 CodeArtifact 設定 Cargo，您需要在 Cargo 組態中將 CodeArtifact 儲存庫定義為登錄檔，並提供登入資料。
+ 以您的登錄檔名稱取代 *my\$1registry*。
+ 以您的 CodeArtifact 網域名稱取代 *my\$1domain*。
+ 以網域擁有者 AWS 的帳戶 ID 取代 *111122223333*。如果您要存取您擁有之網域中的儲存庫，則不需要包含 `--domain-owner`。如需詳細資訊，請參閱[跨帳戶網域](domain-overview.md#domain-overview-cross-account)。
+ 將 *my\$1repo* 取代為您的 CodeArtifact 儲存庫名稱。

將組態複製到僅從您的儲存庫下載貨運套件，並將其儲存在`%USERPROFILE%\.cargo\config.toml`檔案中，用於系統層級組態或`.cargo\config.toml`專案層級組態：

```
[registries.my_registry]
index = "sparse+https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/cargo/my_repo/"
credential-provider = "cargo:token-from-stdout aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --region us-west-2 --query authorizationToken --output text"

[registry]
default = "my_registry"

[source.crates-io]
replace-with = "my_registry"
```

------
#### [ Windows: Publish and download packages ]

1. 若要使用 CodeArtifact 設定 Cargo，您需要在 Cargo 組態中將 CodeArtifact 儲存庫定義為登錄檔，並提供登入資料。
   + 以您的登錄檔名稱取代 *my\$1registry*。
   + 以您的 CodeArtifact 網域名稱取代 *my\$1domain*。
   + 以網域擁有者 AWS 的帳戶 ID 取代 *111122223333*。如果您要存取您擁有之網域中的儲存庫，則不需要包含 `--domain-owner`。如需詳細資訊，請參閱[跨帳戶網域](domain-overview.md#domain-overview-cross-account)。
   + 將 *my\$1repo* 取代為您的 CodeArtifact 儲存庫名稱。

   複製組態以發佈和下載 Cargo 套件到您的儲存庫，並將其儲存在 `%USERPROFILE%\.cargo\config.toml`檔案中以供系統層級組態或專案層級組態`.cargo\config.toml`使用。

   建議您使用登入資料提供者 `cargo:token`，其會使用存放在您`~/.cargo/credentials.toml`檔案中的登入資料。如果您使用 `cargo publish` ，您可能會在 期間遇到錯誤，`cargo:token-from-stdout`因為 Cargo 用戶端在 期間未正確裁剪授權字符`cargo publish`。

   ```
   [registries.my_registry]
   index = "sparse+https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/cargo/my_repo/"
   credential-provider = "cargo:token"
   
   [registry]
   default = "my_registry"
   
   [source.crates-io]
   replace-with = "my_registry"
   ```

1. 若要使用 Windows 將 Cargo 套件發佈到您的儲存庫，您必須使用 CodeArtifact `get-authorization-token`命令和 Cargo `login`命令來擷取授權字符和您的登入資料。
   + 將 *my\$1registry* 取代為您的登錄檔名稱，如 中所定義`[registries.my_registry]`。
   + 以您的 CodeArtifact 網域名稱取代 *my\$1domain*。
   + 以網域擁有者 AWS 的帳戶 ID 取代 *111122223333*。如果您要存取您擁有之網域中的儲存庫，則不需要包含 `--domain-owner`。如需詳細資訊，請參閱[跨帳戶網域](domain-overview.md#domain-overview-cross-account)。

   ```
   aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --region us-west-2 --query authorizationToken --output text | cargo login --registry my_registry
   ```
**注意**  
產生的授權字符有效期為 12 小時。如果自建立權杖後已經過 12 小時，您將需要建立新的權杖。

------

上述範例中的 `[registries.my_registry]`區段使用 `my_registry`和 提供 `index` 和 `credential-provider`資訊來定義登錄檔。
+ `index` 指定登錄檔的索引 URL，這是結尾為 的 CodeArtifact 儲存庫端點`/`。非 Git 儲存庫的登錄檔需要 `sparse+`字首。
**注意**  
若要使用雙堆疊端點，請使用 `codeartifact.region.on.aws`端點。
+ `credential-provider` 指定指定登錄檔的登入資料提供者。如果`credential-provider`未設定 ，`registry.global-credential-providers`則會使用 中的提供者。透過將 `credential-provider`設定為 `cargo:token-from-stdout`，Cargo 用戶端會在從 CodeArtifact 儲存庫發佈或下載時自動擷取新的授權字符，因此您不需要每 12 小時手動重新整理授權字符。

`[registry]` 區段定義使用的預設登錄檔。
+ `default` 指定在 中定義的登錄檔名稱`[registries.my_registry]`，預設在從 CodeArtifact 儲存庫發佈或下載時使用。

`[source.crates-io]` 區段定義未指定預設登錄檔時所使用的預設登錄檔。
+ `replace-with = "my_registry"` 會使用 中定義的 CodeArtifact 儲存庫來取代公有登錄檔 crates.io`[registries.my_registry]`。如果您需要從外部連線請求套件，例如 crates.io，則建議使用此組態。

  若要取得 CodeArtifact 的所有優點，例如防止相依性混淆攻擊的套件原始伺服器控制，建議您使用來源取代。使用來源取代時，CodeArtifact 會將所有請求代理至外部連線，並從外部連線複製套件至您的儲存庫。如果沒有取代來源，Cargo 用戶端會根據專案中`Cargo.toml`檔案中的組態直接擷取套件。如果相依性未標示 `registry=my_registry`，則 Cargo 用戶端會直接從 crates.io 擷取相依性，而不與您的 CodeArtifact 儲存庫通訊。
**注意**  
如果您開始使用來源替換，然後更新您的組態檔案以不使用來源替換，您可能會遇到錯誤。相反的情況也可能導致錯誤。因此，建議您避免變更專案的組態。

## 安裝貨運箱
安裝貨運箱

使用下列程序從 CodeArtifact 儲存庫或 [crates.io](https://crates.io/) 安裝貨運箱。

### 從 CodeArtifact 安裝貨運箱


您可以使用貨運 (`cargo`) CLI，從 CodeArtifact 儲存庫快速安裝特定版本的貨運箱。

**使用 從 CodeArtifact 儲存庫安裝貨運箱 `cargo`**

1. 如果您尚未執行，請依照 中的步驟[透過 CodeArtifact 設定和使用貨運](#configure-use-cargo)設定 `cargo` CLI，以使用具有適當登入資料的 CodeArtifact 儲存庫。

1. 使用下列命令從 CodeArtifact 安裝貨運箱：

   ```
   cargo add my_cargo_package@1.0.0
   ```

   如需詳細資訊，請參閱「[貨運手冊」中的貨運新增](https://doc.rust-lang.org/cargo/commands/cargo-add.html)。 **

## 將貨運箱發佈至 CodeArtifact
發佈貨運箱

使用下列程序，使用 CLI 將貨運箱發佈至 CodeArtifact `cargo` 儲存庫。

1. 如果您尚未執行，請依照 中的步驟[透過 CodeArtifact 設定和使用貨運](#configure-use-cargo)設定 `cargo` CLI，以使用具有適當登入資料的 CodeArtifact 儲存庫。

1. 使用下列命令將貨運箱發佈至 CodeArtifact 儲存庫：

   ```
   cargo publish
   ```

   如需詳細資訊，請參閱「[貨運手冊」中的貨運發佈](https://doc.rust-lang.org/cargo/commands/cargo-publish.html)。 **

# 貨運命令支援


以下各節摘要 CodeArtifact 儲存庫支援的貨運命令，以及不支援的特定命令。

**Contents**
+ [

## 需要存取登錄檔的支援命令
](#supported-commands-access-the-registry)
+ [

## 不支援的命令
](#unsupported-commands)

## 需要存取登錄檔的支援命令


本節列出 Cargo 用戶端需要存取其所設定之登錄檔的 Cargo 命令。已驗證這些命令在針對 CodeArtifact 儲存庫調用時可正常運作。


****  

| 命令 | Description | 
| --- | --- | 
|   [組建](https://doc.rust-lang.org/cargo/commands/cargo-build.html)   |  建置本機套件及其相依性。  | 
|   [檢查](https://doc.rust-lang.org/cargo/commands/cargo-check.html)   |  檢查本機套件及其相依性是否有錯誤。  | 
|   [擷取](https://doc.rust-lang.org/cargo/commands/cargo-fetch.html)   |  擷取套件的相依性。  | 
|   [發佈](https://doc.rust-lang.org/cargo/commands/cargo-publish.html)   |  將套件發佈至登錄檔。  | 

## 不支援的命令


CodeArtifact 儲存庫不支援這些 Cargo 命令。


****  

| 命令 | Description | 
| --- | --- | 
|   [擁有者](https://doc.rust-lang.org/cargo/commands/cargo-owner.html)   |  管理登錄檔上的木箱擁有者。  | 
|   [search](https://doc.rust-lang.org/cargo/commands/cargo-search.html)   |  在登錄檔中搜尋套件。  |