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

# 在 中建置 AWS CodeBuild
<a name="builds-working"></a>

組*建*代表 執行的一組動作，以根據一組輸入成品 （例如 Java 類別檔案的集合） AWS CodeBuild 建立輸出成品 （例如 JAR 檔案）。

當您執行多個建置時，適用以下規則：
+ 如果可能，建置會並行執行。並行執行的建置數量上限可能不同。如需詳細資訊，請參閱[的配額 AWS CodeBuild](limits.md)。
+ 如果組建專案已設定並行組建限制，當執行中的組建數量達到專案的並行組建限制時，組建會傳回錯誤。如需詳細資訊，請參閱[啟用並行建置限制](create-project.md#enable-concurrent-build-limit.console)。
+ 如果建置專案未設定並行建置限制，則如果執行中的建置數量達到平台和運算類型的並行建置限制，則會將建置排入佇列。佇列中建置的數量上限為並行建置限制的五倍。如需詳細資訊，請參閱[的配額 AWS CodeBuild](limits.md)。

  佇列中的建置若未在其指定的逾時值分鐘數之後開始，則會從佇列中移除。預設逾時值為八小時。執行建置時，您可以以介於五分鐘到八個小時之間的值覆寫建置佇列逾時。如需詳細資訊，請參閱[手動執行 AWS CodeBuild 組建](run-build.md)。

  我們無法預測佇列建置的開始順序。

**注意**  
您可以存取一年的組建歷史紀錄。

您可以在處理建置時，執行這些任務：

**Topics**
+ [

# 手動執行 AWS CodeBuild 組建
](run-build.md)
+ [

# 在 AWS Lambda 運算上執行組建
](lambda.md)
+ [

# 在預留容量機群上執行組建
](fleets.md)
+ [

# 批次執行組建
](batch-build.md)
+ [

# 在批次建置中執行平行測試
](parallel-test.md)
+ [

# 快取建置以改善效能
](build-caching.md)
+ [

# 在 中對組建進行偵錯 AWS CodeBuild
](debug-builds.md)
+ [

# 在 中刪除組建 AWS CodeBuild
](delete-builds.md)
+ [

# 在 中手動重試建置 AWS CodeBuild
](retry-build.md)
+ [

# 在 中自動重試建置 AWS CodeBuild
](auto-retry-build.md)
+ [

# 在 中停止建置 AWS CodeBuild
](stop-build.md)
+ [

# 在 中停止批次建置 AWS CodeBuild
](stop-batch-build.md)
+ [

# 自動觸發 AWS CodeBuild 建置
](build-triggers.md)
+ [

# 在 中檢視建置詳細資訊 AWS CodeBuild
](view-build-details.md)
+ [

# 檢視 中的組建 IDs清單 AWS CodeBuild
](view-build-list.md)
+ [

# 在 中檢視組建專案的組建 IDs 清單 AWS CodeBuild
](view-builds-for-project.md)

# 手動執行 AWS CodeBuild 組建
<a name="run-build"></a>

您可以使用 AWS CodeBuild 主控台 AWS CLI或 AWS SDKs CodeBuild 中執行組建。

**Topics**
+ [

# 使用 AWS CodeBuild 代理程式在本機執行組建
](use-codebuild-agent.md)
+ [

# 執行建置 (主控台)
](run-build-console.md)
+ [

# 執行建置 (AWS CLI)
](run-build-cli.md)
+ [

# 執行批次建置 (AWS CLI)
](run-batch-build-cli.md)
+ [

# 自動開始執行建置 (AWS CLI)
](run-build-cli-auto-start.md)
+ [

# 自動停止執行建置 (AWS CLI)
](run-build-cli-auto-stop.md)
+ [

# 執行組建AWS SDKs)
](run-build-sdks.md)

# 使用 AWS CodeBuild 代理程式在本機執行組建
<a name="use-codebuild-agent"></a>

您可以使用 AWS CodeBuild 代理程式在本機電腦上執行 CodeBuild 組建。有適用於 x86\$164 和 ARM 平台的代理程式。

您也可以訂閱，以在發佈新版本的代理程式時接收通知。

## 先決條件
<a name="use-codebuild-agent.prerequisites"></a>

開始之前，您需要執行下列動作：
+ 在您的本機電腦上安裝 Git。
+ 在本機電腦上安裝和設定 [Docker](https://www.docker.com/)。

## 設定建置映像
<a name="use-codebuild-agent.setup-image"></a>

您只需要在第一次執行代理程式或映像變更時設定建置映像。

**設定建置映像**

1. 如果您想要使用精選的 Amazon Linux 2 映像，您可以使用下列命令，從位於 https：//[https://gallery.ecr.aws/codebuild/amazonlinux-x86\$164-standard](https://gallery.ecr.aws/codebuild/amazonlinux-x86_64-standard) 的 CodeBuild 公有 Amazon ECR 儲存庫中提取映像：

   ```
   $ docker pull public.ecr.aws/codebuild/amazonlinux-x86_64-standard:4.0
   ```

   或者，如果您想要使用另一個 Linux 映像，請執行下列步驟：

   1. 複製 CodeBuild 映像儲存庫：

      ```
      $ git clone https://github.com/aws/aws-codebuild-docker-images.git
      ```

   1. 變更為映像目錄。在此範例中，請使用 `aws/codebuild/standard:5.0`映像：

      ```
      $ cd aws-codebuild-docker-images/ubuntu/standard/5.0
      ```

   1. 建置映像。這將需要數分鐘的時間。

      ```
      $ docker build -t aws/codebuild/standard:5.0 .
      ```

1. 下載 CodeBuild 代理程式。

   若要下載 x86\$164 版本的代理程式，請執行下列命令：

   ```
   $ docker pull public.ecr.aws/codebuild/local-builds:latest
   ```

   若要下載代理程式的 ARM 版本，請執行下列命令：

   ```
   $ docker pull public.ecr.aws/codebuild/local-builds:aarch64
   ```

1. <a name="codebuild-agent-sha"></a>CodeBuild 代理程式可從 https：//[https://gallery.ecr.aws/codebuild/local-builds](https://gallery.ecr.aws/codebuild/local-builds) 取得。

   x86\$164 版代理程式的安全雜湊演算法 (SHA) 簽章為：

   ```
   sha256:ccb19bdd7af94e4dc761e4c58c267e9455c28ec68d938086b4dc1cf8fe6b0940
   ```

   代理程式 ARM 版本的 SHA 簽章為：

   ```
   sha256:7d7b5d35d2ac4e062ae7ba8c662ffed15229a52d09bd0d664a7816c439679192
   ```

   您可以使用 SHA 來識別代理程式的版本。若要查看代理程式的 SHA 簽章，請執行下列命令，並在 下尋找 SHA`RepoDigests`：

   ```
   $ docker inspect public.ecr.aws/codebuild/local-builds:latest
   ```

## 執行 CodeBuild 代理程式
<a name="use-codebuild-agent.run-agent"></a>

**執行 CodeBuild 代理程式**

1. 變更至包含您建置專案來源的目錄。

1. 下載 [codebuild\$1build.sh](https://github.com/aws/aws-codebuild-docker-images/blob/master/local_builds/codebuild_build.sh) 指令碼：

   ```
   $ curl -O  https://raw.githubusercontent.com/aws/aws-codebuild-docker-images/master/local_builds/codebuild_build.sh
   $ chmod +x codebuild_build.sh
   ```

1. 執行`codebuild_build.sh`指令碼並指定您的容器映像和輸出目錄。

   若要執行 x86\$164 組建，請執行下列命令：

   ```
   $ ./codebuild_build.sh -i <container-image> -a <output directory>
   ```

   若要執行 ARM 組建，請執行下列命令：

   ```
   $ ./codebuild_build.sh -i <container-image> -a <output directory> -l public.ecr.aws/codebuild/local-builds:aarch64
   ```

   將 *<container-image>* 取代為容器映像的名稱，例如 `aws/codebuild/standard:5.0`或 `public.ecr.aws/codebuild/amazonlinux-x86_64-standard:4.0`。

   指令碼會啟動建置映像，並在目前目錄中的專案上執行建置。若要指定建置專案的位置，請將 `-s <build project directory>`選項新增至指令碼命令。

## 接收新 CodeBuild 代理程式版本的通知
<a name="receive-codebuild-agent-notifications"></a>

您可以訂閱 Amazon SNS 通知，以便在發行新版本的 AWS CodeBuild 代理程式時收到通知。

**訂閱 CodeBuild 代理程式通知**

1. 在 [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home) 開啟 Amazon SNS 主控台。

1. 在導覽列中，如果尚未選取，請將 AWS 區域變更為**美國東部 （維吉尼亞北部）**。您必須選取此 AWS 區域，因為您訂閱的 Amazon SNS 通知會在此區域中建立。

1. 在導覽窗格中，選擇**訂閱**。

1. 選擇**建立訂閱**。

1. 在**建立訂閱**中，執行下列動作：

   1. 對於 **Topic ARN** (主題 ARN)，請使用下列 Amazon Resource Name (ARN)：

      ```
      arn:aws:sns:us-east-1:850632864840:AWS-CodeBuild-Local-Agent-Updates
      ```

   1. 針對**通訊協定**，選擇**電子郵件** 或**簡訊**。

   1. 針對 **Endpoint (端點)**，選擇要接收通知的位置 (電子郵件或簡訊)。輸入電子郵件或地址或電話號碼，包括區碼。

   1. 選擇**建立訂閱**。

   1. 選擇**電子郵件**以接收要求您確認訂閱的電子郵件。遵循電子郵件中的指示來完成訂閱。

      如果您不想再接收這些通知，請使用下列程序來取消訂閱。

**取消訂閱 CodeBuild 代理程式通知**

1. 在 [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home) 開啟 Amazon SNS 主控台。

1. 在導覽窗格中，選擇**訂閱**。

1. 選取訂閱，然後從 **Actions (動作)**，選擇 **Delete subscriptions (刪除訂閱)**。出現確認提示時，選擇 **Delete (刪除)**。

# 執行建置 (主控台)
<a name="run-build-console"></a>

若要使用 AWS CodePipeline 搭配 CodeBuild 執行組建，請略過這些步驟並遵循 中的指示[搭配 CodePipeline 使用 CodeBuild CodePipeline](how-to-create-pipeline.md)。

1. 開啟 AWS CodeBuild 主控台，網址為 [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)：//。

1. 在導覽窗格中，選擇 **Build projects (建置專案)**。

1. 在建置專案清單中，選擇建置專案。

1. 您可以使用預設建置專案設定來執行建置，或僅覆寫此建置的建置設定。

   1. 如果您想要使用預設建置專案設定執行建置，請選擇**開始建置**。組建會立即開始。

   1. 如果您想要覆寫預設建置專案設定，請選擇**使用覆寫開始建置**。在**開始建置**頁面中，您可以覆寫下列項目：
      + **組建組態**
      + **來源**
      + **環境變數覆寫**

      如果您需要選取更多進階覆寫，請選擇**進階建置覆寫**。在此頁面上，您可以覆寫下列項目：
      + **組建組態**
      + **來源**
      + **Environment (環境)** 
      + **Buildspec**
      + **成品**
      + **日誌**

      當您進行覆寫選擇時，請選擇**開始建置**。

如需此建置的詳細資訊，請參閱[檢視建置的詳細資訊 (主控台)](view-build-details.md#view-build-details-console)。

# 執行建置 (AWS CLI)
<a name="run-build-cli"></a>

**注意**  
若要使用 CodePipeline 執行組建 AWS CodeBuild，請略過這些步驟，並遵循 中的指示[建立使用 CodeBuild 的管道 (AWS CLI)](how-to-create-pipeline-cli.md)。  
如需 AWS CLI 搭配 CodeBuild 使用 的詳細資訊，請參閱 [命令列參考](cmd-ref.md)。

1. 使用下列其中一種方式，執行 `start-build` 命令：

   ```
   aws codebuild start-build --project-name <project-name>
   ```

   如果您想要執行的建置使用建置輸入成品和組建專案現有設定的最新版本，則請使用此命令。

   ```
   aws codebuild start-build --generate-cli-skeleton
   ```

   如果您想要執行的建置使用建置輸入成品的舊版本，或者想要覆寫建置輸出成品、環境變數、buildspec 或預設建置逾時期間的設定，則請使用此命令。

1. 如果您使用 `--project-name`選項執行 **start-build**命令，請將 *<project-name>* 取代為建置專案的名稱，然後跳至此程序的步驟 6。若要取得組建專案清單，請參閱[檢視組建專案名稱](view-project-list.md)。

1. 如果您使用 `--idempotency-token`選項執行 **start-build**命令，`start-build`則請求中會包含唯一的區分大小寫識別符或字符。此字符在 請求之後的 5 分鐘內有效。如果您使用相同的字符重複`start-build`請求，但變更參數，CodeBuild 會傳回參數不相符錯誤。

1. 如果您搭配執行 **start-build** 命令與 `--generate-cli-skeleton` 選項，則會在輸出中顯示 JSON 格式化資料。將資料複製到 AWS CLI 安裝 的本機電腦或執行個體位置中的檔案 （例如 `start-build.json`)。修改複製的資料以符合下列格式，並儲存您的結果：

   ```
   {
     "projectName": "projectName",
     "sourceVersion": "sourceVersion",
     "artifactsOverride": {
       "type": "type",
       "location": "location",
       "path": "path",
       "namespaceType": "namespaceType",
       "name": "artifactsOverride-name",
       "packaging": "packaging"
     },
     "buildspecOverride": "buildspecOverride",
     "cacheOverride": {
       "location": "cacheOverride-location",
       "type": "cacheOverride-type"
     },
     "certificateOverride": "certificateOverride",
     "computeTypeOverride": "computeTypeOverride",
     "environmentTypeOverride": "environmentTypeOverride",
     "environmentVariablesOverride": {
       "name": "environmentVariablesOverride-name",
       "value": "environmentVariablesValue",
       "type": "environmentVariablesOverride-type"
     },
     "gitCloneDepthOverride": "gitCloneDepthOverride",
     "imageOverride": "imageOverride",
     "idempotencyToken": "idempotencyToken",
     "insecureSslOverride": "insecureSslOverride",
     "privilegedModeOverride": "privilegedModeOverride",
     "queuedTimeoutInMinutesOverride": "queuedTimeoutInMinutesOverride",
     "reportBuildStatusOverride": "reportBuildStatusOverride",
     "timeoutInMinutesOverride": "timeoutInMinutesOverride",
     "sourceAuthOverride": "sourceAuthOverride",
     "sourceLocationOverride": "sourceLocationOverride",
     "serviceRoleOverride": "serviceRoleOverride",
     "sourceTypeOverride": "sourceTypeOverride"
   }
   ```

   取代下列預留位置：
   + *projectName*：必要字串。用於此建置的組建專案名稱。
   + *sourceVersion*：選用字串。要建置的來源碼版本，如下所示：
     + 對於 Amazon S3，對應至您要建置之輸入 ZIP 檔案版本的版本 ID。如果未指定 *sourceVersion*，則會使用最新版本。
     + 對於 CodeCommit，對應至您要建置之來源碼版本的遞交 ID。如果未指定 *sourceVersion*，則會使用預設分支的 HEAD 遞交 ID。(您無法指定 *sourceVersion* 的標籤名稱，但可以指定標籤的遞交 ID)。
     + 針對 GitHub，為遞交 ID、提取請求 ID、分支名稱，或與您想要建置之來源碼版本對應的標籤名稱。如果指定提取請求 ID，其格式必須為 `pr/pull-request-ID` (例如，`pr/25`)。如果指定分支名稱，則會使用分支的 HEAD 遞交 ID。如果未指定 *sourceVersion*，則會使用預設分支的 HEAD 遞交 ID。
     + 針對 Bitbucket，為遞交 ID、分支名稱，或與您想要建置之來源碼版本對應的標籤名稱。如果指定分支名稱，則會使用分支的 HEAD 遞交 ID。如果未指定 *sourceVersion*，則會使用預設分支的 HEAD 遞交 ID。
   + 下列是 `artifactsOverride` 的預留位置。
     + *type*：選用。此建置的建置輸出成品類型，可覆寫組建專案中所定義的建置輸出成品類型。
     + *location*：選用。此建置的建置輸出成品位置，可覆寫組建專案中所定義的建置輸出成品位置。
     + *路徑*：選用。此建置的建置輸出成品路徑，可覆寫組建專案中所定義的建置輸出成品路徑。
     + *namespaceType*：選用。此建置的建置輸出成品路徑類型，可覆寫組建專案中所定義的建置輸出成品路徑類型。
     + *name*：選用。此建置的建置輸出成品名稱，可覆寫組建專案中所定義的建置輸出成品名稱。
     + *封裝*：選用。此建置的建置輸出成品封裝類型，可覆寫組建專案中所定義的建置輸出成品封裝類型。
   + *buildspecOverride*：選用。此建置的 Buildspec 宣告，可覆寫建置專案中所定義的 Buildspec 宣告。如果已設定此值，它可以是內嵌 buildspec 定義，或相對於內建 `CODEBUILD_SRC_DIR` 環境變數值之替代 buildspec 檔案的路徑，或 S3 儲存貯體的路徑。S3 儲存貯體必須位於與建置專案相同的 AWS 區域。使用其 ARN 指定 buildspec 檔案 (例如，`arn:aws:s3:::<my-codebuild-sample2>/buildspec.yml`)。如果此值未提供，或設定為空字串，則來源碼必須包含其根目錄中的 `buildspec.yml` 檔案。如需詳細資訊，請參閱[Buildspec 檔案名稱和儲存位置](build-spec-ref.md#build-spec-ref-name-storage)。
   + 下列是 `cacheOverride` 的預留位置。
     + *cacheOverride-location*：選用。此建置的 `ProjectCache` 物件位置，可覆寫組建專案中所指定的 `ProjectCache` 物件。`cacheOverride` 是選用項目，並採用 `ProjectCache` 物件。`ProjectCache` 物件中需要 `location`。
     + *cacheOverride-type*：選用。此建置的 `ProjectCache` 物件類型，可覆寫組建專案中所指定的 `ProjectCache` 物件。`cacheOverride` 是選用項目，並採用 `ProjectCache` 物件。`ProjectCache` 物件中需要 `type`。
   + *certificateOverride*：選用。此建置的憑證名稱，可覆寫組建專案中所指定的憑證名稱。
   + *environmentTypeOverride*：選用。此建置的容器名稱，可覆寫組建專案中所指定的容器名稱。目前有效字串為 `LINUX_CONTAINER`。
   + 下列是 `environmentVariablesOverride` 的預留位置。
     + *environmentVariablesOverride-name*：選用。您想要針對此建置覆寫其值之組建專案中的環境變數名稱。
     + *environmentVariablesOverride-type*：選用。您想要針對此建置覆寫其值之組建專案中的環境變數類型。
     + *environmentVariablesValue*：選用。您想要針對此建置覆寫組建專案中所定義的環境變數值。
   + *gitCloneDepthOverride*：選用。您想要針對此建置覆寫其值之組建專案中的 **Git clone depth (Git 複製深度)** 值。如果您的來源類型是 Amazon S3，則不支援此值。
   + *imageOverride*：選用。此建置的映像名稱，可覆寫組建專案中所指定的映像名稱。
   + *idempotencyToken*：選用。字串，可做為指定建置請求為等冪的字符。您可以選擇長度為 64 個或更少字元的任何字串。字符在 start-build 請求後 5 分鐘內有效。如果您使用相同的字符重複 start-build 請求，但變更參數，CodeBuild 會傳回參數不相符錯誤。
   + *insecureSslOverride*：選用布林值，指定是否覆寫建置專案中所指定的不安全 TLS 設定。不安全 TLS 設定決定是否忽略連線至專案來源碼時的 TLS 警告。只有在建置的來源是 GitHub Enterprise Server 時，才會套用此覆寫。
   + *privilegedModeOverride*：選用布林值。如果設定為 true，則建置會覆寫建置專案中的特殊權限模式。
   +  *queuedTimeoutInMinutesOverride*：選用整數，指定在建置逾時之前，允許將建置排入佇列的分鐘數。其最小值為五分鐘，其最大值為 480 分鐘 (八小時)。
   + *reportBuildStatusOverride*：選用布林值，指定是否將建置的啟動和完成狀態傳送給您的來源提供者。如果您搭配 GitHub、GitHub Enterprise Server 或 Bitbucket 以外的來源供應商設定此項，則會擲出 invalidInputException。
   + *sourceAuthOverride*：選用字串。此建置的授權類型，可覆寫組建專案中所定義的授權類型。只有在建置專案的來源是 Bitbucket 或 GitHub 時，才會套用此覆寫。
   + *sourceLocationOverride*：選用字串。此建置的位置，可覆寫組建專案中所定義位置的來源位置。
   + *serviceRoleOverride*：選用字串。此建置的服務角色名稱，可覆寫組建專案中所指定的服務角色名稱。
   + *sourceTypeOverride*：選用字串。此建置的來源輸入類型，可覆寫組建專案中所定義的來源輸入。有效字串為 `NO_SOURCE`、`CODECOMMIT`、`CODEPIPELINE`、`GITHUB`、`S3`、`BITBUCKET` 和 `GITHUB_ENTERPRISE`。
   + *timeoutInMinutesOverride*：選用數字。此建置的建置逾時分鐘數目，可覆寫組建專案中所定義的建置逾時分鐘數目。

   建議您存放具有敏感值的環境變數，例如 AWS 存取金鑰 ID、 AWS 私密存取金鑰或密碼，做為 Amazon EC2 Systems Manager 參數存放區中的參數。CodeBuild 只能在 參數的名稱開頭為 `/CodeBuild/`（例如 ) 時，使用存放在 Amazon EC2 Systems Manager 參數存放區中的參數`/CodeBuild/dockerLoginPassword`。您可以使用 CodeBuild 主控台在 Amazon EC2 Systems Manager 中建立參數。選擇 **Create a parameter (建立參數)**，然後遵循指示進行。（在該對話方塊中，對於 **KMS 金鑰**，您可以選擇指定帳戶中金鑰 AWS KMS 的 ARN。 Amazon EC2 Systems Manager 會使用此金鑰在儲存期間加密參數的值，並在擷取期間解密。) 如果您使用 CodeBuild 主控台來建立參數，則主控台會在儲存參數`/CodeBuild/`時以 啟動參數。不過，如果您使用 Amazon EC2 Systems Manager 參數存放區主控台來建立參數，您必須使用 啟動參數的名稱`/CodeBuild/`，而且必須將 **Type** 設定為 **Secure String**。如需詳細資訊，請參閱《*Amazon EC2 Systems Manager 使用者指南*》中的[AWS Systems Manager 參數存放](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)區和[演練：建立和測試字串參數 （主控台）](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-console.html)。

   如果您的建置專案參考存放在 Amazon EC2 Systems Manager 參數存放區的參數，則建置專案的服務角色必須允許 `ssm:GetParameters`動作。如果您先前**在帳戶中選擇建立新的服務角色**，則 CodeBuild 會自動在建置專案的預設服務角色中包含此動作。不過，如果您選擇 **Choose an existing service role from your account (從您的帳戶中選擇現有服務角色)**，則必須將此動作單獨包含在服務角色中。

   您設定的環境變數會取代現有環境變數。例如，如果 Docker 影像已包含名為 `MY_VAR` 且值為 `my_value` 的環境變數，而且您設定名為 `MY_VAR` 且值為 `other_value` 的環境變數，則 `my_value` 會取代為 `other_value`。同樣地，如果 Docker 影像已包含名為 `PATH` 且值為 `/usr/local/sbin:/usr/local/bin` 的環境變數，而且您設定名為 `PATH` 且值為 `$PATH:/usr/share/ant/bin` 的環境變數，則 `/usr/local/sbin:/usr/local/bin` 會取代為文字值 `$PATH:/usr/share/ant/bin`。

   請不要設定名稱開頭為 `CODEBUILD_` 的任何環境變數。此字首保留供 內部使用。

   如果有多個位置定義同名的環境變數，則會決定環境變數的值，如下所示：
   + 開始建置操作呼叫中的值會採用最高優先順序。
   + 組建專案定義中的值會採用下一個優先順序。
   + buildspec 檔案宣告中的值會採用最低優先順序。

   如需這些預留位置有效值的資訊，請參閱[建立建置專案 (AWS CLI)](create-project.md#create-project-cli)。如需組建專案的最新設定清單，請參閱[檢視組建專案詳細資訊](view-project-details.md)。

1. 切換到包含您剛儲存之檔案的目錄，然後再次執行 `start-build` 命令。

   ```
   aws codebuild start-build --cli-input-json file://start-build.json
   ```

1. 如果成功，則會在輸出中顯示[執行建置](getting-started-overview.md#getting-started-run-build-cli) 程序中所述資料類似的資料。

若要使用此建置的詳細資訊，請記下輸出中的 `id` 值，然後參閱[檢視建置的詳細資訊 (AWS CLI)](view-build-details.md#view-build-details-cli)。

# 執行批次建置 (AWS CLI)
<a name="run-batch-build-cli"></a>

1. 使用下列其中一種方式，執行 `start-build-batch` 命令：

   ```
   aws codebuild start-build-batch --project-name <project-name>
   ```

   如果您想要執行的建置使用建置輸入成品和組建專案現有設定的最新版本，則請使用此命令。

   ```
   aws codebuild start-build-batch --generate-cli-skeleton > <json-file>
   ```

   如果您想要執行的建置使用建置輸入成品的舊版本，或者想要覆寫建置輸出成品、環境變數、buildspec 或預設建置逾時期間的設定，則請使用此命令。

1. 如果您使用 `--project-name`選項執行 **start-build-batch**命令，請將 *<project-name>* 取代為建置專案的名稱，然後跳至此程序的步驟 6。若要取得組建專案清單，請參閱[檢視組建專案名稱](view-project-list.md)。

1. 如果您使用 `--idempotency-token`選項執行 **start-build-batch**命令，`start-build-batch`則請求中會包含唯一區分大小寫的識別符或字符。此字符在 請求之後的 5 分鐘內有效。如果您使用相同的字符重複`start-build-batch`請求，但變更參數，CodeBuild 會傳回參數不相符錯誤。

1. 如果您使用 `--generate-cli-skeleton`選項執行 **start-build-batch**命令，JSON 格式的資料會輸出到 *<json-file>* 檔案。此檔案類似於 **start-build**命令產生的骨架，並新增下列物件。如需常見物件的詳細資訊，請參閱 [執行建置 (AWS CLI)](run-build-cli.md)。

   修改此檔案以新增任何組建覆寫，並儲存結果。

   ```
     "buildBatchConfigOverride": {
       "combineArtifacts": combineArtifacts,
       "restrictions": {
         "computeTypesAllowed": [
           allowedComputeTypes
         ],
         "maximumBuildsAllowed": maximumBuildsAllowed
       },
       "serviceRole": "batchServiceRole",
       "timeoutInMins": batchTimeout
     }
   ```

   `buildBatchConfigOverride` 物件是 [ProjectBuildBatchConfig](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectBuildBatchConfig.html) 結構，其中包含此建置的批次建置組態覆寫。  
*combineArtifacts*  
布林值，指定是否應將批次組建的組建成品合併為單一成品位置。  
*allowedComputeTypes*  
字串陣列，指定批次建置允許的運算類型。如需這些值，請參閱[建置環境運算類型](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html)。  
*maximumBuildsAllowed*  
指定允許的建置數目上限。  
*batchServiceRole*  
指定批次建置專案的服務角色 ARN。  
*batchTimeout*  
指定批次建置必須完成的時間上限 (以分鐘為單位)。

1. 切換到包含您剛儲存之檔案的目錄，然後再次執行 `start-build-batch` 命令。

   ```
   aws codebuild start-build-batch --cli-input-json file://start-build.json
   ```

1. 如果成功，則 [BuildBatch](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_BuildBatch.html) 物件的 JSON 表示法會出現在主控台輸出中。如需此資料的範例，請參閱 [StartBuildBatch 回應語法](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_StartBuildBatch.html#API_StartBuildBatch_ResponseSyntax)。

# 自動開始執行建置 (AWS CLI)
<a name="run-build-cli-auto-start"></a>

如果您的原始碼存放在 GitHub 或 GitHub Enterprise Server 儲存庫中，則只要將程式碼變更推送至儲存庫，您就可以使用 GitHub Webhook AWS CodeBuild 來重建原始碼。

執行 **create-webhook** 命令，如下所示：

```
aws codebuild create-webhook --project-name <project-name>
```

*<project-name>* 是包含要重建之原始碼的建置專案名稱。

針對 GitHub，則會在輸出中顯示與下列內容類似的資訊：

```
{
  "webhook": {
    "url": "<url>"
  }
}
```

*<url>* 是 GitHub Webhook 的 URL。

針對 GitHub Enterprise Server，則會在輸出中顯示與下列內容類似的資訊：

![\[輸出資訊範例。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/create-webhook-ghe.png)


1. 複製輸出中的秘密金鑰和有效負載 URL。您需要它們，才能在 GitHub Enterprise Server 中新增 Webhook。

1. 在 GitHub Enterprise Server 中，選擇儲存 CodeBuild 專案的儲存庫。依序選擇 **Settings (設定)**、**Hooks & services (關聯和服務)** 和 **Add webhook (新增 Webhook)**。

1. 輸入有效負載 URL 和秘密金鑰，並接受其他欄位的預設值，然後選擇 **Add webhook (新增 Webhook)**。

# 自動停止執行建置 (AWS CLI)
<a name="run-build-cli-auto-stop"></a>

如果您的原始碼存放在 GitHub 或 GitHub Enterprise Server 儲存庫中，您可以設定 GitHub Webhook，以便在將程式碼變更推送至儲存庫時 AWS CodeBuild 重建原始碼。如需詳細資訊，請參閱[自動開始執行建置 (AWS CLI)](run-build-cli-auto-start.md)。

如果您已啟用此行為，則可以執行 `delete-webhook` 命令予以關閉，如下所示：

```
aws codebuild delete-webhook --project-name <project-name>
```
+ 其中 *<project-name>* 是包含要重建之原始碼的建置專案名稱。

如果此命令成功，則輸入中不會顯示任何資訊和錯誤。

**注意**  
這只會從您的 CodeBuild 專案中刪除 Webhook。您也應該刪除 GitHub 或 GitHub Enterprise Server 儲存庫中的 Webhook。

# 執行組建AWS SDKs)
<a name="run-build-sdks"></a>

若要使用 CodePipeline 執行組建 AWS CodeBuild，請略過這些步驟，並[使用 AWS CodeBuild 搭配 AWS CodePipeline 來測試程式碼和執行組建](how-to-create-pipeline.md)改為遵循 中的指示。

如需搭配 AWS SDKs 使用 CodeBuild 的詳細資訊，請參閱 [AWS SDKs和工具參考](sdk-ref.md)。

# 在 AWS Lambda 運算上執行組建
<a name="lambda"></a>

AWS Lambda 運算為您的組建提供最佳化的啟動速度。 AWS Lambda 支援更快的組建，因為啟動延遲較低。 AWS Lambda 也會自動擴展，因此組建不會在佇列中等待執行。不過，有些使用案例 AWS Lambda 不支援，如果它們會影響您，請使用 EC2 運算。如需詳細資訊，請參閱[AWS Lambda 運算的限制](#lambda.limitations)。

**Topics**
+ [

## 在 上執行的精選執行時間環境Docker 映像中，會包含哪些工具和執行時間 AWS Lambda？
](#lambda.tools)
+ [

## 如果策劃的映像不包含我需要的工具，該怎麼辦？
](#lambda.custom)
+ [

## 哪些區域支援 CodeBuild 中的 AWS Lambda 運算？
](#lambda.regions)
+ [

## AWS Lambda 運算的限制
](#lambda.limitations)
+ [

# 使用 AWS SAM 搭配 CodeBuild Lambda Java 部署 Lambda 函數
](sample-lambda-sam-gradle.md)
+ [

# 使用 CodeBuild Lambda Node.js 建立單一頁面 React 應用程式
](sample-lambda-react-nodejs.md)
+ [

# 使用 CodeBuild Lambda Python 更新 Lambda 函數組態
](sample-lambda-boto3-python.md)

## 在 上執行的精選執行時間環境Docker 映像中，會包含哪些工具和執行時間 AWS Lambda？
<a name="lambda.tools"></a>

AWS Lambda 支援下列工具： AWS CLI v2、 AWS SAM CLI、git、go、Java、Node.js、Python、pip、Ruby 和 .NET。

## 如果策劃的映像不包含我需要的工具，該怎麼辦？
<a name="lambda.custom"></a>

如果策劃的映像不包含您需要的工具，您可以提供包含必要工具的自訂環境 Docker 映像。

**注意**  
Lambda 不支援使用多架構容器映像的函數。如需詳細資訊，請參閱《 *AWS Lambda 開發人員指南*》中的[使用容器映像建立 Lambda 函數](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html#images-reqs)。

請注意，您需要下列 Amazon ECR 許可，才能使用自訂映像進行 Lambda 運算：

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecr:GetAuthorizationToken"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ecr:BatchCheckLayerAvailability",
                "ecr:GetDownloadUrlForLayer",
                "ecr:BatchGetImage"
            ],
            "Resource": "arn:aws:ecr:us-east-1:111122223333:repository/image-repo"
        }
    ]
}
```

------

另請注意，`wget`必須安裝 `curl`或 才能使用自訂映像。

## 哪些區域支援 CodeBuild 中的 AWS Lambda 運算？
<a name="lambda.regions"></a>

在 CodeBuild 中，以下支援 AWS Lambda 運算 AWS 區域：美國東部 （維吉尼亞北部）、美國東部 （俄亥俄）、美國西部 （奧勒岡）、亞太區域 （孟買）、亞太區域 （新加坡）、亞太區域 （雪梨）、亞太區域 （東京）、歐洲 （法蘭克福）、歐洲 （愛爾蘭） 和南美洲 （聖保羅）。如需 CodeBuild 可用位置的詳細資訊 AWS 區域 ，請參閱[AWS 依區域的服務](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。

## AWS Lambda 運算的限制
<a name="lambda.limitations"></a>

有些使用案例 AWS Lambda 不支援，如果它們影響到您，請使用 EC2 運算：
+ AWS Lambda 不支援需要根許可的工具。對於 `yum`或 等工具`rpm`，請使用 EC2 運算類型或其他不需要根許可的工具。
+ AWS Lambda 不支援 Docker 組建或執行。
+ AWS Lambda 不支援寫入 外部的檔案`/tmp`。包含的套件管理員預設會設定為使用 `/tmp`目錄來下載和參考套件。
+ AWS Lambda 不支援 環境類型，`LINUX_GPU_CONTAINER`Windows Server Core 2019 也不支援。
+ AWS Lambda 不支援快取、自訂建置逾時、佇列逾時、建置徽章、特殊權限模式、自訂執行時間環境或超過 15 分鐘的執行時間。
+ AWS Lambda 不支援使用 Session Manager 進行 VPC 連線、固定範圍的 CodeBuild 來源 IP 地址、EFS、安裝憑證或 SSH 存取。

# 使用 AWS SAM 搭配 CodeBuild Lambda Java 部署 Lambda 函數
<a name="sample-lambda-sam-gradle"></a>

 AWS Serverless Application Model (AWS SAM) 是用於建置無伺服器應用程式的開放原始碼架構。如需詳細資訊，請參閱 GitHub 上的儲存[AWS Serverless Application Model 庫](https://github.com/aws/serverless-application-model)。下列 Java 範例使用 Gradle 來建置和測試 AWS Lambda 函數。之後，會使用 AWS SAM CLI 來部署 CloudFormation 範本和部署套件。透過使用 CodeBuild Lambda，系統會自動處理建置、測試和部署步驟，以便快速更新基礎設施，而無需在單一建置中手動介入。

## 設定您的 AWS SAM 儲存庫
<a name="sample-lambda-sam-gradle.set-up-repo"></a>

使用 CLI AWS SAM 建立 AWS SAM `Hello World`專案。

**建立您的 AWS SAM 專案**

1. 請遵循在本機電腦上[安裝 CLI AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html)的 *AWS Serverless Application Model 開發人員指南*中的指示。

1. 執行`sam init`並選取下列專案組態。

   ```
   Which template source would you like to use?: 1 - AWS Quick Start Templates
   Choose an AWS Quick Start application template: 1 - Hello World Example
   Use the most popular runtime and package type? (Python and zip) [y/N]: N
   Which runtime would you like to use?: 8 - java21
   What package type would you like to use?: 1 - Zip
   Which dependency manager would you like to use?: 1 - gradle
   Would you like to enable X-Ray tracing on the function(s) in your application? [y/N]: N
   Would you like to enable monitoring using CloudWatch Application Insights? [y/N]: N
   Would you like to set Structured Logging in JSON format on your Lambda functions? [y/N]:  N
   Project name [sam-app]: <insert project name>
   ```

1. 將 AWS SAM 專案資料夾上傳至支援的來源儲存庫。如需支援的來源類型清單，請參閱 [ProjectSource](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html)。

## 建立 CodeBuild Lambda Java 專案
<a name="sample-lambda-sam-gradle.create-project"></a>

建立 AWS CodeBuild Lambda Java 專案並設定建置所需的 IAM 許可。

**建立 CodeBuild Lambda Java 專案**

1. 在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1.  如果顯示 CodeBuild 資訊頁面，請選擇**建立組建專案**。否則，請在導覽窗格中展開**組**建，選擇**組建專案**，然後選擇**建立組建專案**。

1. 在 **Project name (專案名稱)** 中，輸入此建置專案的名稱。組建專案名稱在每個 AWS 帳戶中必須是唯一的。您也可以包含建置專案的選用描述，以協助其他使用者了解此專案的用途。

1. 在**來源**中，選取 AWS SAM 專案所在的來源儲存庫。

1. 在 **Environment (環境)** 中：
   + 針對**運算**，選取 **Lambda**。
   + 針對 **Runtime(s)**，選取 **Java**。
   + 針對**影像**，選取 **aws/codebuild/amazonlinux-x86\$164-lambda-standard：corretto21**。
   + 對於**服務角色**，保留選取**新的服務角色**。記下**角色名稱**。當您稍後在此範例中更新專案的 IAM 許可時，這是必要的。

1. 選擇 **Create build project (建立建置專案)**。

1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。

1. 在導覽窗格中，選擇**角色**，然後選取與您的專案相關聯的服務角色。您可以透過選取建置專案、選擇**編輯**、**環境，然後選擇服務角色**，在 CodeBuild 中尋找專案角色。 ****

1. 選擇 **Trust Relationships** (信任關係) 標籤，然後選擇 **Edit Trust Relationship** (編輯信任政策)。

1. 將下列內嵌政策新增至您的 IAM 角色。這將用於稍後部署您的 AWS SAM 基礎設施。如需詳細資訊，請參閱《 IAM 使用者指南》**中的[新增和移除 IAM 身分許可](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Sid": "",
               "Effect": "Allow",
               "Action": [
                   "cloudformation:*",
                   "lambda:*",
                   "iam:*",
                   "apigateway:*",
                   "s3:*"
               ],
               "Resource": "arn:aws:iam::*:role/Service*"
           }
       ]
   }
   ```

------

## 設定專案 buildspec
<a name="sample-lambda-sam-gradle.set-up-buildspec"></a>

為了建置、測試和部署 Lambda 函數，CodeBuild 會從 buildspec 讀取和執行建置命令。

**設定您的專案 buildspec**

1. 在 CodeBuild 主控台中，選取您的建置專案，然後選擇**編輯**和**建置規格**。

1. 在 **Buildspec** 中，選擇**插入建置命令**，然後**切換到編輯器**。

1. 刪除預先填入的建置命令，並貼到下列 buildspec 中。

   ```
   version: 0.2
   env:
     variables:
       GRADLE_DIR: "HelloWorldFunction"
   phases:
     build:
       commands:
         - echo "Running unit tests..."
         - cd $GRADLE_DIR; gradle test; cd ..
         - echo "Running build..."
         - sam build --template-file template.yaml
         - echo "Running deploy..."
         - sam package --output-template-file packaged.yaml --resolve-s3 --template-file template.yaml
         - yes | sam deploy
   ```

1. 選擇 **Update buildspec (更新 buildspec)**。

## 部署您的 AWS SAM Lambda 基礎設施
<a name="sample-lambda-sam-gradle.deploy"></a>

使用 CodeBuild Lambda 自動部署 Lambda 基礎設施

**部署 Lambda 基礎設施**

1. 選擇 **Start build (開始組建)**。這會自動建置、測試和部署您的 AWS SAM 應用程式以 AWS Lambda 使用 CloudFormation。

1. 建置完成後，導覽至 AWS Lambda 主控台，並在 AWS SAM 專案名稱下搜尋新的 Lambda 函數。

1. 在函數概觀下選取 **API Gateway**，然後按一下 **API 端點** URL，以測試您的 Lambda **函數**。您應該會看到開啟的頁面，其中包含訊息 `"message": "hello world"`。

## 清除您的基礎設施
<a name="sample-lambda-sam-gradle.clean-up"></a>

若要避免您在本教學課程中使用的資源進一步收費，請刪除 AWS SAM 範本和 CodeBuild 建立的資源。

**清除您的基礎設施**

1. 導覽至 CloudFormation 主控台，然後選取 `aws-sam-cli-managed-default`。

1. 在 **資源**中，清空部署儲存貯體 `SamCliSourceBucket`。

1. 刪除`aws-sam-cli-managed-default`堆疊。

1. 刪除與您的 AWS SAM 專案相關聯的 CloudFormation 堆疊。此堆疊應與 AWS SAM 專案具有相同的名稱。

1. 導覽至 CloudWatch 主控台，並刪除與 CodeBuild 專案相關聯的 CloudWatch 日誌群組。

1. 導覽至 CodeBuild 主控台，然後選擇刪除組建專案來刪除您的 CodeBuild 專案。 ****

# 使用 CodeBuild Lambda Node.js 建立單一頁面 React 應用程式
<a name="sample-lambda-react-nodejs"></a>

[Create React 應用程式](https://create-react-app.dev/)是建立單頁 React 應用程式的一種方式。下列 Node.js 範例使用 Node.js 來建置來自 Create React 應用程式的來源成品，並傳回建置成品。

## 設定來源儲存庫和成品儲存貯體
<a name="sample-lambda-react-nodejs.set-up-repo"></a>

使用 yarn 和 Create React 應用程式為您的專案建立來源儲存庫。

**設定來源儲存庫和成品儲存貯體**

1. 在本機電腦上，執行 `yarn create react-app <app-name>` 以建立簡單的 React 應用程式。

1. 將 React 應用程式專案資料夾上傳至支援的來源儲存庫。如需支援的來源類型清單，請參閱 [ProjectSource](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html)。

## 建立 CodeBuild Lambda Node.js 專案
<a name="sample-lambda-react-nodejs.create-project"></a>

建立 AWS CodeBuild Lambda Node.js 專案。

**建立 CodeBuild Lambda Node.js 專案**

1. 開啟 AWS CodeBuild 主控台，網址為 [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)：//。

1.  如果顯示 CodeBuild 資訊頁面，請選擇**建立組建專案**。否則，在導覽窗格中，展開**組**建，選擇**組建專案**，然後選擇**建立組建專案**。

1. 在 **Project name (專案名稱)** 中，輸入此建置專案的名稱。組建專案名稱在每個 AWS 帳戶中必須是唯一的。您也可以包含建置專案的選用描述，以協助其他使用者了解此專案的用途。

1. 在**來源**中，選取 AWS SAM 專案所在的來源儲存庫。

1. 在 **Environment (環境)** 中：
   + 針對**運算**，選取 **Lambda**。
   + 對於**執行期 (Runtime)**，選取 **Node.js**。
   + 針對**影像**，選取 **aws/codebuild/amazonlinux-x86\$164-lambda-standard：nodejs20**。

1. 在 **Artifacts (成品)** 中：
   + 針對**類型**，選取 **Amazon S3**。
   + 針對**儲存貯體名稱**，選取您先前建立的專案成品儲存貯體。
   + 針對**成品封裝**，選取 **Zip**。

1. 選擇 **Create build project (建立建置專案)**。

## 設定專案 buildspec
<a name="sample-lambda-react-nodejs.set-up-buildspec"></a>

為了建置您的 React 應用程式，CodeBuild 會從 buildspec 檔案讀取並執行建置命令。

**設定您的專案 buildspec**

1. 在 CodeBuild 主控台中，選取您的建置專案，然後選擇**編輯**和 **Buildspec**。

1. 在 **Buildspec** 中，選擇**插入建置命令**，然後選擇**切換到編輯器**。

1. 刪除預先填入的建置命令，並貼到下列 buildspec 中。

   ```
   version: 0.2
   phases:
     build:
       commands:
         - yarn
         - yarn add --dev jest-junit @babel/plugin-proposal-private-property-in-object
         - yarn run build
         - yarn run test -- --coverage --watchAll=false --testResultsProcessor="jest-junit" --detectOpenHandles
   artifacts:
     name: "build-output"
     files:
       - "**/*"
   reports:
     test-report:
       files:
         - 'junit.xml'
       file-format: 'JUNITXML'
     coverage-report:
       files:
         - 'coverage/clover.xml'
       file-format: 'CLOVERXML'
   ```

1. 選擇 **Update buildspec (更新 buildspec)**。

## 建置並執行您的 React 應用程式
<a name="sample-lambda-react-nodejs.build"></a>

在 CodeBuild Lambda 上建置 React 應用程式、下載建置成品，並在本機執行 React 應用程式。

**建置和執行您的 React 應用程式**

1. 選擇 **Start build (開始組建)**。

1. 建置完成後，導覽至 Amazon S3 專案成品儲存貯體並下載 React 應用程式成品。

1. 解壓縮專案資料夾中的 React 建置成品 和 `run npm install -g serve && serve -s build` 。

1. `serve` 命令將在本機連接埠上提供靜態網站，並將輸出列印至您的終端機。您可以在終端機輸出`Local:`中造訪 下的 localhost URL，以檢視您的 React 應用程式。

若要進一步了解如何處理以 React 為基礎的伺服器的部署，請參閱[建立 React 應用程式部署](https://create-react-app.dev/docs/deployment/)。

## 清除您的基礎設施
<a name="sample-lambda-react-nodejs.clean-up"></a>

若要避免您在本教學課程中使用的資源產生進一步費用，請刪除為 CodeBuild 專案建立的資源。

**清除您的基礎設施**

1. 刪除專案成品 Amazon S3 儲存貯體

1. 導覽至 CloudWatch 主控台，並刪除與 CodeBuild 專案相關聯的 CloudWatch 日誌群組。

1. 導覽至 CodeBuild 主控台，然後選擇刪除組建專案來刪除您的 CodeBuild 專案。 ****

# 使用 CodeBuild Lambda Python 更新 Lambda 函數組態
<a name="sample-lambda-boto3-python"></a>

下列 Python 範例使用 [Boto3](https://aws.amazon.com/sdk-for-python/) 和 CodeBuild Lambda Python 來更新 Lambda 函數的組態。您可以延伸此範例，以程式設計方式管理其他 AWS 資源。如需詳細資訊，請參閱 [Boto3 文件](https://aws.amazon.com/sdk-for-python/)。

## 先決條件
<a name="sample-lambda-boto3-python.prerequisites"></a>

在您的帳戶中建立或尋找 Lambda 函數。

此範例假設您已在帳戶中建立 Lambda 函數，並將使用 CodeBuild 更新 Lambda 函數的環境變數。如需透過 CodeBuild 設定 Lambda 函數的詳細資訊，請參閱[使用 AWS SAM 搭配 CodeBuild Lambda Java 部署 Lambda 函數](sample-lambda-sam-gradle.md)範例或造訪 [AWS Lambda](https://aws.amazon.com/lambda/)。

## 設定您的來源儲存庫
<a name="sample-lambda-boto3-python.set-up-repo"></a>

建立來源儲存庫以存放 Boto3 python 指令碼。

**設定來源儲存庫**

1. 將下列 python 指令碼複製到名為 的新檔案`update_lambda_environment_variables.py`。

   ```
   import boto3
   from os import environ
   
   
   def update_lambda_env_variable(lambda_client):
       lambda_function_name = environ['LAMBDA_FUNC_NAME']
       lambda_env_variable = environ['LAMBDA_ENV_VARIABLE']
       lambda_env_variable_value = environ['LAMBDA_ENV_VARIABLE_VALUE']
       print("Updating lambda function " + lambda_function_name + " environment variable "
             + lambda_env_variable + " to " + lambda_env_variable_value)
       lambda_client.update_function_configuration(
           FunctionName=lambda_function_name,
           Environment={
               'Variables': {
                   lambda_env_variable: lambda_env_variable_value
               }
           },
       )
   
   
   if __name__ == "__main__":
       region = environ['AWS_REGION']
       client = boto3.client('lambda', region)
       update_lambda_env_variable(client)
   ```

1. 將 python 檔案上傳至支援的來源儲存庫。如需支援的來源類型清單，請參閱 [ProjectSource](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html)。

## 建立 CodeBuild Lambda Python 專案
<a name="sample-lambda-boto3-python.create-project"></a>

建立 CodeBuild Lambda Python 專案。

**建立 CodeBuild Lambda Java 專案**

1. 在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1.  如果顯示 CodeBuild 資訊頁面，請選擇**建立組建專案**。否則，請在導覽窗格中展開**組**建，選擇**組建專案**，然後選擇**建立組建專案**。

1. 在 **Project name (專案名稱)** 中，輸入此建置專案的名稱。組建專案名稱在每個 AWS 帳戶中必須是唯一的。您也可以包含建置專案的選用描述，以協助其他使用者了解此專案的用途。

1. 在**來源**中，選取 AWS SAM 專案所在的來源儲存庫。

1. 在 **Environment (環境)** 中：
   + 針對**運算**，選取 **Lambda**。
   + 針對 **Runtime(s)**，選取 **Python**。
   + 針對**影像**，選取 **aws/codebuild/amazonlinux-x86\$164-lambda-standard：python3.12**。
   + 對於**服務角色**，保留選取**新的服務角色**。記下**角色名稱**。當您稍後在此範例中更新專案的 IAM 許可時，這是必要的。

1. 選擇 **Create build project (建立建置專案)**。

1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。

1. 在導覽窗格中，選擇**角色**，然後選取與您的專案相關聯的服務角色。您可以透過選取建置專案、選擇**編輯**、**環境，然後選擇服務角色**，在 CodeBuild 中尋找專案角色。 ****

1. 選擇 **Trust Relationships** (信任關係) 標籤，然後選擇 **Edit Trust Relationship** (編輯信任政策)。

1. 將下列內嵌政策新增至您的 IAM 角色。這將用於稍後部署您的 AWS SAM 基礎設施。如需詳細資訊，請參閱《 IAM 使用者指南》**中的[新增和移除 IAM 身分許可](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Sid": "UpdateLambdaPermissions",
               "Effect": "Allow",
               "Action": [
                   "lambda:UpdateFunctionConfiguration"
               ],
               "Resource": [
                   "*"
               ]
           }
       ]
   }
   ```

------

## 設定專案 buildspec
<a name="sample-lambda-boto3-python.set-up-buildspec"></a>

為了更新 Lambda 函數，指令碼會從 buildspec 讀取環境變數，以尋找 Lambda 函數的名稱、環境變數名稱和環境變數值。

**設定您的專案 buildspec**

1. 在 CodeBuild 主控台中，選取您的建置專案，然後選擇**編輯**和**建置規格**。

1. 在 **Buildspec** 中，選擇**插入建置命令**，然後**切換到編輯器**。

1. 刪除預先填入的建置命令，並貼到下列 buildspec 中。

   ```
   version: 0.2
   env:
     variables:
       LAMBDA_FUNC_NAME: "<lambda-function-name>"
       LAMBDA_ENV_VARIABLE: "FEATURE_ENABLED"
       LAMBDA_ENV_VARIABLE_VALUE: "true"
   phases:
     install:
       commands:
          - pip3 install boto3
     build:
       commands:
          - python3 update_lambda_environment_variables.py
   ```

1. 選擇 **Update buildspec (更新 buildspec)**。

## 更新您的 Lambda 組態
<a name="sample-lambda-boto3-python.update"></a>

使用 CodeBuild Lambda Python 自動更新 Lambda 函數的組態。

**更新 Lambda 函數的組態**

1. 選擇 **Start build (開始組建)**。

1. 建置完成後，導覽至 Lambda 函數。

1. 選取**組態**，然後選取**環境**變數。您應該會看到具有索引鍵 `FEATURE_ENABLED` 和值 的新環境變數`true`。

## 清除您的基礎設施
<a name="sample-lambda-boto3-python.clean-up"></a>

若要避免您在本教學課程中使用的資源進一步收費，請刪除為 CodeBuild 專案建立的資源。

**清除您的基礎設施**

1. 導覽至 CloudWatch 主控台，並刪除與 CodeBuild 專案相關聯的 CloudWatch 日誌群組。

1. 導覽至 CodeBuild 主控台，然後選擇刪除組建專案來刪除您的 CodeBuild 專案。 ****

1. 如果您為此範例建立 Lambda 函數，請選擇**動作**和**刪除函數**來清除 Lambda 函數。

## 延伸模組
<a name="sample-lambda-boto3-python.extensions"></a>

如果您想要延伸此範例以使用 AWS CodeBuild Lambda Python 管理其他 AWS 資源：
+ 更新 Python 指令碼以使用 Boto3 修改新資源。
+ 更新與 CodeBuild 專案相關聯的 IAM 角色，以取得新資源的許可。
+ 將與新資源相關聯的任何新環境變數新增至您的 buildspec。

# 在預留容量機群上執行組建
<a name="fleets"></a>

CodeBuild 提供下列運算機群：
+ 隨需機群
+ 預留容量機群

透過隨需機群，CodeBuild 為您的建置提供運算。這些機器會在建置完成時銷毀。隨需機群受到完整管理，並包含自動擴展功能，可處理需求激增。

**注意**  
隨需機群不支援 macOS。

CodeBuild 也提供預留容量機群，其中包含由 CodeBuild 維護且採用 Amazon EC2 技術的執行個體。使用預留容量機群，您可以為建置環境設定一組專用執行個體。這些機器保持閒置狀態，準備好立即處理組建或測試，並減少組建持續時間。使用預留容量機群，您的機器一律在執行中，只要佈建，就會持續產生成本。

**重要**  
無論您執行執行個體的時間有多長，預留容量機群都會產生每個執行個體的初始費用，之後可能會產生額外的相關費用。如需詳細資訊，請參閱[https://aws.amazon.com/codebuild/pricing/](https://aws.amazon.com/codebuild/pricing/)。

**Topics**
+ [

## 建立預留容量機群
](#fleets.how-to)
+ [

## 最佳實務
](#fleets.best-practices)
+ [

## 我可以跨多個 CodeBuild 專案共用預留容量機群嗎？
](#fleets.share)
+ [

## 屬性型運算如何運作？
](#fleets.attribute-compute)
+ [

## 我可以手動指定機群的 Amazon EC2 執行個體嗎？
](#fleets.manual-input-compute)
+ [

## 哪些區域支援預留容量機群？
](#fleets.regions)
+ [

## 如何設定預留容量 macOS 機群？
](#fleets.configure-macos)
+ [

## 如何為預留容量機群設定自訂 Amazon Machine Image (AMI)？
](#fleets.custom-ami)
+ [

## 預留容量機群的限制
](#fleets.limitations)
+ [

# 預留容量機群屬性
](fleets.reserved-capacity-fleets.md)
+ [

# 使用 的預留容量範例 AWS CodeBuild
](reserved-capacity-samples.md)

## 建立預留容量機群
<a name="fleets.how-to"></a>

使用下列指示來建立預留容量機群。

**建立預留容量機群**

1. 登入 AWS 管理主控台 並在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1. 在導覽窗格中，選擇**運算機群**，然後選擇**建立機群**。

1. 在**運算機群名稱**文字欄位中，輸入機群的名稱。

1. 從**作業系統**下拉式功能表中，選擇作業系統。

1. 從**架構**下拉式功能表中，選擇架構。

1. （選用） 選取**使用執行模式的執行個體 - 選擇性地**直接在 Amazon EC2 執行個體上執行，而非 Docker 容器。然後選擇**主要版本**和**次要版本**。

1. （選用） **在其他組態**中，執行下列動作：
   + 選取**設定 VPC - 選用**以將機群連線至 VPC，以便在使用期間存取私有資源。
     + 從 **VPC** 下拉式選單中，選取 CodeBuild 機群將存取的 VPC。
     + 從**子網路**下拉式功能表中，選取 CodeBuild 應該用來設定 VPC 組態的子網路。
     + 從**安全群組**下拉式功能表中，選取 CodeBuild 應用於 VPC 的安全群組。
     + 在**機群服務角色**欄位中，選擇現有的服務角色。
**注意**  
請確定您的機群角色具有必要的許可。如需詳細資訊，請參閱[允許使用者新增機群服務角色的許可政策](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-permission-policy-fleet-service-role)。
     + 如果您選擇 Amazon Linux 作業系統，請選取**定義代理組態 - 選用**，以套用預留容量執行個體的網路存取控制。
     + 針對**預設行為**，選擇預設允許或拒絕所有目的地的傳出流量。
     + 針對 **Proxy 規則**，選擇**新增 Proxy 規則**以指定目的地網域或 IPs，以允許或拒絕網路存取控制。
   + 選取**設定自訂 AMI - 選用**以使用自訂 Amazon Machine Image (AMI)。
     + 從 **AMI** 下拉式選單中，為您的機群選取 Amazon Machine Image (AMI)。
     + 在**機群服務角色**欄位中，選擇現有的服務角色。
**注意**  
請確定您的機群角色具有必要的許可。如需詳細資訊，請參閱[允許使用者新增機群服務角色的許可政策](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-permission-policy-fleet-service-role)。

1. 在**容量組態**中，從**運算選擇模式中**，選擇下列其中一項：
   + 如果您選擇**引導式選擇**，請執行下列動作：
     + 針對**運算**，選擇此機群中包含的執行個體類型。
     + 在**容量**文字欄位中，輸入機群中執行個體的最小數量。
     + （選用） **在其他組態**中，執行下列動作：
       + 選取**設定擴展 - 選用**，以根據此組態自動擴展機群。從**擴展模式 - 選用**下拉式功能表中，選擇需求超過機群容量時的行為。
   + 如果您選擇**自訂執行個體**，請執行下列動作：
     + 從**運算執行個體類型**下拉式功能表中，選取此機群中包含的執行個體類型。
     + 在**其他 EBS 磁碟區大小 - 選用**文字欄位中，輸入所提供的 64GB 磁碟空間以外的磁碟區。
     + 在**容量**文字欄位中，輸入機群中執行個體的最小數量。
     + （選用） **在其他組態**中，執行下列動作：
       + 選取**設定擴展 - 選用**，以根據此組態自動擴展機群。從**擴展模式 - 選用**下拉式功能表中，選擇需求超過機群容量時的行為。

1. 選擇**建立運算機群**。

1. 建立運算機群後，請建立新的 CodeBuild 專案或編輯現有的專案。在**環境中**，選擇**佈建模型**下的**預留容量**，然後在**機群名稱**下選擇指定的機群。

## 最佳實務
<a name="fleets.best-practices"></a>

使用預留容量機群時，建議您遵循這些最佳實務。
+ 我們建議您使用來源快取模式，透過快取來源來協助改善建置效能。
+ 我們建議您使用 Docker layer 快取，透過快取現有的 Docker layer 來協助改善建置效能。

## 我可以跨多個 CodeBuild 專案共用預留容量機群嗎？
<a name="fleets.share"></a>

可以，您可以將機群容量的使用率最大化，方法是跨多個專案使用。

**重要**  
使用預留容量功能時，同一帳戶中的其他專案可以存取機群執行個體上快取的資料，包括來源檔案、Docker layer 和 buildspec 中指定的快取目錄。這是根據設計，並允許相同帳戶中的專案共用機群執行個體。

## 屬性型運算如何運作？
<a name="fleets.attribute-compute"></a>

如果您選擇 `ATTRIBUTE_BASED_COMPUTE`做為機群的 `computeType`，您可以在名為 的新欄位中指定屬性`computeConfiguration`。這些屬性包括 vCPUs、記憶體、磁碟空間和 `machineType`。這是 `machineType` `GENERAL`或 `NVME`。指定一或多個可用屬性之後，CodeBuild 會從可用的支援執行個體類型中選擇運算類型，做為最終的 `computeConfiguration`。

**注意**  
CodeBuild 將選擇符合所有輸入需求最便宜的執行個體。所選執行個體的記憶體、vCPUs和磁碟空間都會大於或等於輸入需求。您可以在建立或更新的機群`computeConfiguration`中檢查已解析的 。

如果您輸入無法在 CodeBuild 中滿足`computeConfiguration`的 ，您將會收到驗證例外狀況。另請注意，如果 `computeConfiguration` 不適用於隨需，則會覆寫隨需機群溢位行為以佇列行為。

## 我可以手動指定機群的 Amazon EC2 執行個體嗎？
<a name="fleets.manual-input-compute"></a>

是，您可以透過選取自訂執行個體或設定 API 參數 ，在主控台中直接輸入所需的 Amazon EC2 執行個體`InstanceType`。 ****此欄位用於下列 APIs：CreateFleet、UpdateFleet、CreateProject、UpdateProject 和 StartBuild。如需詳細資訊，請參閱[Compute instance type](fleets.reserved-capacity-fleets.md#compute)。

## 哪些區域支援預留容量機群？
<a name="fleets.regions"></a>

下列支援預留容量 Amazon Linux 和 Windows 機群 AWS 區域：美國東部 （維吉尼亞北部）、美國東部 （俄亥俄）、美國西部 （奧勒岡）、亞太區域 （孟買）、亞太區域 （新加坡）、亞太區域 （雪梨）、亞太區域 （東京）、歐洲 （法蘭克福）、歐洲 （愛爾蘭） 和南美洲 （聖保羅）。如需 CodeBuild 可用位置的詳細資訊 AWS 區域 ，請參閱[AWS 依區域提供服務](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。

預留容量 macOS Medium 機群支援以下項目 AWS 區域：美國東部 （維吉尼亞北部）、美國東部 （俄亥俄）、美國西部 （奧勒岡）、亞太區域 （雪梨） 和歐洲 （法蘭克福）。預留容量 macOS 支援大型機群 AWS 區域：美國東部 （維吉尼亞北部）、美國東部 （俄亥俄）、美國西部 （奧勒岡） 和亞太區域 （雪梨）。

## 如何設定預留容量 macOS 機群？
<a name="fleets.configure-macos"></a>

**設定預留容量 macOS 機群**

1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1. 在導覽窗格中，選擇**運算機群**，然後選擇**建立機群**。

1. 在**運算機群名稱**文字欄位中，輸入機群的名稱。

1. 從**作業系統**下拉式功能表中，選擇 **macOS**。

1. 在**運算**欄位中，選擇下列其中一種運算機器類型：**Apple M2、24 GB 記憶體、8 個 vCPUs **或 **Apple M2、32 GB 記憶體、12 個 vCPUs**。

1. 在**容量**文字欄位中，輸入機群中執行個體的最小數量。

1. （選用） 若要為您的機群使用自訂映像，請參閱 [如何為預留容量機群設定自訂 Amazon Machine Image (AMI)？](#fleets.custom-ami) 以確保您的 Amazon Machine Image (AMI) 具有必要的先決條件。

1. （選用） 若要使用機群設定 VPC，請在**其他組態**中執行下列動作：
   + 從 **VPC - 選用**下拉式功能表中，選取 CodeBuild 機群將存取的 VPC。
   + 從**子網路**下拉式功能表中，選取 CodeBuild 應該用來設定 VPC 組態的子網路。
   + 從**安全群組**下拉式功能表中，選取 CodeBuild 應用於 VPC 的安全群組。
   + 在**機群服務角色**欄位中，選擇現有的服務角色。
**注意**  
請確定您的機群角色具有必要的許可。如需詳細資訊，請參閱[允許使用者新增機群服務角色的許可政策](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-permission-policy-fleet-service-role)。

1. 選擇**建立運算機群**，並等待機群執行個體啟動。啟動後，容量將為 `n/n`，其中 *n* 是提供的容量。

1. 運算機群啟動後，建立新的 CodeBuild 專案或編輯現有的專案。在**環境中**，選擇**佈建模型**下的**預留容量**，然後在**機群名稱**下選擇指定的機群。

## 如何為預留容量機群設定自訂 Amazon Machine Image (AMI)？
<a name="fleets.custom-ami"></a>

**為預留容量機群設定自訂 Amazon Machine Image (AMI)**

1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1. 在導覽窗格中，選擇**運算機群**，然後選擇**建立機群**。

1. 在**運算機群名稱**文字欄位中，輸入機群的名稱。

1. 選擇機群的**自訂映像**，並確保您的 Amazon Machine Image (AMI) 具有下列先決條件：
   + 如果您的環境類型是 `MAC_ARM`，請確定您的 AMI **架構**是 64 位元 `Mac-Arm`。
   + 如果您的環境類型是 `LINUX_EC2`，請確定您的 AMI **架構**是 64 位元 `x86`。
   + 如果您的環境類型是 `ARM_EC2`，請確定您的 AMI **架構**是 64 位元 `Arm`。
   + 如果您的環境類型是 `WINDOWS_EC2`，請確定您的 AMI **架構**是 64 位元 `x86`。
   + AMI 允許 CodeBuild 服務**組織 ARN**。如需組織 ARNs的清單，請參閱 [Amazon Machine Images (AMI)](fleets.reserved-capacity-fleets.md#ami)。
   + 如果 AMI 使用 AWS KMS 金鑰加密， AWS KMS 金鑰也必須允許 CodeBuild 服務**組織 ID**。如需組織 IDs的清單，請參閱 [Amazon Machine Images (AMI)](fleets.reserved-capacity-fleets.md#ami)。如需 AWS KMS 金鑰的詳細資訊，請參閱《*Amazon EC2 使用者指南*》中的[允許組織和 OUs 使用 KMS 金鑰](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/share-amis-with-organizations-and-OUs.html#allow-org-ou-to-use-key)。若要授予 CodeBuild 組織使用 KMS 金鑰的許可，請將下列陳述式新增至金鑰政策：

     ```
     {
         "Sid": "Allow access for organization root",
         "Effect": "Allow",
         "Principal": "*",
         "Action": [
             "kms:Describe*",
             "kms:List*",
             "kms:Get*",
             "kms:Encrypt",
             "kms:Decrypt",
             "kms:ReEncrypt*",
             "kms:GenerateDataKey*",
             "kms:CreateGrant"
         ],
         "Resource": "*",
         "Condition": {
             "StringEquals": {
                 "aws:PrincipalOrgID": "o-123example"
             }
         }
     }
     ```
   + 在**機群服務角色**欄位中，授予下列 Amazon EC2 許可：

------
#### [ JSON ]

****  

     ```
     {
         "Version":"2012-10-17",		 	 	 
         "Statement": [
             {
                 "Effect": "Allow",
                 "Action": [
                    "ec2:DescribeImages",
                    "ec2:DescribeSnapshots"
                 ],
                 "Resource": "*"
             }
         ]
     }
     ```

------

## 預留容量機群的限制
<a name="fleets.limitations"></a>

有些使用案例不支援預留容量機群，如果它們影響到您，請改用隨需機群：
+ 預留容量機群不支援建置使用率指標。
+ 預留容量 macOS 機群不支援偵錯工作階段。

如需限制和配額的詳細資訊，請參閱 [運算機群](limits.md#fleet-limits)。

# 預留容量機群屬性
<a name="fleets.reserved-capacity-fleets"></a>

預留容量機群包含下列屬性。如需預留容量機群的詳細資訊，請參閱 [在預留容量機群上執行組建](fleets.md)。

**作業系統**  
作業系統。下列作業系統可供使用：  
+ Amazon Linux
+ macOS
+ Windows Server 2019
+ Windows Server 2022

**Architecture**  
處理器架構。下列架構可供使用：  
+ x86\$164
+ Arm64

**環境類型**  
選取 **Amazon Linux** 時可用的環境類型。下列環境類型可供使用：  
+ Linux EC2
+ Linux GPU

**運算執行個體類型**  
機群執行個體的運算組態。    
**引導式選取**  
選取 vCPU、記憶體和磁碟空間設定，以指定不同的運算類型。如需依區域劃分的運算類型可用性資訊，請參閱 [關於預留容量環境類型](build-env-ref-compute-types.md#environment-reserved-capacity.types)。  
**自訂執行個體**  
手動指定所需的執行個體類型。

**Capacity**  
配置給機群的機器初始數量，定義可平行執行的組建數量。

**溢位行為**  
定義組建數量超過機群容量時的行為。    
**隨需**  
溢位建置會隨需在 CodeBuild 上執行。  
如果您在建立 VPC 連線機群時選擇將溢位行為設定為隨需，請務必將所需的 VPC 許可新增至專案服務角色。如需詳細資訊，請參閱[範例政策陳述式，以允許 CodeBuild AWS 存取建立 VPC 網路介面所需的服務](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-create-vpc-network-interface)。
如果您選擇將溢位行為設定為隨需，請注意，溢位建置將分別計費，類似於隨需 Amazon EC2。如需詳細資訊，請參閱[https://aws.amazon.com/codebuild/pricing/](https://aws.amazon.com/codebuild/pricing/)。  
**佇列**  
建置執行會放置在佇列中，直到機器可用為止。這會限制額外的成本，因為沒有配置額外的機器。

**Amazon Machine Image (AMI)**  
機群的 Amazon Machine Image (AMI) 屬性。CodeBuild 支援下列屬性：      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/fleets.reserved-capacity-fleets.html)

**其他組態**    
**VPC - 選用**  
CodeBuild 機群將存取的 VPC。如需詳細資訊，請參閱[AWS CodeBuild 搭配 Amazon Virtual Private Cloud 使用](vpc-support.md)。  
如果在呼叫 StartBuild API 時指定機群覆寫，CodeBuild 會忽略專案 VPC 組態。  
**子網路**  
CodeBuild 用來設定 VPC 組態的 VPC 子網路。請注意，預留容量機群僅支援單一可用區域中的一個子網路。此外，請確定您的子網路包含 NAT 閘道。  
**安全群組**  
CodeBuild 搭配 VPC 使用的 VPC 安全群組。確保您的安全群組允許傳出連線。  
**機群服務角色**  
從您帳戶中的現有服務角色定義機群的服務角色。  
**定義代理組態 - 選用**  
將網路存取控制套用至預留容量執行個體的代理組態。如需詳細資訊，請參閱[AWS CodeBuild 搭配受管代理伺服器使用](run-codebuild-in-managed-proxy-server.md)。  
Proxy 組態不支援 VPC、Windows 或 MacOS。  
**預設行為**  
定義傳出流量的行為。    
**Allow**  
根據預設，允許傳出流量到所有目的地。  
**拒絕**  
根據預設，拒絕所有目的地的傳出流量。  
**Proxy 規則**  
指定要允許或拒絕網路存取控制的目的地網域或 IPs。

# 使用 的預留容量範例 AWS CodeBuild
<a name="reserved-capacity-samples"></a>

這些範例可用於實驗 CodeBuild 中的預留容量機群。

**Topics**
+ [

## 使用預留容量範例進行快取
](#reserved-capacity-samples.caching)

## 使用預留容量範例進行快取
<a name="reserved-capacity-samples.caching"></a>

快取可以存放組建環境的可重複使用部分，並在多個組建間使用這些部分。此範例示範如何使用預留容量在建置專案中啟用快取。如需詳細資訊，請參閱[快取建置以改善效能](build-caching.md)。

您可以先在專案設定中指定一或多個快取模式：

```
Cache:
        Type: LOCAL
        Modes:
          - LOCAL_CUSTOM_CACHE
          - LOCAL_DOCKER_LAYER_CACHE
          - LOCAL_SOURCE_CACHE
```

**注意**  
請務必啟用特權模式，才能使用 Docker layer 快取。

您的專案 buildspec 設定應如下所示：

```
version: 0.2
      phases:
        build:
          commands:
            - echo testing local source cache
            - touch /codebuild/cache/workspace/foobar.txt
            - git checkout -b cached_branch
            - echo testing local docker layer cache
            - docker run alpine:3.14 2>&1 | grep 'Pulling from' || exit 1
            - echo testing local custom cache
            - touch foo
            - mkdir bar && ln -s foo bar/foo2
            - mkdir bar/bar && touch bar/bar/foo3 && touch bar/bar/foo4
            - "[ -f foo ] || exit 1"
            - "[ -L bar/foo2 ] || exit 1"
            - "[ -f bar/bar/foo3 ] || exit 1"
            - "[ -f bar/bar/foo4 ] || exit 1"
      cache:
        paths:
           - './foo'
           - './bar/**/*'
           - './bar/bar/foo3'
```

您可以從使用新專案執行組建開始，以植入快取。完成後，您應該使用覆寫的 buildspec 啟動另一個組建，如下所示：

```
version: 0.2
      phases:
        build:
          commands:
            - echo testing local source cache
            - git branch | if grep 'cached_branch'; then (exit 0); else (exit 1); fi
            - ls /codebuild/cache/workspace | if grep 'foobar.txt'; then (exit 0); else (exit 1); fi
            - echo testing local docker layer cache
            - docker run alpine:3.14 2>&1 | if grep 'Pulling from'; then (exit 1); else (exit 0); fi
            - echo testing local custom cache
            - "[ -f foo ] || exit 1"
            - "[ -L bar/foo2 ] || exit 1"
            - "[ -f bar/bar/foo3 ] || exit 1"
            - "[ -f bar/bar/foo4 ] || exit 1"
      cache:
        paths:
           - './foo'
           - './bar/**/*'
           - './bar/bar/foo3'
```

# 批次執行組建
<a name="batch-build"></a>

您可以使用 AWS CodeBuild 執行具有批次建置之專案的並行和協調建置。

**Topics**
+ [

## 安全角色
](#batch_security_role)
+ [

## 批次建置類型
](#batch_build_types)
+ [

## 批次報告模式
](#batch-report-mode)
+ [

## 其他資訊
](#batch_more_info)

## 安全角色
<a name="batch_security_role"></a>

批次建置在批次組態中導入新的安全性角色。此新角色是必要的，因為 CodeBuild 必須能夠代表您呼叫 `StartBuild`、`StopBuild` 和 `RetryBuild` 動作，才能在批次處理中執行組建。客戶應該使用新的角色，而不是與他們在組建中使用的角色相同，原因有兩個：
+ 賦予建置角色 `StartBuild`、`StopBuild` 和 `RetryBuild` 權限，此將允許單一組建透過 buildspec 啟動更多組建。
+ CodeBuild 批次建置提供限制，限制可用於批次中建置的建置和運算類型數目。如果組建角色具有這些權限，組建本身可能會略過這些限制。

## 批次建置類型
<a name="batch_build_types"></a>

CodeBuild 支援下列批次建置類型：

**Topics**
+ [

### 組建圖表
](#batch_build_graph)
+ [

### 組建清單
](#batch_build_list)
+ [

### 建置矩陣
](#batch_build_matrix)
+ [

### 建置分發
](#batch_build_fanout)

### 組建圖表
<a name="batch_build_graph"></a>

建置圖表會定義一組任務，這些任務對批次中的其他任務具有相依性。

下列範例會定義建立相依性鏈的建置圖表。

```
batch:
  fast-fail: false
  build-graph:
    - identifier: build1
      env:
        variables:
          BUILD_ID: build1
      ignore-failure: false
    - identifier: build2
      buildspec: build2.yml
      env:
        variables:
          BUILD_ID: build2
      depend-on:
        - build1
    - identifier: build3
      env:
        variables:
          BUILD_ID: build3
      depend-on:
        - build2
    - identifier: build4
      env:
        compute-type: ARM_LAMBDA_1GB
    - identifier: build5
      env:
        fleet: fleet_name
```

在此範例中：
+ `build1` 會先執行，因為它沒有相依性。
+ `build2` 具有 的相依性`build1`，因此 會在 `build1`完成後`build2`執行。
+ `build3` 具有 的相依性`build2`，因此 會在 `build2`完成後`build3`執行。

如需建置圖表 buildspec 語法的詳細資訊，請參閱 [`batch/build-graph`](batch-build-buildspec.md#build-spec.batch.build-graph)。

### 組建清單
<a name="batch_build_list"></a>

建置清單會定義一些平行執行的任務。

下列範例定義建置清單。`build1` 和 `build2`建置會平行執行。

```
batch:
  fast-fail: false
  build-list:
    - identifier: build1
      env:
        variables:
          BUILD_ID: build1
      ignore-failure: false
    - identifier: build2
      buildspec: build2.yml
      env:
        variables:
          BUILD_ID: build2
      ignore-failure: true
    - identifier: build3
      env:
        compute-type: ARM_LAMBDA_1GB
    - identifier: build4
      env:
        fleet: fleet_name
    - identifier: build5
      env:
        compute-type: GENERAL_LINUX_XLAGRE
```

如需建置清單 buildspec 語法的詳細資訊，請參閱 [`batch/build-list`](batch-build-buildspec.md#build-spec.batch.build-list)。

### 建置矩陣
<a name="batch_build_matrix"></a>

建置矩陣會定義具有平行執行之不同組態的任務。CodeBuild 會為每個可能的組態組合建立個別的組建。

下列範例顯示具有兩個 buildspec 檔案和三個環境變數值的建置矩陣。

```
batch:
  build-matrix:
    static:
      ignore-failure: false
    dynamic:
      buildspec: 
        - matrix1.yml
        - matrix2.yml
      env:
        variables:
          MY_VAR:
            - VALUE1
            - VALUE2
            - VALUE3
```

在此範例中，CodeBuild 會建立六個組建：
+ `matrix1.yml` 取代為 `$MY_VAR=VALUE1`
+ `matrix1.yml` 取代為 `$MY_VAR=VALUE2`
+ `matrix1.yml` 取代為 `$MY_VAR=VALUE3`
+ `matrix2.yml` 取代為 `$MY_VAR=VALUE1`
+ `matrix2.yml` 取代為 `$MY_VAR=VALUE2`
+ `matrix2.yml` 取代為 `$MY_VAR=VALUE3`

每個組建都會有下列設定：
+ `ignore-failure` 設定為 `false`
+ `env/type` 設定為 `LINUX_CONTAINER`
+ `env/image` 設定為 `aws/codebuild/amazonlinux-x86_64-standard:4.0`
+ `env/privileged-mode` 設定為 `true`

這些建置會平行執行。

如需建置矩陣 buildspec 語法的詳細資訊，請參閱 [`batch/build-matrix`](batch-build-buildspec.md#build-spec.batch.build-matrix)。

### 建置分發
<a name="batch_build_fanout"></a>

建置散發會定義任務，該任務將在批次中分割為多個建置。這可用於平行執行測試。CodeBuild 會根據 `parallelism` 欄位中設定的值，為每個測試案例碎片建立個別的組建。

下列範例會定義建置散發，以建立五個平行執行的建置。

```
version: 0.2

batch:
   fast-fail: false 
   build-fanout:
     parallelism: 5
     ignore-failure: false

phases:
  install:
    commands:
      - npm install
   build:
    commands:
      - mkdir -p test-results
      - cd test-results
      - |
        codebuild-tests-run \
         --test-command 'npx jest --runInBand --coverage' \
         --files-search "codebuild-glob-search '**/test/**/*.test.js'" \
         --sharding-strategy 'equal-distribution'
```

在此範例中，假設需要執行 100 個測試，CodeBuild 會建立五個組建，每個組建會平行執行 20 個測試。

如需建置圖表 buildspec 語法的詳細資訊，請參閱 [`batch/build-fanout`](batch-build-buildspec.md#build-spec.batch.build-fanout)。

## 批次報告模式
<a name="batch-report-mode"></a>

如果專案的來源提供者是 Bitbucket、GitHub 或 GitHub Enterprise，且您的專案已設定為向來源提供者報告建置狀態，您可以選取要將批次建置狀態傳送至來源提供者的方式。您可以選擇讓狀態作為批次的單一彙總狀態報告傳送，或讓批次中每個組建的狀態個別報告。

如需詳細資訊，請參閱下列主題：
+ [批次組態 （建立）](create-project.md#create-project-console-batch-config)
+ [批次組態 （更新）](change-project.md#change-project-console-batch-config)

## 其他資訊
<a name="batch_more_info"></a>

如需詳細資訊，請參閱下列主題：
+ [批次建置 buildspec 參考](batch-build-buildspec.md)
+ [批次組態](create-project.md#create-project-console-batch-config)
+ [執行批次建置 (AWS CLI)](run-batch-build-cli.md)
+ [在 中停止批次建置 AWS CodeBuild](stop-batch-build.md)

# 在批次建置中執行平行測試
<a name="parallel-test"></a>

您可以使用 AWS CodeBuild 在批次建置中執行平行測試。平行測試執行是一種測試方法，其中多個測試案例會同時跨不同的環境、機器或瀏覽器執行，而不是依序執行。這種方法可以大幅縮短整體測試執行時間，並改善測試效率。在 CodeBuild 中，您可以將測試分割到多個環境，並同時執行。

平行測試執行的主要優點包括：

1. **縮短執行時間** - 循序需要數小時的測試可以在幾分鐘內完成。

1. **更好的資源使用率** - 有效率地使用可用的運算資源。

1. **早期意見回饋** - 更快完成測試意味著對開發人員提供更快的意見回饋。

1. **經濟實惠** - 長期下來可節省時間和運算成本。

實作平行測試執行時，通常會考慮兩種主要方法：獨立環境和多執行緒。雖然這兩種方法都旨在實現並行測試執行，但它們的實作和有效性有很大的不同。不同的環境會建立隔離的執行個體，其中每個測試套件都會獨立執行，而多執行緒會使用不同的執行緒在相同的程序空間內同時執行多個測試。

相較於多執行緒，不同環境的主要優點包括：

1. **隔離** - 每個測試都會在完全隔離的環境中執行，以防止測試之間的干擾。

1. **資源衝突** - 不競爭多執行緒中經常發生的共用資源。

1. **穩定性** - 較不容易發生競爭條件和同步問題。

1. **更輕鬆地偵錯** - 當測試失敗時，更容易識別原因，因為每個環境都是獨立的。

1. **狀態管理** - 輕鬆管理困擾多執行緒測試的共用狀態問題。

1. **更好的可擴展性** - 可以輕鬆新增更多環境，而無需複雜性。

**Topics**
+ [

## 中的支援 AWS CodeBuild
](#parallel-test-support)
+ [

# 在批次建置中啟用平行測試執行
](parallel-test-enable.md)
+ [

# 使用 `codebuild-tests-run` CLI 命令
](parallel-test-tests-run.md)
+ [

# 使用 `codebuild-glob-search` CLI 命令
](parallel-test-glob-search.md)
+ [

# 關於測試分割
](parallel-test-splitting.md)
+ [

# 自動合併個別建置報告
](parallel-test-auto-merge.md)
+ [

# 各種測試架構範例的平行測試執行
](sample-parallel-test.md)

## 中的支援 AWS CodeBuild
<a name="parallel-test-support"></a>

AWS CodeBuild 透過其批次建置功能提供對平行測試執行的強大支援，專為利用個別環境執行而設計。此實作完美符合隔離測試環境的優點。

**具有測試分佈的批次建置**  
CodeBuild 的批次建置功能可建立同時執行的多個建置環境。每個環境都以完全隔離的單位運作，具有自己的運算資源、執行期環境和相依性。透過批次建置組態，您可以指定他們需要多少平行環境，以及如何將測試分散到各個環境。

**測試碎片 CLI**  
CodeBuild 透過其 CLI 工具 包含內建測試分佈機制`codebuild-tests-run`，其會自動將測試劃分為不同的環境。

**報告彙總**  
CodeBuild 實作的主要優勢之一是能夠順暢地處理測試結果彙總。當測試在不同的環境中執行時，CodeBuild 會自動收集每個環境的測試報告，並將其合併為批次建置層級的統一測試報告。此整合提供測試結果的完整檢視，同時維持平行執行的效率優勢。

下圖說明 中平行測試執行的完整概念 AWS CodeBuild。

![\[平行測試執行的概念圖。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/parallel-test.png)


# 在批次建置中啟用平行測試執行
<a name="parallel-test-enable"></a>

若要平行執行測試，請更新批次組建 buildspec 檔案，以包含 build-fanout 欄位和平行組建數目，以在 `parallelism` 欄位中分割測試套件，如下所示。`parallelism` 欄位指定要設定多少獨立執行器來執行測試套件。

若要在多個平行執行環境中執行測試，請將 `parallelism` 欄位設定為大於零的值。在以下範例中， `parallelism` 設定為 5，表示 CodeBuild 會啟動五個相同的組建，並平行執行測試套件的一部分。

您可以使用 [codebuild-tests-run](parallel-test-tests-run.md) CLI 命令來分割和執行測試。您的測試檔案會分割，而您的部分測試會在每次建置中執行。這可減少執行完整測試套件所需的整體時間。在下列範例中，測試將分割成五個，並根據測試的名稱計算分割點。

```
version: 0.2

batch:
  fast-fail: false 
  build-fanout:
    parallelism: 5
    ignore-failure: false
    
phases:
  install:
    commands:
      - npm install jest-junit --save-dev
  pre_build:
    commands:
      - echo 'prebuild'
  build:
    commands:
      - |
        codebuild-tests-run \
         --test-command 'npx jest --runInBand --coverage' \
         --files-search "codebuild-glob-search '**/_tests_/**/*.test.js'" \
         --sharding-strategy 'equal-distribution'

  post_build:
    commands:
      - codebuild-glob-search '**/*.xml'  
      - echo "Running post-build steps..."
      - echo "Build completed on `date`"

reports:
  test-reports:
    files:
      - '**/junit.xml'               
    base-directory: .
    discard-paths: yes           
    file-format: JUNITXML
```

如果報告已設定為建置集組建，則每個組建都會分別產生測試報告，這些報告可以在 AWS CodeBuild 主控台中對應組建**的報告**索引標籤下檢視。

如需如何批次執行平行測試的詳細資訊，請參閱 [各種測試架構範例的平行測試執行](sample-parallel-test.md)。

# 使用 `codebuild-tests-run` CLI 命令
<a name="parallel-test-tests-run"></a>

AWS CodeBuild 提供 CLI，會將測試命令和測試檔案位置做為輸入。具有這些輸入的 CLI 會根據測試檔案名稱，將測試分割為 `parallelism` 欄位中指定的碎片數量。將測試檔案指派給碎片是由碎片策略決定。

```
codebuild-tests-run \
    --files-search "codebuild-glob-search '**/__tests__/*.js'" \
    --test-command 'npx jest --runInBand --coverage' \
    --sharding-strategy 'equal-distribution'
```

下表說明 CLI `codebuild-tests-run` 命令的欄位。


| 欄位名稱 | Type | 必要或選用 | 定義 | 
| --- | --- | --- | --- | 
|  `test-command`  |  String  |  必要  |  此命令用於執行測試。  | 
|  `files-search`  |  String  |  必要  |  此命令會提供測試檔案的清單。您可以使用 AWS CodeBuild 提供的 [codebuild-glob-search](parallel-test-glob-search.md) CLI 命令或您選擇的任何其他檔案搜尋工具。  確保`files-search`命令輸出檔案名稱，每個名稱都以新行分隔。   | 
|  `sharding-strategy`  |  列舉  |  選用  |  有效值：`equal-distribution` (預設)、`stability` [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/parallel-test-tests-run.html) 如需詳細資訊，請參閱[關於測試分割](parallel-test-splitting.md)。  | 

CLI `codebuild-tests-run` 會先使用 `files-search` 參數中提供的命令來識別測試檔案的清單。然後，它會使用指定的碎片策略，決定指定給目前碎片 （環境） 的測試檔案子集。最後，此測試檔案子集會格式化為以空格分隔的清單，並在執行之前附加至 `test-command` 參數中提供的命令結尾。

對於不接受空格分隔清單的測試架構，`codebuild-tests-run`CLI 透過 `CODEBUILD_CURRENT_SHARD_FILES`環境變數提供彈性的替代方案。此變數包含指派給目前建置碎片之測試檔案路徑的新行分隔清單。透過利用此環境變數，您可以輕鬆適應各種測試架構需求，容納預期輸入格式與空間分隔清單不同的測試架構需求。此外，您也可以根據測試架構的需求格式化測試檔案名稱。以下是在 Linux `CODEBUILD_CURRENT_SHARD_FILES` 上使用 搭配 Django 架構的範例。以下是`CODEBUILD_CURRENT_SHARD_FILES`用來取得 Django 支援的*點表示法*檔案路徑：

```
codebuild-tests-run \
    —files-search "codebuild-glob-search '/tests/test_.py'" \
    —test-command 'python3 manage.py test $(echo "$CODEBUILD_CURRENT_SHARD_FILES" | sed -E "s/\//__/g; s/\.py$//; s/__/./g")' \
    —sharding-strategy 'equal-distribution'
```

**注意**  
請注意，`CODEBUILD_CURRENT_SHARD_FILES`環境變數只能在 CLI `codebuild-tests-run` 的範圍內使用。  
此外，如果您在 test-mand `CODEBUILD_CURRENT_SHARD_FILES`內使用 ，請放入雙引號`CODEBUILD_CURRENT_SHARD_FILES`內，如上述範例所示。

# 使用 `codebuild-glob-search` CLI 命令
<a name="parallel-test-glob-search"></a>

AWS CodeBuild 提供稱為 的內建 CLI 工具`codebuild-glob-search`，可讓您根據一或多個 glob 模式搜尋工作目錄中的檔案。當您想要對專案中的特定檔案或目錄執行測試時，此工具特別有用。

## Usage
<a name="parallel-test-glob-search.usage"></a>

`codebuild-glob-search` CLI 具有下列用量語法：

```
codebuild-glob-search <glob_pattern1> [<glob_pattern2> ...]
```
+ `<glob_pattern1>`、 `<glob_pattern2>`等：與工作目錄中的檔案相符的一或多個 glob 模式。
+ `*`：符合任何字元序列 （路徑分隔符號除外）。
+ `**`：符合任何字元序列 （包括路徑分隔符號）。

**注意**  
確定 glob 字串有引號。若要檢查模式比對的結果，請使用 `echo`命令。  

```
version: 0.2

phases:
  build:
    commands:
      - echo $(codebuild-glob-search '**/__tests__/*.js')
      - codebuild-glob-search '**/__tests__/*.js' | xargs -n 1 echo
```

## Output
<a name="parallel-test-glob-search.output"></a>

CLI 將輸出符合所提供 glob 模式的檔案路徑換行分隔清單。傳回的檔案路徑將相對於工作目錄。

如果找不到符合所提供模式的檔案，CLI 會輸出一則訊息，指出找不到檔案。

請注意，由於任何指定模式而找到的目錄將從搜尋結果中排除。

## 範例
<a name="parallel-test-glob-search.example"></a>

如果您只想要搜尋測試目錄及其子目錄中具有 `.js` 副檔名的檔案，您可以搭配 CLI `codebuild-glob-search` 使用下列命令：

```
codebuild-glob-search '**/__tests__/*.js'
```

此命令將搜尋`__tests__`目錄及其子目錄中具有`.js`副檔名的所有檔案，如 模式所示。

# 關於測試分割
<a name="parallel-test-splitting"></a>

AWS CodeBuild的測試分割功能可讓您在多個運算執行個體間平行化測試套件執行，進而縮短整體測試執行時間。此功能是透過 CodeBuild 專案設定中的批次組態和 buildspec 檔案中的`codebuild-tests-run`公用程式來啟用。

測試會根據指定的碎片策略進行分割。CodeBuild 提供兩種碎片策略，如下所示：

相等分佈  
`equal-distribution` 碎片策略會根據測試檔案名稱的字母順序，將測試分割為平行組建。此方法會先排序測試檔案，然後採用以區塊為基礎的方法來分配它們，確保類似的檔案分組在一起進行測試。建議在處理一組相對較小的測試檔案時。雖然此方法旨在為每個碎片配置大約相等數量的檔案，但最大差異為 1，但不保證穩定性。在後續建置中新增或移除測試檔案時，現有檔案的分佈可能會變更，從而導致碎片之間的重新指派。

穩定性  
`stability` 碎片策略採用一致的雜湊演算法，在碎片之間分割測試，確保檔案分佈保持穩定。新增或移除新檔案時，此方法可確保現有的file-to-shard指派大致保持不變。對於大型測試套件，建議使用穩定性選項，將測試平均分散到碎片。此機制旨在提供近乎相等的分佈，確保每個碎片都收到相似數量的檔案，只有最小的差異。雖然穩定性策略不保證理想的相等分佈，但它提供近乎相等的分佈，即使在新增或移除檔案時，也能維持跨組建的檔案指派一致性。

若要啟用測試分割，您需要在 CodeBuild 專案設定中設定批次區段，指定所需的`parallelism`層級和其他相關參數。此外，您需要在 buildspec 檔案中包含 `codebuild-tests-run`公用程式，以及適當的測試命令和分割方法。

# 自動合併個別建置報告
<a name="parallel-test-auto-merge"></a>

在廣發批次建置中， AWS CodeBuild 支援將個別建置報告自動合併為合併批次層級報告。此功能提供批次中所有組建的測試結果和程式碼涵蓋範圍的完整檢視。

## 運作方式
<a name="parallel-test-auto-merge.how"></a>

執行`fanout`批次建置時，每個個別建置都會產生[測試報告](test-reporting.md)。CodeBuild 接著會自動將來自不同組建的相同報告合併為統一報告，該報告會連接到批次組建。這些合併報告可透過 [ BatchGetBuildBatches](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_BatchGetBuildBatches.html#CodeBuild-BatchGetBuildBatches-response-buildBatches) API 的 `reportArns` 欄位輕鬆存取，也可以在 主控台的報告****索引標籤中檢視。此合併功能也延伸至自動探索的報告。

合併的報告是在 buildspec 中指定的[報告群組](test-report-group.md)下建立，或由 CodeBuild 自動探索。您可以直接在這些報告群組下分析合併報告的趨勢，提供對相同建置批次專案歷史組建的整體組建效能和品質指標的寶貴見解。

對於批次中的每個個別組建，CodeBuild 會自動建立個別的報告群組。這些遵循特定的命名慣例，將批次建置報告群組名稱與尾碼 結合`BuildFanoutShard<shard_number>`，其中 `shard_number`代表建立報告群組的碎片數量。此組織可讓您追蹤和分析合併和個別建置層級的趨勢，提供監控和評估其建置程序的彈性。

批次建置報告遵循與[個別建置報告](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_Report.html)相同的結構。**報告**索引標籤中的下列金鑰欄位專屬於批次建置報告：

**批次建置報告狀態**  
批次建置報告的狀態會根據報告類型遵循特定規則：  
+ 測試報告：
  + 成功：當所有個別建置報告都成功時，狀態會設定為成功。
  + 失敗：如果任何個別建置報告失敗，狀態會設定為失敗。
  + 未完成：如果任何個別建置報告遺失或狀態不完整，狀態會標示為未完成。
+ 程式碼涵蓋範圍報告：
  + 完成：當所有個別建置報告完成時，狀態設定為完成。
  + 失敗：如果任何個別建置報告失敗，狀態會設定為失敗。
  + 未完成：如果任何個別建置報告遺失或狀態不完整，狀態會標示為未完成。

**測試摘要**  
合併的測試報告會合併所有個別建置報告的下列欄位：  
+ 以duration-in-nano-seconds：所有個別建置報告之間的測試持續時間上限，以奈秒為單位。
+ 總計：所有測試案例的合併計數，加總每個組建的測試總數。
+ status-counts：提供測試狀態的合併檢視，例如通過、失敗或略過，透過彙總所有個別組建中每個狀態類型的計數來計算。

**程式碼涵蓋範圍摘要**  
合併程式碼涵蓋範圍報告使用下列計算，結合所有個別組建的欄位：  
+ 分支涵蓋：個別報告中所有涵蓋分支的總和。
+ 分支遺失：個別報告中所有遺失分支的總和。
+ branch-coverage-percentage： `(Total covered branches / Total branches) * 100`
+ 涵蓋的行數：個別報告中所有涵蓋行數的總和。
+ 遺漏行：個別報告中所有遺漏行的總和。
+ lines-coverage-percentage： `(Total covered lines / Total lines) * 100`

**執行 ID**  
批次建置 ARN。

**測試案例**  
合併的報告包含來自個別建置之所有測試案例的合併清單，可透過 [DescribeTestCases](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_DescribeTestCases.html) API 和主控台中的批次建置報告存取。

**程式碼涵蓋範圍**  
合併程式碼涵蓋範圍報告提供所有個別組建中每個檔案的合併行和分支涵蓋範圍資訊，可透過 [DescribeCodeCoverages](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_DescribeCodeCoverages.html) API 和主控台中的批次組建報告存取。注意：對於分散在不同碎片的多個測試檔案所涵蓋的檔案，合併的報告會使用下列選擇條件：  

1. 主要選擇是以碎片之間的最高線涵蓋範圍為基礎。

1. 如果多個碎片的折線涵蓋範圍相等，則會選取分支涵蓋範圍最高的碎片。

# 各種測試架構範例的平行測試執行
<a name="sample-parallel-test"></a>

您可以使用 `codebuild-tests-run` CLI 命令，在平行執行環境中分割和執行測試。下一節提供各種架構`buildspec.yml`的範例，說明 `codebuild-tests-run`命令的使用方式。
+ 以下每個範例都包含五個`parallelism`層級，這表示將建立五個相同的執行環境來分割您的測試。您可以透過修改 `build-fanout`區段中的 `parallelism`值來選擇適合您專案的`parallelism`關卡。
+ 以下每個範例都會顯示將您的測試設定為依測試檔案名稱分割，這是預設的。這會將測試平均分散到平行執行環境。

開始使用之前，請參閱 [在批次建置中執行平行測試](parallel-test.md) 以取得詳細資訊。

如需使用 CLI `codebuild-tests-run` 命令時選項的完整清單，請參閱 [使用 `codebuild-tests-run` CLI 命令](parallel-test-tests-run.md)。

**Topics**
+ [

# 使用 Django 設定平行測試
](sample-parallel-test-django.md)
+ [

# 使用 Elixir 設定平行測試
](sample-parallel-test-elixir.md)
+ [

# 使用 Go 設定平行測試
](sample-parallel-test-go.md)
+ [

# 使用 Java 設定平行測試 (Maven)
](sample-parallel-test-java-maven.md)
+ [

# 使用 Javascript 設定平行測試 (Jest)
](sample-parallel-test-javascript.md)
+ [

# 使用 Kotlin 設定平行測試
](sample-parallel-test-kotlin.md)
+ [

# 使用 PHPUnit 設定平行測試
](sample-parallel-test-phpunit.md)
+ [

# 使用 Pytest 設定平行測試
](sample-parallel-test-python.md)
+ [

# 使用 Ruby (Cucumber) 設定平行測試
](sample-parallel-test-ruby-cucumber.md)
+ [

# 使用 Ruby (RSpec) 設定平行測試
](sample-parallel-test-ruby.md)

# 使用 Django 設定平行測試
<a name="sample-parallel-test-django"></a>

以下是在 Ubuntu 平台上`buildspec.yml`使用 Django 顯示平行測試執行的 範例：

```
version: 0.2

batch:
  fast-fail: false
  build-fanout:
    parallelism: 5

phases:
  install:
    commands:
      - echo 'Installing Python dependencies'
      - sudo yum install -y python3 python3-pip 
      - python3 -m ensurepip --upgrade 
      - python3 -m pip install django
  pre_build:
    commands:
      - echo 'Prebuild'
  build:
    commands:
      - echo 'Running Django Tests'
      - |
        codebuild-tests-run \
         --test-command 'python3 manage.py test $(echo "$CODEBUILD_CURRENT_SHARD_FILES" | sed -E "s/\//__/g; s/\.py$//; s/__/./g")' \ 
         --files-search "codebuild-glob-search '**/tests/*test_*.py'" \
         --sharding-strategy 'equal-distribution'
  post_build:
    commands:
      - echo 'Test execution completed'
```

上述範例顯示環境變數 的使用情況`CODEBUILD_CURRENT_SHARD_FILES`。這裡`CODEBUILD_CURRENT_SHARD_FILES`用於擷取 Django 支援的點標記檔案路徑。使用雙引號`CODEBUILD_CURRENT_SHARD_FILES`內，如上所示。

# 使用 Elixir 設定平行測試
<a name="sample-parallel-test-elixir"></a>

以下是在 Ubuntu 平台上`buildspec.yml`使用 Elixir 顯示平行測試執行的 範例：

```
version: 0.2

batch:
  fast-fail: false
  build-fanout:
    parallelism: 5

phases:
  install:
    commands:
      - echo 'Installing Elixir dependencies'
      - sudo apt update
      - sudo DEBIAN_FRONTEND=noninteractive apt install -y elixir
      - elixir --version
      - mix --version
  pre_build:
    commands:
      - echo 'Prebuild'
  build:
    commands:
      - echo 'Running Elixir Tests'
      - |
        codebuild-tests-run \
         --test-command 'mix test' \
         --files-search "codebuild-glob-search '**/test/**/*_test.exs'" \ 
         --sharding-strategy 'equal-distribution'
  post_build:
    commands:
      - echo "Test execution completed"
```

# 使用 Go 設定平行測試
<a name="sample-parallel-test-go"></a>

以下是在 Linux 平台上`buildspec.yml`使用 Go 顯示平行測試執行的 範例：

```
version: 0.2

batch:
  fast-fail: false
  build-fanout:
    parallelism: 5
    ignore-failure: false

phases:
  install:
    commands:
      - echo 'Fetching Go version'
      - go version
  pre_build:
    commands:
      - echo 'prebuild'
  build:
    commands:
      - echo 'Running go Tests'
      - go mod init calculator
      - cd calc
      - |
        codebuild-tests-run \
         --test-command "go test -v calculator.go" \
         --files-search "codebuild-glob-search '**/*test.go'"
  post_build:
    commands:
      - echo "Test execution completed"
```

在上述範例中， `calculator.go`函數包含要測試的簡單數學函數，且所有測試檔案和`calculator.go`檔案都在 `calc` 資料夾內。

# 使用 Java 設定平行測試 (Maven)
<a name="sample-parallel-test-java-maven"></a>

以下是在 Linux 平台上`buildspec.yml`使用 Java 顯示平行測試執行的 範例：

```
version: 0.2

batch:
  fast-fail: false 
  build-fanout:
    parallelism: 5
    ignore-failure: false
    
phases:
  pre_build:
    commands:
      - echo 'prebuild'
  build:
    commands:
      - echo "Running mvn test"
      - |
        codebuild-tests-run \
          --test-command 'mvn test -Dtest=$(echo "$CODEBUILD_CURRENT_SHARD_FILES" | sed "s|src/test/java/||g; s/\.java//g; s|/|.|g; s/ /,/g" | tr "\n" "," | sed "s/,$//")' \
          --files-search "codebuild-glob-search '**/test/**/*.java'"
         
  post_build:
    commands:
      - echo "Running post-build steps..."
      - echo "Test execution completed"
```

在指定的範例中，環境變數`CODEBUILD_CURRENT_SHARD_FILES`包含目前碎片中的測試檔案，並以換行分隔。這些檔案會轉換成以逗號分隔的類別名稱清單，格式為 Maven 的 `-Dtest` 參數接受。

# 使用 Javascript 設定平行測試 (Jest)
<a name="sample-parallel-test-javascript"></a>

以下是`buildspec.yml`在 Ubuntu 平台上使用 Javascript 顯示平行測試執行的 範例：

```
version: 0.2

batch:
  fast-fail: true
  build-fanout:
    parallelism: 5
    ignore-failure: false

phases:
  install:
    commands:
      - echo 'Installing Node.js dependencies'
      - apt-get update
      - apt-get install -y nodejs
      - npm install
      - npm install --save-dev jest-junit
  pre_build:
    commands:
      - echo 'prebuild'
  build:
    commands:
      - echo 'Running JavaScript Tests'
      - |
         codebuild-tests-run \
          --test-command "npx jest" \
          --files-search "codebuild-glob-search '**/test/**/*.test.js'" \
          --sharding-strategy 'stability'
    post_build:
      commands:
        - echo 'Test execution completed'
```

# 使用 Kotlin 設定平行測試
<a name="sample-parallel-test-kotlin"></a>

以下是在 Linux 平台上`buildspec.yml`使用 Kotlin 顯示平行測試執行的 範例：

```
version: 0.2

batch:
  fast-fail: false
  build-fanout:
    parallelism: 2
    ignore-failure: false

phases:
  install:
    runtime-versions:
      java: corretto11 
    commands:
      - echo 'Installing dependencies'
      - KOTLIN_VERSION="1.8.20" # Replace with your desired version
      - curl -o kotlin-compiler.zip -L "https://github.com/JetBrains/kotlin/releases/download/v${KOTLIN_VERSION}/kotlin-compiler-${KOTLIN_VERSION}.zip"
      - unzip kotlin-compiler.zip -d /usr/local
      - export PATH=$PATH:/usr/local/kotlinc/bin
      - kotlin -version
      - curl -O https://repo1.maven.org/maven2/org/junit/platform/junit-platform-console-standalone/1.8.2/junit-platform-console-standalone-1.8.2.jar
  pre_build:
    commands:
      - echo 'prebuild'
  build:
    commands:
      - echo 'Running Kotlin Tests'
      - |
        codebuild-tests-run \
          --test-command 'kotlinc src/main/kotlin/*.kt $(echo "$CODEBUILD_CURRENT_SHARD_FILES" | tr "\n" " ") -d classes -cp junit-platform-console-standalone-1.8.2.jar' \
          --files-search "codebuild-glob-search 'src/test/kotlin/*.kt'"
      - |
        codebuild-tests-run \
          --test-command '
            java -jar junit-platform-console-standalone-1.8.2.jar --class-path classes \
              $(for file in $CODEBUILD_CURRENT_SHARD_FILES; do
                 class_name=$(basename "$file" .kt)
                 echo "--select-class $class_name"
               done)
          ' \
          --files-search "codebuild-glob-search 'src/test/kotlin/*.kt'"
  post_build:
    commands:
      - echo "Test execution completed"
```

在上述範例中，會使用兩次 `codebuild-tests-run` CLI。在第一次執行期間， kotlinc 會編譯檔案。`CODEBUILD_CURRENT_SHARD_FILES` 變數會擷取指派給目前碎片的測試檔案，然後轉換為以空格分隔的清單。在第二次執行中，JUnit 會執行測試。同樣地， `CODEBUILD_CURRENT_SHARD_FILES` 會擷取指派給目前碎片的測試檔案，但這次會轉換為類別名稱。

# 使用 PHPUnit 設定平行測試
<a name="sample-parallel-test-phpunit"></a>

以下是在 Linux 平台上`buildspec.yml`使用 PHPUnit 顯示平行測試執行的 範例：

```
version: 0.2
 
batch:
   fast-fail: false
   build-fanout:
     parallelism: 5
     ignore-failure: false
 
phases:
   install:
     commands:
       - echo 'Install dependencies'
       - composer require --dev phpunit/phpunit
   pre_build:
     commands:
       - echo 'prebuild'
   build:
     commands:
       - echo 'Running phpunit Tests'
       - composer dump-autoload
       - | 
         codebuild-tests-run \
          --test-command "./vendor/bin/phpunit --debug" \ 
          --files-search "codebuild-glob-search '**/tests/*Test.php'"
   post_build:
       commands:
         - echo 'Test execution completed'
```

# 使用 Pytest 設定平行測試
<a name="sample-parallel-test-python"></a>

以下是`buildspec.yml`在 Ubuntu 平台上使用 Pytest 顯示平行測試執行的 範例：

```
version: 0.2

batch:
  fast-fail: false
  build-fanout:
    parallelism: 5
    ignore-failure: false

phases:
  install:
    commands:
      - echo 'Installing Python dependencies'
      - apt-get update
      - apt-get install -y python3 python3-pip
      - pip3 install --upgrade pip
      - pip3 install pytest
  build:
    commands:
      - echo 'Running Python Tests'
      - |
         codebuild-tests-run \
          --test-command 'python -m pytest' \
          --files-search "codebuild-glob-search 'tests/test_*.py'" \
          --sharding-strategy 'equal-distribution'
  post_build:
    commands:
      - echo "Test execution completed"
```

以下是`buildspec.yml`在 Windows 平台上使用 Pytest 顯示平行測試執行的 範例：

```
version: 0.2

batch:
  fast-fail: false
  build-fanout:
    parallelism: 5
    ignore-failure: false

phases:
  install:
    commands:
      - echo 'Installing Python dependencies'
      - pip install pytest
  pre_build:
    commands:
      - echo 'prebuild'
  build:
    commands:
      - echo 'Running pytest'
      - |
        & codebuild-tests-run `
         --test-command 'pytest @("$env:CODEBUILD_CURRENT_SHARD_FILES" -split \"`r?`n\")'  `
         --files-search "codebuild-glob-search '**/test_*.py' '**/*_test.py'" `
         --sharding-strategy 'equal-distribution' 
  post_build:
    commands:
      - echo "Test execution completed"
```

在上述範例中，`CODEBUILD_CURRENT_SHARD_FILES`環境變數用於擷取指派給目前碎片並做為陣列傳遞至 pytest 命令的測試檔案。

# 使用 Ruby (Cucumber) 設定平行測試
<a name="sample-parallel-test-ruby-cucumber"></a>

以下是在 Linux 平台上`buildspec.yml`使用 Cucumber 顯示平行測試執行的 範例：

```
version: 0.2

batch:
  fast-fail: false
  build-fanout:
    parallelism: 5
    ignore-failure: false

phases:
  install:
    commands:
      - echo 'Installing Ruby dependencies'
      - gem install bundler
      - bundle install
  pre_build:
    commands:
      - echo 'prebuild'
  build:
    commands:
      - echo 'Running Cucumber Tests'
      - cucumber --init
      - |
        codebuild-tests-run \
         --test-command "cucumber" \
         --files-search "codebuild-glob-search '**/*.feature'"
  post_build:
    commands:
      - echo "Test execution completed"
```

# 使用 Ruby (RSpec) 設定平行測試
<a name="sample-parallel-test-ruby"></a>

以下是在 Ubuntu 平台上`buildspec.yml`使用 RSpec 顯示平行測試執行的 範例：

```
version: 0.2

batch:
  fast-fail: false
  build-fanout:
    parallelism: 5
    ignore-failure: false

phases:
  install:
    commands:
      - echo 'Installing Ruby dependencies'
      - apt-get update
      - apt-get install -y ruby ruby-dev build-essential
      - gem install bundler
      - bundle install
  build:
    commands:
      - echo 'Running Ruby Tests'
      - |
         codebuild-tests-run \
          --test-command 'bundle exec rspec' \
          --files-search "codebuild-glob-search 'spec/**/*_spec.rb'" \
          --sharding-strategy 'equal-distribution'
  post_build:
    commands:
      - echo "Test execution completed"
```

# 快取建置以改善效能
<a name="build-caching"></a>

當您的專案使用快取來建置時，可以為您省下時間。快取可以存放組建環境的可重複使用部分，並在多個組建間使用這些部分。您的建置專案可以使用兩種快取類型的其中之一：Amazon S3 或本機。如果您使用本機快取，您必須從三種快取模式中選擇一或多種：來源快取、Docker 層快取和自訂快取。

**注意**  
Docker 層快取模式僅適用於 Linux 環境。如果您選擇此模式，您必須以特殊權限模式執行您的組建。CodeBuild 專案授予特權模式會授予其容器存取所有裝置的權限。如需詳細資訊，請參閱 Docker Docs 網站上的[執行期權限和 Linux 功能](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)。

**Topics**
+ [

# Amazon S3 快取
](caching-s3.md)
+ [

# 本機快取
](caching-local.md)
+ [

# 指定本機快取
](specify-caching-local.md)

# Amazon S3 快取
<a name="caching-s3"></a>

Amazon S3 快取會將快取存放在跨多個建置主機可用的 Amazon S3 儲存貯體中。對於較下載更昂貴的中小型建置成品，這是理想的選項。

若要在建置中使用 Amazon S3，您可以指定要在 中快取之檔案的路徑`buildspec.yml`。CodeBuild 會自動將快取儲存並更新至專案上設定的 Amazon S3 位置。如果您未指定檔案路徑，CodeBuild 會盡最大努力快取常見的語言相依性，以協助您加速建置。您可以在建置日誌中檢視快取詳細資訊。

此外，如果您想要有多個版本的快取，您可以在 中定義快取金鑰`buildspec.yml`。CodeBuild 會將快取存放在此快取金鑰的內容下，並建立唯一的快取複本，一旦建立就不會更新。快取金鑰也可以跨專案共用。只有在指定金鑰時，才能使用動態金鑰、快取版本控制和跨組建快取共用等功能。

若要進一步了解 buildspec 檔案中的快取語法，請參閱 buildspec 參考[快取](build-spec-ref.md#build-spec.cache)中的 。

**Topics**
+ [

## 產生動態金鑰
](#caching-s3-dynamic)
+ [

## codebuild-hash-files
](#caching-s3-dynamic.codebuild-hash-files)
+ [

## 快取版本
](#caching-s3-version)
+ [

## 專案之間的快取共用
](#caching-s3-sharing)
+ [

## Buildspec 範例
](#caching-s3-examples)

## 產生動態金鑰
<a name="caching-s3-dynamic"></a>

快取金鑰可以包含 Shell 命令和環境變數，使其獨一無二，並在金鑰變更時啟用自動快取更新。例如，您可以使用 `package-lock.json` 檔案的雜湊來定義金鑰。當該檔案中的相依性變更時，雜湊 - 因此是快取金鑰 - 會變更，觸發自動建立新的快取。

```
cache:
    key: npm-key-$(codebuild-hash-files package-lock.json)
```

CodeBuild 將評估表達式`$(codebuild-hash-files package-lock.json)`以取得最終索引鍵：

```
npm-key-abc123
```

您也可以使用環境變數定義快取金鑰，例如 `CODEBUILD_RESOLVED_SOURCE_VERSION`。這可確保每當來源變更時，都會產生新的金鑰，進而自動儲存新的快取：

```
cache:
   key: npm-key-$CODEBUILD_RESOLVED_SOURCE_VERSION
```

CodeBuild 將評估表達式並取得最終索引鍵：

```
npm-key-046e8b67481d53bdc86c3f6affdd5d1afae6d369
```

## codebuild-hash-files
<a name="caching-s3-dynamic.codebuild-hash-files"></a>

`codebuild-hash-files` 是一種 CLI 工具，可使用 glob 模式計算 CodeBuild 來源目錄中一組檔案的 SHA-256 雜湊：

```
codebuild-hash-files <glob-pattern-1> <glob-pattern-2> ...
```

以下是使用 的一些範例`codebuild-hash-files`：

```
codebuild-hash-files package-lock.json
codebuild-hash-files '**/*.md'
```

## 快取版本
<a name="caching-s3-version"></a>

快取版本是從要快取之目錄的路徑產生的雜湊。如果兩個快取有不同的版本，則在比對程序期間會將它們視為不同的快取。例如，以下兩個快取會被視為不同，因為它們參考不同的路徑：

```
version: 0.2

phases:
  build:
    commands:
      - pip install pandas==2.2.3 --target pip-dependencies
cache:
  key: pip-dependencies 
  paths:
    - "pip-dependencies/**/*"
```

```
version: 0.2

phases:
  build:
    commands:
      - pip install pandas==2.2.3 --target tmp/pip-dependencies
cache:
  key: pip-dependencies 
  paths:
    - "tmp/pip-dependencies/**/*"
```

## 專案之間的快取共用
<a name="caching-s3-sharing"></a>

您可以使用 `cache`區段下的 `cacheNamespace` API 欄位，跨多個專案共用快取。此欄位定義快取的範圍。若要共用快取， 必須執行下列動作：
+ 使用相同的 `cacheNamespace`。
+ 指定相同的快取 `key`。
+ 定義相同的快取路徑。
+ `pathPrefix` 如果設定，請使用相同的 Amazon S3 儲存貯體和 。

這可確保一致性，並啟用跨專案的快取共用。

### 指定快取命名空間 （主控台）
<a name="caching-s3-sharing.console"></a>

1. 在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1. 選擇**建立專案**。如需詳細資訊，請參閱 [建立組建專案 (主控台)](create-project.md#create-project-console) 及 [執行建置 (主控台)](run-build-console.md)。

1. 在**成品**中，選擇**其他組態**。

1. 針對**快取類型**，選擇 **Amazon S3**。

1. 針對**快取命名空間 - 選用**，輸入命名空間值。  
![\[CodeBuild 主控台中的快取命名空間參數。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/s3-cache-namespace.png)

1. 繼續執行預設值，然後選擇**建立建置專案**。

### 指定快取命名空間 (AWS CLI)
<a name="caching-s3-sharing.cli"></a>

您可以使用 中的 `--cache` 參數 AWS CLI 來指定快取命名空間。

```
--cache '{"type": "S3", "location": "your-s3-bucket", "cacheNamespace": "test-cache-namespace"}'
```

## Buildspec 範例
<a name="caching-s3-examples"></a>

以下是幾個常見語言的 buildspec 範例：

**Topics**
+ [

### 快取 Node.js 相依性
](#caching-s3-examples.nodejs)
+ [

### 快取 Python 相依性
](#caching-s3-examples.python)
+ [

### 快取 Ruby 相依性
](#caching-s3-examples.ruby)
+ [

### 快取 Go 相依性
](#caching-s3-examples.go)

### 快取 Node.js 相依性
<a name="caching-s3-examples.nodejs"></a>

如果您的專案包含 `package-lock.json` 檔案並使用 `npm` 來管理 Node.js 相依性，下列範例會示範如何設定快取。根據預設， 會將相依性`npm`安裝到 `node_modules`目錄中。

```
version: 0.2

phases:
  build:
    commands:
      - npm install
cache:
  key: npm-$(codebuild-hash-files package-lock.json)
  paths:
    - "node_modules/**/*"
```

### 快取 Python 相依性
<a name="caching-s3-examples.python"></a>

如果您的專案包含 `requirements.txt` 檔案並使用 pip 來管理 Python 相依性，下列範例會示範如何設定快取。根據預設，pip 會將套件安裝到系統的`site-packages`目錄中。

```
version: 0.2

phases:
  build:
    commands:
      - pip install -r requirements.txt
cache:
  key: python-$(codebuild-hash-files requirements.txt)
  paths:
    - "/root/.pyenv/versions/${python_version}/lib/python${python_major_version}/site-packages/**/*"
```

此外，您可以在特定目錄中安裝相依性，並設定該目錄的快取。

```
version: 0.2

phases:
  build:
    commands:
      - pip install -r requirements.txt --target python-dependencies
cache:
  key: python-$(codebuild-hash-files requirements.txt)
  paths:
    - "python-dependencies/**/*"
```

### 快取 Ruby 相依性
<a name="caching-s3-examples.ruby"></a>

如果您的專案包含 `Gemfile.lock` 檔案並使用 `Bundler` 來管理 Gem 相依性，下列範例會示範如何有效設定快取。

```
version: 0.2

phases:
  build:
    commands:
      - bundle install --path vendor/bundle
cache:
  key: ruby-$(codebuild-hash-files Gemfile.lock)
  paths:
    - "vendor/bundle/**/*"
```

### 快取 Go 相依性
<a name="caching-s3-examples.go"></a>

如果您的專案包含 `go.sum` 檔案，並使用 Go 模組來管理相依性，下列範例會示範如何設定快取。根據預設，Go 模組會下載並存放在 `${GOPATH}/pkg/mod`目錄中。

```
version: 0.2

phases:
  build:
    commands:
      - go mod download
cache:
  key: go-$(codebuild-hash-files go.sum)
  paths:
    - "/go/pkg/mod/**/*"
```

# 本機快取
<a name="caching-local"></a>

本機快取將快取存放在組建主機的本機，而僅供該組建主機使用。這是中大型建置成品的好選項，因為快取可立即在建置主機上使用。如果是不常存取的組建，這不是最佳選項。這表示組建效能不會受到網路傳輸時間所影響。

如果您選擇本機快取，您必須選擇以下一或多個快取模式：
+ 來源快取模式會快取主要和次要來源的 Git 中繼資料。建立快取之後，後續組建只會提取遞交之間的變更。如果專案有全新的工作目錄，且來源是大型的 Git 儲存庫，此模式是很好的選擇。如果您選擇此選項，且您的專案不使用 Git 儲存庫 (AWS CodeCommit、GitHub、GitHub Enterprise Server 或 Bitbucket)，則會忽略此選項。
+ Docker 層快取模式會快取現有的 Docker 層。如果專案會建置或提取大型 Docker 影像，此模式是很好的選擇。它可以避免從網路提取大型 Docker 影像所造成的效能問題。
**注意**  
您只能在 Linux 環境中使用 Docker 層快取。
您必須設定 `privileged` 旗標，專案才能具備所需的 Docker 許可。  
預設會為非 VPC 建置啟用 Docker 協助程式。如果您想要將 Docker 容器用於 VPC 建置，請參閱 Docker 文件網站上的[執行期權限和 Linux 功能](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)，並啟用特權模式。此外，Windows 不支援特殊權限模式。
使用 Docker 層快取之前，您應該考慮安全隱憂。
+ 自訂快取模式會快取您在 buildspec 檔案中指定的目錄。如果您的組建案例不適合其他兩個本機快取模式，此模式是很好的選擇。如果您使用自訂快取：
  + 只能指定目錄來快取。您不能指定個別檔案。
  + 符號連結用來參考快取的目錄。
  + 在您的組建下載其專案來源之前，快取的目錄會連結到您的組建。如果快取項目具有相同名稱，則會覆寫來源項目。目錄的指定方式是使用 buildspec 檔案中的快取路徑。如需詳細資訊，請參閱[Buildspec 語法](build-spec-ref.md#build-spec-ref-syntax)。
  + 避免來源和快取中的目錄名稱相同。本機快取的目錄可能會覆寫或刪除具有相同名稱之來源儲存庫中的目錄內容。

**注意**  
`LINUX_GPU_CONTAINER` 環境類型和`BUILD_GENERAL1_2XLARGE`運算類型不支援本機快取。如需詳細資訊，請參閱[建置環境運算模式和類型](build-env-ref-compute-types.md)。

**注意**  
當您設定 CodeBuild 使用 VPC 時，不支援本機快取。如需搭配 CodeBuild 使用 VPCs 的詳細資訊，請參閱 [AWS CodeBuild 搭配 Amazon Virtual Private Cloud 使用](vpc-support.md)。

# 指定本機快取
<a name="specify-caching-local"></a>

您可以使用 AWS CLI、 主控台、 SDK 或 CloudFormation 來指定本機快取。如需本機快取的詳細資訊，請參閱 [本機快取](caching-local.md)。

**Topics**
+ [

## 指定本機快取 (CLI)
](#caching-local-cli)
+ [

## 指定本機快取 (主控台)
](#caching-local-console)
+ [

## 指定本機快取 (CloudFormation)
](#caching-local-cfn)

## 指定本機快取 (CLI)
<a name="caching-local-cli"></a>

您可以使用 中的 `--cache` 參數 AWS CLI 來指定三種本機快取類型的每一個。
+ 若要指定來源快取：

  ```
  --cache type=LOCAL,mode=[LOCAL_SOURCE_CACHE]
  ```
+ 若要指定 Docker 層快取：

  ```
  --cache type=LOCAL,mode=[LOCAL_DOCKER_LAYER_CACHE]
  ```
+ 若要指定自訂快取：

  ```
  --cache type=LOCAL,mode=[LOCAL_CUSTOM_CACHE]
  ```

如需詳細資訊，請參閱[建立建置專案 (AWS CLI)](create-project.md#create-project-cli)。

## 指定本機快取 (主控台)
<a name="caching-local-console"></a>

您可以在主控台的 **Artifacts (成品)** 區段中指定快取。針對**快取類型**，選擇 **Amazon S3** 或 **Local**。如果您選擇 **Local (本機)**，請從三種本機快取選項中選擇一或多種。

![\[透過選擇三個本機快取選項中的一個或多個來指定本機快取。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/local-cache.png)


如需詳細資訊，請參閱[建立組建專案 (主控台)](create-project.md#create-project-console)。

## 指定本機快取 (CloudFormation)
<a name="caching-local-cfn"></a>

如果您使用 CloudFormation 指定本機快取，請在 `Cache` 屬性上指定 `Type``LOCAL`。下列 YAML 格式 CloudFormation 程式碼範例會指定所有三種本機快取類型。您可以指定這些類型的任意組合。如果您使用 Docker 層快取，在 `Environment` 下，您必須將 `PrivilegedMode` 設定為 `true`，將 `Type` 設定為 `LINUX_CONTAINER`。

```
CodeBuildProject:
    Type: AWS::CodeBuild::Project
    Properties:
      Name: MyProject
      ServiceRole: <service-role>
      Artifacts:
        Type: S3
        Location: <bucket-name>
        Name: myArtifact
        EncryptionDisabled: true
        OverrideArtifactName: true
      Environment:
        Type: LINUX_CONTAINER
        ComputeType: BUILD_GENERAL1_SMALL
        Image: aws/codebuild/standard:5.0
        Certificate: <bucket/cert.zip>
        # PrivilegedMode must be true if you specify LOCAL_DOCKER_LAYER_CACHE
        PrivilegedMode: true
      Source:
        Type: GITHUB
        Location: <github-location>
        InsecureSsl: true
        GitCloneDepth: 1
        ReportBuildStatus: false
      TimeoutInMinutes: 10
      Cache:
        Type: LOCAL
        Modes: # You can specify one or more cache mode, 
          - LOCAL_CUSTOM_CACHE
          - LOCAL_DOCKER_LAYER_CACHE
          - LOCAL_SOURCE_CACHE
```

**注意**  
預設會為非 VPC 建置啟用 Docker 協助程式。如果您想要將 Docker 容器用於 VPC 建置，請參閱 Docker 文件網站上的[執行期權限和 Linux 功能](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)，並啟用特權模式。此外，Windows 不支援特殊權限模式。

如需詳細資訊，請參閱[建立建置專案 (CloudFormation)](create-project.md#create-project-cloud-formation)。

# 在 中對組建進行偵錯 AWS CodeBuild
<a name="debug-builds"></a>

AWS CodeBuild 提供兩種在開發和疑難排解期間對組建進行偵錯的方法。您可以使用 CodeBuild 沙盒環境來調查問題並即時驗證修正，也可以使用 AWS Systems Manager Session Manager 連線到建置容器並檢視容器狀態。

## 使用 CodeBuild 沙盒對組建進行偵錯
<a name="debug-codebuild-sandbox"></a>

CodeBuild 沙盒環境在安全且隔離的環境中提供互動式偵錯工作階段。您可以透過 AWS 管理主控台 或 直接與環境互動 AWS CLI、執行命令，並逐步驗證您的建置程序。它使用經濟實惠的每秒計費模型，並支援與建置環境的來源提供者 AWS 和服務相同的原生整合。您也可以使用 SSH 用戶端或從整合式開發環境 (IDEs) 連線到沙盒環境。

若要進一步了解 CodeBuild 沙盒定價，請造訪 [CodeBuild 定價文件](https://aws.amazon.com/codebuild/pricing/#Sandbox)。如需詳細說明，請參閱 [使用 CodeBuild 沙盒對組建進行偵錯](sandbox.md) 文件。

## 使用 Session Manager 偵錯組建
<a name="debug-codebuild-session-manager"></a>

AWS Systems Manager Session Manager 可讓您直接存取在實際執行環境中執行的組建。此方法可讓您連線至作用中的建置容器，並即時檢查建置程序。您可以檢查檔案系統、監控執行中的程序，並在問題發生時進行故障診斷。

如需詳細說明，請參閱 [使用 Session Manager 偵錯組建](session-manager.md) 文件。

# 使用 CodeBuild 沙盒對組建進行偵錯
<a name="sandbox"></a>

在 中 AWS CodeBuild，您可以使用 CodeBuild 沙盒對組建進行偵錯，以執行自訂命令並對組建進行疑難排解。

**Topics**
+ [

## 先決條件
](#sandbox-prereq)
+ [

## 使用 CodeBuild 沙盒偵錯組建 （主控台）
](#sandbox-console)
+ [

## 使用 CodeBuild 沙盒對組建進行偵錯 (AWS CLI)
](#sandbox-cli)
+ [

# 教學課程：使用 SSH 連線至沙盒
](sandbox-ssh-tutorial.md)
+ [

# 對 AWS CodeBuild 沙盒 SSH 連線問題進行故障診斷
](sandbox-troubleshooting.md)

## 先決條件
<a name="sandbox-prereq"></a>

使用 CodeBuild 沙盒之前，請確定您的 CodeBuild 服務角色具有下列 SSM 政策：

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssmmessages:CreateControlChannel",
                "ssmmessages:CreateDataChannel",
                "ssmmessages:OpenControlChannel",
                "ssmmessages:OpenDataChannel"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ssm:StartSession"
            ],
            "Resource": [
                "arn:aws:codebuild:us-east-1:111122223333:build/*",
                "arn:aws:ssm:us-east-1::document/AWS-StartSSHSession"
            ]
        }
    ]
}
```

------

## 使用 CodeBuild 沙盒偵錯組建 （主控台）
<a name="sandbox-console"></a>

使用下列指示在 主控台中執行命令，並將 SSH 用戶端與 CodeBuild 沙盒連線。

### 使用 CodeBuild 沙盒執行命令 （主控台）
<a name="sandbox-console.commands"></a>

1. 在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1. 在導覽窗格中，選擇 **Build projects (建置專案)**。選擇建置專案，然後選擇**偵錯建置**。  
![\[主控台中的偵錯建置專案詳細資訊頁面。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/sandbox-debug-build.png)

1. 在**執行命令**索引標籤中，輸入您的自訂命令，然後選擇**執行命令**。  
![\[主控台中的執行命令詳細資訊頁面。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/debug-build-run.png)

1. 然後，您的 CodeBuild 沙盒將初始化並開始執行您的自訂命令。輸出完成後，輸出會顯示在**輸出**索引標籤中。  
![\[主控台中的執行命令輸出頁面。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/debug-build-run-output.png)

1. 疑難排解完成時，您可以選擇停止沙盒來**停止沙盒**。然後選擇**停止**，確認您的沙盒將停止。  
![\[停止沙盒對話方塊。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/stop-sandbox.png)  
![\[主控台中已停止沙盒的執行命令輸出頁面。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/stopped-sandbox.png)

### 使用 CodeBuild 沙盒 （主控台） 連線至 SSH 用戶端
<a name="sandbox-console.ssh"></a>

1. 在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1. 在導覽窗格中，選擇 **Build projects (建置專案)**。選擇建置專案，然後選擇**偵錯建置**。  
![\[主控台中的偵錯建置專案詳細資訊頁面。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/sandbox-debug-build.png)

1. 在 **SSH 用戶端**索引標籤中，選擇**啟動沙盒**。  
![\[主控台中的 SSH 用戶端沙盒頁面。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/ssh-client-sandbox.png)

1. CodeBuild 沙盒開始執行後，請依照主控台指示，將 SSH 用戶端連線至沙盒。  
![\[主控台中的 SSH 用戶端沙盒頁面。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/ssh-client-sandbox-terminal.png)

1. 疑難排解完成時，您可以選擇停止沙盒來**停止沙盒**。然後選擇**停止**，確認您的沙盒將停止。  
![\[停止沙盒對話方塊。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/stop-sandbox-2.png)  
![\[主控台中已停止沙盒的執行命令輸出頁面。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/stopped-sandbox-2.png)

## 使用 CodeBuild 沙盒對組建進行偵錯 (AWS CLI)
<a name="sandbox-cli"></a>

使用下列指示來執行命令，並將 SSH 用戶端連線至 CodeBuild 沙盒。

### 啟動 CodeBuild 沙盒 (AWS CLI)
<a name="sandbox-cli.start-sandbox"></a>

------
#### [ CLI command ]

```
aws codebuild start-sandbox --project-name $PROJECT_NAME
```
+ `--project-name` ：CodeBuild 專案名稱

------
#### [ Sample request ]

```
aws codebuild start-sandbox --project-name "project-name"
```

------
#### [ Sample response ]

```
{
    "id": "project-name",
    "arn": "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name",
    "projectName": "project-name",
    "requestTime": "2025-02-06T11:24:15.560000-08:00",
    "status": "QUEUED",
    "source": {
        "type": "S3",
        "location": "arn:aws:s3:::cofa-e2e-test-1-us-west-2-beta-default-build-sources/eb-sample-jetty-v4.zip",
        "insecureSsl": false
    },
    "environment": {
        "type": "LINUX_CONTAINER",
        "image": "aws/codebuild/standard:6.0",
        "computeType": "BUILD_GENERAL1_SMALL",
        "environmentVariables": [{
                "name": "foo",
                "value": "bar",
                "type": "PLAINTEXT"
            },
            {
                "name": "bar",
                "value": "baz",
                "type": "PLAINTEXT"
            }
        ],
        "privilegedMode": false,
        "imagePullCredentialsType": "CODEBUILD"
    },
    "timeoutInMinutes": 10,
    "queuedTimeoutInMinutes": 480,
    "logConfig": {
        "cloudWatchLogs": {
            "status": "ENABLED",
            "groupName": "group",
            "streamName": "stream"
        },
        "s3Logs": {
            "status": "ENABLED",
            "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs",
            "encryptionDisabled": false
        }
    },
    "encryptionKey": "arn:aws:kms:us-west-2:962803963624:alias/SampleEncryptionKey",
    "serviceRole": "arn:aws:iam::962803963624:role/BuildExecutionServiceRole",
    "currentSession": {
        "id": "0103e0e7-52aa-4a3d-81dd-bfc27226fa54",
        "currentPhase": "QUEUED",
        "status": "QUEUED",
        "startTime": "2025-02-06T11:24:15.626000-08:00",
        "logs": {
            "groupName": "group",
            "streamName": "stream/0103e0e7-52aa-4a3d-81dd-bfc27226fa54",
            "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream$252F0103e0e7-52aa-4a3d-81dd-bfc27226fa54",
            "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/0103e0e7-52aa-4a3d-81dd-bfc27226fa54.gz?region=us-west-2",
            "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream/0103e0e7-52aa-4a3d-81dd-bfc27226fa54",
            "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/0103e0e7-52aa-4a3d-81dd-bfc27226fa54.gz",
            "cloudWatchLogs": {
                "status": "ENABLED",
                "groupName": "group",
                "streamName": "stream"
            },
            "s3Logs": {
                "status": "ENABLED",
                "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs",
                "encryptionDisabled": false
            }
        }
    }
}
```

------

### 取得沙盒狀態的相關資訊 (AWS CLI)
<a name="sandbox-cli.batch-get-sandboxes"></a>

------
#### [ CLI command ]

```
aws codebuild batch-get-sandboxes --ids $SANDBOX_IDs
```

------
#### [ Sample request ]

```
aws codebuild stop-sandbox --id "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name"
```
+ `--ids` ：以逗號分隔的 `sandboxIds`或 清單`sandboxArns`。

您可以提供沙盒 ID 或沙盒 ARN：
+ 沙盒 ID： `<codebuild-project-name>:<UUID>`

  例如 `project-name:d25be134-05cb-404a-85da-ac5f85d2d72c`。
+ 沙盒 ARN：arn：aws：codebuild：*<region>*：*<account-id>*：sandbox/*<codebuild-project-name>*：*<UUID>*

  例如 `arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name:d25be134-05cb-404a-85da-ac5f85d2d72c`。

------
#### [ Sample response ]

```
{
    "sandboxes": [{
        "id": "project-name",
        "arn": "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name",
        "projectName": "project-name",
        "requestTime": "2025-02-06T11:24:15.560000-08:00",
        "endTime": "2025-02-06T11:39:21.587000-08:00",
        "status": "STOPPED",
        "source": {
            "type": "S3",
            "location": "arn:aws:s3:::cofa-e2e-test-1-us-west-2-beta-default-build-sources/eb-sample-jetty-v4.zip",
            "insecureSsl": false
        },
        "environment": {
            "type": "LINUX_CONTAINER",
            "image": "aws/codebuild/standard:6.0",
            "computeType": "BUILD_GENERAL1_SMALL",
            "environmentVariables": [{
                    "name": "foo",
                    "value": "bar",
                    "type": "PLAINTEXT"
                },
                {
                    "name": "bar",
                    "value": "baz",
                    "type": "PLAINTEXT"
                }
            ],
            "privilegedMode": false,
            "imagePullCredentialsType": "CODEBUILD"
        },
        "timeoutInMinutes": 10,
        "queuedTimeoutInMinutes": 480,
        "logConfig": {
            "cloudWatchLogs": {
                "status": "ENABLED",
                "groupName": "group",
                "streamName": "stream"
            },
            "s3Logs": {
                "status": "ENABLED",
                "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs",
                "encryptionDisabled": false
            }
        },
        "encryptionKey": "arn:aws:kms:us-west-2:962803963624:alias/SampleEncryptionKey",
        "serviceRole": "arn:aws:iam::962803963624:role/BuildExecutionServiceRole",
        "currentSession": {
            "id": "0103e0e7-52aa-4a3d-81dd-bfc27226fa54",
            "currentPhase": "COMPLETED",
            "status": "STOPPED",
            "startTime": "2025-02-06T11:24:15.626000-08:00",
            "endTime": "2025-02-06T11:39:21.600000-08:00",
            "phases": [{
                    "phaseType": "SUBMITTED",
                    "phaseStatus": "SUCCEEDED",
                    "startTime": "2025-02-06T11:24:15.577000-08:00",
                    "endTime": "2025-02-06T11:24:15.606000-08:00",
                    "durationInSeconds": 0
                },
                {
                    "phaseType": "QUEUED",
                    "phaseStatus": "SUCCEEDED",
                    "startTime": "2025-02-06T11:24:15.606000-08:00",
                    "endTime": "2025-02-06T11:24:16.067000-08:00",
                    "durationInSeconds": 0
                },
                {
                    "phaseType": "PROVISIONING",
                    "phaseStatus": "SUCCEEDED",
                    "startTime": "2025-02-06T11:24:16.067000-08:00",
                    "endTime": "2025-02-06T11:24:20.519000-08:00",
                    "durationInSeconds": 4,
                    "contexts": [{
                        "statusCode": "",
                        "message": ""
                    }]
                },
                {
                    "phaseType": "DOWNLOAD_SOURCE",
                    "phaseStatus": "SUCCEEDED",
                    "startTime": "2025-02-06T11:24:20.519000-08:00",
                    "endTime": "2025-02-06T11:24:22.238000-08:00",
                    "durationInSeconds": 1,
                    "contexts": [{
                        "statusCode": "",
                        "message": ""
                    }]
                },
                {
                    "phaseType": "RUNNING_SANDBOX",
                    "phaseStatus": "TIMED_OUT",
                    "startTime": "2025-02-06T11:24:22.238000-08:00",
                    "endTime": "2025-02-06T11:39:21.560000-08:00",
                    "durationInSeconds": 899,
                    "contexts": [{
                        "statusCode": "BUILD_TIMED_OUT",
                        "message": "Build has timed out. "
                    }]
                },
                {
                    "phaseType": "COMPLETED",
                    "startTime": "2025-02-06T11:39:21.560000-08:00"
                }
            ],
            "logs": {
                "groupName": "group",
                "streamName": "stream/0103e0e7-52aa-4a3d-81dd-bfc27226fa54",
                "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream$252F0103e0e7-52aa-4a3d-81dd-bfc27226fa54",
                "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/0103e0e7-52aa-4a3d-81dd-bfc27226fa54.gz?region=us-west-2",
                "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream/0103e0e7-52aa-4a3d-81dd-bfc27226fa54",
                "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/0103e0e7-52aa-4a3d-81dd-bfc27226fa54.gz",
                "cloudWatchLogs": {
                    "status": "ENABLED",
                    "groupName": "group",
                    "streamName": "stream"
                },
                "s3Logs": {
                    "status": "ENABLED",
                    "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs",
                    "encryptionDisabled": false
                }
            }
        }
    }],
    "sandboxesNotFound": []
}
```

------

### 停止沙盒 (AWS CLI)
<a name="sandbox-cli.stop-sandbox"></a>

------
#### [ CLI command ]

```
aws codebuild stop-sandbox --id $SANDBOX-ID
```
+ `--id` ： `sandboxId`或 `sandboxArn`。

------
#### [ Sample request ]

```
aws codebuild stop-sandbox --id "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name"
```

------
#### [ Sample response ]

```
{
    "id": "project-name",
    "arn": "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name",
    "projectName": "project-name",
    "requestTime": "2025-02-06T11:24:15.560000-08:00",
    "status": "STOPPING",
    "source": {
        "type": "S3",
        "location": "arn:aws:s3:::cofa-e2e-test-1-us-west-2-beta-default-build-sources/eb-sample-jetty-v4.zip",
        "insecureSsl": false
    },
    "environment": {
        "type": "LINUX_CONTAINER",
        "image": "aws/codebuild/standard:6.0",
        "computeType": "BUILD_GENERAL1_SMALL",
        "environmentVariables": [{
                "name": "foo",
                "value": "bar",
                "type": "PLAINTEXT"
            },
            {
                "name": "bar",
                "value": "baz",
                "type": "PLAINTEXT"
            }
        ],
        "privilegedMode": false,
        "imagePullCredentialsType": "CODEBUILD"
    },
    "timeoutInMinutes": 10,
    "queuedTimeoutInMinutes": 480,
    "logConfig": {
        "cloudWatchLogs": {
            "status": "ENABLED",
            "groupName": "group",
            "streamName": "stream"
        },
        "s3Logs": {
            "status": "ENABLED",
            "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs",
            "encryptionDisabled": false
        }
    },
    "encryptionKey": "arn:aws:kms:us-west-2:962803963624:alias/SampleEncryptionKey",
    "serviceRole": "arn:aws:iam::962803963624:role/BuildExecutionServiceRole",
    "currentSession": {
        "id": "0103e0e7-52aa-4a3d-81dd-bfc27226fa54",
        "currentPhase": "RUN_SANDBOX",
        "status": "STOPPING",
        "startTime": "2025-02-06T11:24:15.626000-08:00",
        "phases": [{
                "phaseType": "SUBMITTED",
                "phaseStatus": "SUCCEEDED",
                "startTime": "2025-02-08T14:33:26.144000-08:00",
                "endTime": "2025-02-08T14:33:26.173000-08:00",
                "durationInSeconds": 0
            },
            {
                "phaseType": "QUEUED",
                "phaseStatus": "SUCCEEDED",
                "startTime": "2025-02-08T14:33:26.173000-08:00",
                "endTime": "2025-02-08T14:33:26.702000-08:00",
                "durationInSeconds": 0
            },
            {
                "phaseType": "PROVISIONING",
                "phaseStatus": "SUCCEEDED",
                "startTime": "2025-02-08T14:33:26.702000-08:00",
                "endTime": "2025-02-08T14:33:30.530000-08:00",
                "durationInSeconds": 3,
                "contexts": [{
                    "statusCode": "",
                    "message": ""
                }]
            },
            {
                "phaseType": "DOWNLOAD_SOURCE",
                "phaseStatus": "SUCCEEDED",
                "startTime": "2025-02-08T14:33:30.530000-08:00",
                "endTime": "2025-02-08T14:33:33.478000-08:00",
                "durationInSeconds": 2,
                "contexts": [{
                    "statusCode": "",
                    "message": ""
                }]
            },
            {
                "phaseType": "RUN_SANDBOX",
                "startTime": "2025-02-08T14:33:33.478000-08:00"
            }
        ],
        "logs": {
            "groupName": "group",
            "streamName": "stream/0103e0e7-52aa-4a3d-81dd-bfc27226fa54",
            "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream$252F0103e0e7-52aa-4a3d-81dd-bfc27226fa54",
            "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/0103e0e7-52aa-4a3d-81dd-bfc27226fa54.gz?region=us-west-2",
            "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream/0103e0e7-52aa-4a3d-81dd-bfc27226fa54",
            "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/0103e0e7-52aa-4a3d-81dd-bfc27226fa54.gz",
            "cloudWatchLogs": {
                "status": "ENABLED",
                "groupName": "group",
                "streamName": "stream"
            },
            "s3Logs": {
                "status": "ENABLED",
                "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs",
                "encryptionDisabled": false
            }
        }
    }
}
```

------

### 啟動命令執行 (AWS CLI)
<a name="sandbox-cli.start-command-execution"></a>

------
#### [ CLI command ]

```
aws codebuild start-command-execution --command $COMMAND --type $TYPE --sandbox-id $SANDBOX-ID
```
+ `--command` ：需要執行的命令。
+ `--sandbox-id` ： `sandboxId`或 `sandboxArn`。
+ `--type` ：命令類型 `SHELL`。

------
#### [ Sample request ]

```
aws codebuild start-command-execution --command "echo "Hello World"" --type SHELL --sandbox-id "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name
```

------
#### [ Sample response ]

```
{
    "id": "e1c658c2-02bb-42a8-9abb-94835241fcd6",
    "sandboxId": "f7126a4a-b0d5-452f-814c-fea73718f805",
    "submitTime": "2025-02-06T20:12:02.683000-08:00",
    "status": "SUBMITTED",
    "command": "echo \"Hello World\"",
    "type": "SHELL",
    "logs": {
        "groupName": "group",
        "streamName": "stream",
        "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream",
        "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/f7126a4a-b0d5-452f-814c-fea73718f805.gz?region=us-west-2",
        "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream",
        "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/f7126a4a-b0d5-452f-814c-fea73718f805.gz",
        "cloudWatchLogs": {
            "status": "ENABLED",
            "groupName": "group",
            "streamName": "stream"
        },
        "s3Logs": {
            "status": "ENABLED",
            "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs",
            "encryptionDisabled": false
        }
    }
}
```

------

### 取得命令執行的相關資訊 (AWS CLI)
<a name="sandbox-cli.batch-get-command-executions"></a>

------
#### [ CLI command ]

```
aws codebuild batch-get-command-executions --command-execution-ids $COMMAND-IDs --sandbox-id $SANDBOX-IDs
```
+ `--command-execution-ids` ：逗號分隔的 清單`commandExecutionIds`。
+ `--sandbox-id` ： `sandboxId`或 `sandboxArn`。

------
#### [ Sample request ]

```
aws codebuild batch-get-command-executions --command-execution-ids"c3c085ed-5a8f-4531-8e95-87d547f27ffd" --sandbox-id "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name"
```

------
#### [ Sample response ]

```
{
    "commandExecutions": [{
        "id": "c3c085ed-5a8f-4531-8e95-87d547f27ffd",
        "sandboxId": "cd71e456-2a4c-4db4-ada5-da892b0bba05",
        "submitTime": "2025-02-10T20:18:17.118000-08:00",
        "startTime": "2025-02-10T20:18:17.939000-08:00",
        "endTime": "2025-02-10T20:18:17.976000-08:00",
        "status": "SUCCEEDED",
        "command": "echo \"Hello World\"",
        "type": "SHELL",
        "exitCode": "0",
        "standardOutputContent": "Hello World\n",
        "logs": {
            "groupName": "group",
            "streamName": "stream",
            "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream",
            "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/cd71e456-2a4c-4db4-ada5-da892b0bba05.gz?region=us-west-2",
            "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream",
            "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/cd71e456-2a4c-4db4-ada5-da892b0bba05.gz",
            "cloudWatchLogs": {
                "status": "ENABLED",
                "groupName": "group",
                "streamName": "stream"
            },
            "s3Logs": {
                "status": "ENABLED",
                "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs",
                "encryptionDisabled": false
            }
        }
    }],
    "commandExecutionsNotFound": []
}
```

------

### 列出沙盒的命令執行 (AWS CLI)
<a name="sandbox-cli.list-command-executions-for-sandbox"></a>

------
#### [ CLI command ]

```
aws codebuild list-command-executions-for-sandbox --sandbox-id $SANDBOX-ID --next-token $NEXT_TOKEN --max-results $MAX_RESULTS --sort-order $SORT_ORDER
```
+ `--next-token` ：下一個字符，如果有的話，以取得分頁結果。您將從先前執行的清單沙盒取得此值。
+ `--max-results` ：（選用） 要擷取的沙盒記錄數目上限。
+ `--sort-order` ：應擷取沙盒記錄的順序。

------
#### [ Sample request ]

```
aws codebuild list-command-executions-for-sandbox --sandbox-id "arn:aws:codebuild:us-west-2:962803963624:sandbox/project-name"
```

------
#### [ Sample response ]

```
{
    "commandExecutions": [{
            "id": "aad6687e-07bc-45ab-a1fd-f5440229b528",
            "sandboxId": "cd71e456-2a4c-4db4-ada5-da892b0bba05",
            "submitTime": "2025-02-10T20:18:35.304000-08:00",
            "startTime": "2025-02-10T20:18:35.615000-08:00",
            "endTime": "2025-02-10T20:18:35.651000-08:00",
            "status": "FAILED",
            "command": "fail command",
            "type": "SHELL",
            "exitCode": "127",
            "standardErrContent": "/codebuild/output/tmp/script.sh: 4: fail: not found\n",
            "logs": {
                "groupName": "group",
                "streamName": "stream",
                "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream",
                "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/cd71e456-2a4c-4db4-ada5-da892b0bba05.gz?region=us-west-2",
                "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream",
                "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/cd71e456-2a4c-4db4-ada5-da892b0bba05.gz",
                "cloudWatchLogs": {
                    "status": "ENABLED",
                    "groupName": "group",
                    "streamName": "stream"
                },
                "s3Logs": {
                    "status": "ENABLED",
                    "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs",
                    "encryptionDisabled": false
                }
            }
        },
        {
            "id": "c3c085ed-5a8f-4531-8e95-87d547f27ffd",
            "sandboxId": "cd71e456-2a4c-4db4-ada5-da892b0bba05",
            "submitTime": "2025-02-10T20:18:17.118000-08:00",
            "startTime": "2025-02-10T20:18:17.939000-08:00",
            "endTime": "2025-02-10T20:18:17.976000-08:00",
            "status": "SUCCEEDED",
            "command": "echo \"Hello World\"",
            "type": "SHELL",
            "exitCode": "0",
            "standardOutputContent": "Hello World\n",
            "logs": {
                "groupName": "group",
                "streamName": "stream",
                "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logsV2:log-groups/log-group/group/log-events/stream",
                "s3DeepLink": "https://s3.console.aws.amazon.com/s3/object/codefactory-test-pool-1-us-west-2-beta-default-build-logs/cd71e456-2a4c-4db4-ada5-da892b0bba05.gz?region=us-west-2",
                "cloudWatchLogsArn": "arn:aws:logs:us-west-2:962803963624:log-group:group:log-stream:stream",
                "s3LogsArn": "arn:aws:s3:::codefactory-test-pool-1-us-west-2-beta-default-build-logs/cd71e456-2a4c-4db4-ada5-da892b0bba05.gz",
                "cloudWatchLogs": {
                    "status": "ENABLED",
                    "groupName": "group",
                    "streamName": "stream"
                },
                "s3Logs": {
                    "status": "ENABLED",
                    "location": "codefactory-test-pool-1-us-west-2-beta-default-build-logs",
                    "encryptionDisabled": false
                }
            }
        }
    ]
}
```

------

### 列出沙盒 (AWS CLI)
<a name="sandbox-cli.list-sandboxes"></a>

------
#### [ CLI command ]

```
aws codebuild list-sandboxes --next-token $NEXT_TOKEN --max-results $MAX_RESULTS --sort-order $SORT_ORDER
```

------
#### [ Sample request ]

```
aws codebuild list-sandboxes
```

------
#### [ Sample response ]

```
{
    "ids": [
        "s3-log-project-integ-test-temp173925062814985d64e0f-7880-41df-9a3c-fb6597a266d2:827a5243-0841-4b69-a720-4438796f6967",
        "s3-log-project-integ-test-temp1739249999716bbd438dd-8bb8-47bd-ba6b-0133ac65b3d3:e2fa4eab-73af-42e3-8903-92fddaf9f378",
        "s3-log-project-integ-test-temp17392474779450fbdacc2-2d6e-4190-9ad5-28f891bb7415:cd71e456-2a4c-4db4-ada5-da892b0bba05",
        "s3-log-project-integ-test-temp17392246284164301421c-5030-4fa1-b4d3-ca15e44771c5:9e26ab3f-65e4-4896-a19c-56b1a95e630a",
        "s3-log-project-integ-test-temp173921367319497056d8d-6d8e-4f5a-a37c-a62f5686731f:22d91b06-df1e-4e9c-a664-c0abb8d5920b",
        "s3-log-project-integ-test-temp1739213439503f6283f19-390c-4dc8-95a9-c8480113384a:82cc413e-fc46-47ab-898f-ae23c83a613f",
        "s3-log-project-integ-test-temp1739054385570b1f1ddc2-0a23-4062-bd0c-24e9e4a99b99:c02562f3-2396-42ec-98da-38e3fe5da13a",
        "s3-log-project-integ-test-temp173905400540237dab1ac-1fde-4dfb-a8f5-c0114333dc89:d2f30493-f65e-4fa0-a7b6-08a5e77497b9",
        "s3-log-project-integ-test-temp17390534055719c534090-7bc4-48f1-92c5-34acaec5bf1e:df5f1c8a-f017-43b7-91ba-ad2619e2c059",
        "s3-log-project-integ-test-temp1739052719086a61813cc-ebb9-4db4-9391-7f43cc984ee4:d61917ec-8037-4647-8d52-060349272c4a",
        "s3-log-project-integ-test-temp173898670094078b67edb-c42f-42ed-9db2-4b5c1a5fc66a:ce33dfbc-beeb-4466-8c99-a3734a0392c7",
        "s3-log-project-integ-test-temp17389863425584d21b7cd-32e2-4f11-9175-72c89ecaffef:046dadf0-1f3a-4d51-a2c0-e88361924acf",
        "s3-log-project-integ-test-temp1738985884273977ccd23-394b-46cc-90d3-7ab94cf764dc:0370dc41-9339-4b0a-91ed-51929761b244",
        "s3-log-project-integ-test-temp1738985365972241b614f-8e41-4387-bd25-2b8351fbc9e0:076c392a-9630-47d8-85a9-116aa34edfff",
        "s3-log-project-integ-test-temp1738985043988a51a9e2b-09d6-4d24-9c3c-1e6e21ac9fa8:6ea3949c-435b-4177-aa4d-614d5956244c",
        "s3-log-project-integ-test-temp1738984123354c68b31ad-49d1-4f4b-981d-b66c00565ff6:6c3fff6c-815b-48b5-ada3-737400a6dee8",
        "s3-log-project-integ-test-temp1738977263715d4d5bf6c-370a-48bf-8ea6-905358a6cf92:968a0f54-724a-42d1-9207-6ed854b2fae8",
        "s3-log-project-integ-test-temp173897358796816ce8d7d-2a5e-41ef-855b-4a94a8d2795d:80f9a7ce-930a-402e-934e-d8b511d68b04",
        "s3-log-project-integ-test-temp17389730633301af5e452-0966-467c-b684-4e36d47f568c:cabbe989-2e8a-473c-af25-32edc8c28646",
        "s3-log-project-integ-test-temp1738901503813173fd468-b723-4d7b-9f9f-82e88d17f264:f7126a4a-b0d5-452f-814c-fea73718f805",
        "s3-log-project-integ-test-temp1738890502472c13616fb-bd0f-4253-86cc-28b74c97a0ba:c6f197e5-3a53-45b6-863e-0e6353375437",
        "s3-log-project-integ-test-temp17388903044683610daf3-8da7-43c6-8580-9978432432ce:d20aa317-8838-4966-bbfc-85b908213df1",
        "s3-log-project-integ-test-temp173888857196780b5ab8b-e54b-44fd-a222-c5a374fffe96:ab4b9970-ffae-47a0-b3a8-7b6790008cad",
        "s3-log-project-integ-test-temp1738888336931c11d378d-e74d-49a4-a723-3b92e6f7daac:4922f0e8-9b7d-4119-9c9f-115cd85e703e",
        "s3-log-project-integ-test-temp17388881717651612a397-c23f-4d88-ba87-2773cd3fc0c9:be91c3fc-418e-4feb-8a3a-ba58ff8f4e8a",
        "s3-log-project-integ-test-temp17388879727174c3c62ed-6195-4afb-8a03-59674d0e1187:a48826a8-3c0d-43c5-a1b5-1c98a0f978e9",
        "s3-log-project-integ-test-temp1738885948597cef305e4-b8b4-46b0-a65b-e2d0a7b83294:c050e77d-e3f8-4829-9a60-46149628fe96",
        "s3-log-project-integ-test-temp173888561463001a7d2a8-e4e4-4434-94db-09d3da9a9e17:8c3ac3f5-7111-4297-aec9-2470d3ead873",
        "s3-log-project-integ-test-temp1738869855076eb19cafd-04fe-41bd-8aa0-40826d0c0d27:d25be134-05cb-404a-85da-ac5f85d2d72c",
        "s3-project-integ-test-temp1738868157467148eacfc-d39b-49fc-a137-e55381cd2978:4909557b-c221-4814-b4b6-7d9e93d37c35",
        "s3-project-integ-test-temp1738820926895abec0af2-e33d-473c-9cf4-2122dd9d6876:8f5cf218-71d6-40a4-a4be-6cacebd7765f",
        "s3-project-integ-test-temp173881998877574f969a6-1c2e-4441-b463-ab175b45ce32:04396851-c901-4986-9117-585528e3877f",
        "s3-project-integ-test-temp17388189812309abd2604-29ba-4cf6-b6bf-073207b7db9c:540075c7-f5ec-41e8-9341-2233c09247eb",
        "s3-project-integ-test-temp1738818843474d3ea9ac1-b609-461b-bbdb-2da245c9bc96:865d4c3c-fbfe-4ece-9c92-d0c928341404",
        "s3-project-integ-test-temp1738818542236006e9169-e6d9-4344-9b59-f557e7aec619:1f9ffa87-da15-4290-83e2-eebdd877497b",
        "s3-project-integ-test-temp173881809557486ad11fd-7931-48d7-81d5-499cea52a6bc:c4c2efc4-685f-4e13-8b0f-1ef85ec300b1",
        "s3-project-integ-test-temp173881794103322941020-3f0b-49c3-b836-fcd818ec9484:0344cfba-de48-456d-b2a8-6566bd4a5d6e",
        "s3-project-integ-test-temp1738817680747b93d0d0b-ea16-497f-9559-af25ee6dcfdf:654a3a55-d92a-4dc6-8da8-56fd4d40d7e1",
        "s3-project-integ-test-temp17388174027191255c3da-086c-4270-b047-acac0b7bee0d:b7e82740-2c69-42fc-ab5a-dbf15bc016a1",
        "s3-project-integ-test-temp1738817099799016e7fa3-b9b5-46a2-bcd5-0888c646743f:8705a6a4-79ff-427a-a1c3-85c4e8fe462e",
        "s3-project-integ-test-temp1738816479281bb0c3606-5ebf-4623-bed5-12b60e9d3512:f23fc74b-a981-4835-8e28-375fcd4c99e4",
        "s3-project-integ-test-temp1738816263585c939a133-4d37-482c-9238-1dbff34b7674:ca28e234-0045-4ae6-8732-938b17597f50",
        "s3-project-integ-test-temp173881580873072d18733-8fe4-43b1-83f7-95f25bb27ccf:c6f0f55b-5736-47c7-a3aa-1b8461a6d5ed"
    ]
}
```

------

# 教學課程：使用 SSH 連線至沙盒
<a name="sandbox-ssh-tutorial"></a>

本教學課程說明如何使用 SSH 用戶端連線至 CodeBuild 沙盒。

若要完成此教學課程，您必須先：
+ 確保您有現有的 AWS CodeBuild 專案。
+ 為您的 CodeBuild 專案角色設定適當的 IAM 許可。
+  AWS CLI 在本機電腦上安裝和設定 。

## 步驟 1：啟動沙盒
<a name="sandbox-ssh-tutorial.start-sandbox"></a>

**在主控台中啟動 CodeBuild 沙盒**

1. 在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1. 在導覽窗格中，選擇 **Build projects (建置專案)**。選擇建置專案，然後選擇**偵錯建置**。  
![\[主控台中的建置專案詳細資訊頁面。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/project-debug-build.png)

1. 在 **SSH 用戶端**索引標籤中，選擇**啟動沙盒**。  
![\[主控台中具有「啟動沙盒」按鈕的「SSH 用戶端」索引標籤。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/ssh-client-sandbox.png)

1. 沙盒初始化程序可能需要一些時間。當沙盒的狀態變更為 時，您可以連線到沙盒`RUN_SANDDBOX`。  
![\[狀態變更為 "RUN_SANDDBOX" 之後的 SSH 沙盒連線。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/run-sandbox.png)

## 步驟 2：修改本機 SSH 組態
<a name="sandbox-ssh-tutorial.modify-ssh"></a>

如果您是第一次連接到沙盒，則需要使用下列步驟執行一次性設定程序：

**在主控台中修改本機 SSH 組態**

1. 尋找您作業系統的設定命令。

1. 開啟您的本機終端機，然後複製並執行提供的命令，以下載並執行指令碼來設定本機 SSH 組態。例如，如果您的作業系統是 macOS，請使用下列命令：  
![\[主控台中 CodeBuild 沙盒的 SSH 連線 macOS 命令。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/modify-ssh-macOS.png)

1. 組態指令碼會新增連接到沙盒所需的組態。系統會提示您接受這些變更。

1. 成功組態後，將建立新的 CodeBuild 沙盒 SSH 組態項目。  
![\[成功的 SSH 沙盒連線。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/ssh-terminal-success.png)

## 步驟 3：連線至沙盒
<a name="sandbox-ssh-tutorial.connect-sandbox"></a>

**在主控台中修改本機 SSH 組態**

1. 設定 AWS CLI 身分驗證，並確保您的 AWS CLI 使用者具有 `codebuild:StartSandboxConnection`許可。如需詳細資訊，請參閱《 第 *AWS 1 版命令列界面使用者指南*》中的[使用 的 IAM 使用者憑證進行身分驗證 AWS CLI](https://docs.aws.amazon.com/cli/v1/userguide/cli-authentication-user.html)。

1. 使用下列命令連線至沙盒：

   ```
   ssh codebuild-sandbox-ssh=arn:aws:codebuild:us-east-1:<account-id>:sandbox/<sandbox-id>
   ```
**注意**  
若要對連線失敗進行故障診斷，請使用 `-v`旗標來啟用詳細輸出。例如 `ssh -v codebuild-sandbox-ssh=arn:aws:codebuild:us-east-1:<account-id>:sandbox/<sandbox-id>`。  
如需其他故障診斷指引，請參閱 [對 AWS CodeBuild 沙盒 SSH 連線問題進行故障診斷](sandbox-troubleshooting.md)。

## 步驟 4：檢閱您的結果
<a name="sandbox-ssh-tutorial.review-results"></a>

連線後，您就可以偵錯建置失敗、測試建置命令、試驗組態變更，以及使用沙盒驗證環境變數和相依性。

# 對 AWS CodeBuild 沙盒 SSH 連線問題進行故障診斷
<a name="sandbox-troubleshooting"></a>

使用本主題中的資訊來協助您識別、診斷和解決 CodeBuild 沙盒 SSH 連線問題。

**Topics**
+ [

## `StartSandboxConnection` `InvalidInputException` SSH 進入 CodeBuild 沙盒環境時發生錯誤
](#sandbox-troubleshooting.invalid-input)
+ [

## 錯誤：當 SSH 進入 CodeBuild 沙盒環境時，「找不到登入資料」
](#sandbox-troubleshooting.credentials)
+ [

## `StartSandboxConnection` `AccessDeniedException` SSH 進入 CodeBuild 沙盒環境時發生錯誤
](#sandbox-troubleshooting.access-denied)
+ [

## 錯誤：當 SSH 進入 CodeBuild 沙盒環境時，「ssh：無法解析主機名稱」
](#sandbox-troubleshooting.hostname)

## `StartSandboxConnection` `InvalidInputException` SSH 進入 CodeBuild 沙盒環境時發生錯誤
<a name="sandbox-troubleshooting.invalid-input"></a>

**問題：**嘗試使用命令 連線至 CodeBuild 沙盒環境時`ssh codebuild-sandbox-ssh=<sandbox-arn>`，您可能會遇到`InvalidInputException`錯誤，例如：

```
An error occurred (InvalidInputException) when calling the StartSandboxConnection 
operation: Failed to start SSM session for {sandbox-arn}
User: arn:aws:sts::<account-ID>:assumed-role/<service-role-name>/AWSCodeBuild-<UUID> 
is not authorized to perform: ssm:StartSession on resource.
```

```
An error occurred (InvalidInputException) when calling the StartSandboxConnection 
operation: Failed to start SSM session for 
sandbox <sandbox-arn>: codebuild:<UUID> is not connected.
```

**可能原因：**
+ 缺少 Amazon EC2 Systems Manager 代理程式：建置映像未正確安裝或設定 SSM 代理程式。
+ 許可不足：CodeBuild 專案服務角色缺少必要的 SSM 許可。

**建議的解決方案：**如果您使用建置的自訂映像，請執行下列動作。

1. 安裝 SSM Agent。如需詳細資訊，請參閱《》中的在 [ Linux 的 Amazon EC2 執行個體上手動安裝和解除安裝 SSM 代理](https://docs.aws.amazon.com/systems-manager/latest/userguide/manually-install-ssm-agent-linux.html)程式**。SSM Agent 版本必須為 `3.0.1295.0`或更新版本。

1. 將檔案 [ https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/7.0/amazon-ssm-agent.json](https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/7.0/amazon-ssm-agent.json) 複製到映像中的 `/etc/amazon/ssm/` 目錄。這會在 SSM 代理程式中啟用**容器模式**。

1. 確保您的 CodeBuild 專案的服務角色具有下列許可，然後重新啟動沙盒環境：

   ```
   {
      "Effect": "Allow",
         "Action": [
            "ssmmessages:CreateControlChannel",
            "ssmmessages:CreateDataChannel",
            "ssmmessages:OpenControlChannel",
            "ssmmessages:OpenDataChannel"
         ],
         "Resource": "*"
    },
    {
       "Effect": "Allow",
       "Action": [
          "ssm:StartSession"
        ],
        "Resource": [
           "arn:aws:codebuild:region:account-id:build/*",
           "arn:aws:ssm:region::document/AWS-StartSSHSession"
        ]
    }
   ```

## 錯誤：當 SSH 進入 CodeBuild 沙盒環境時，「找不到登入資料」
<a name="sandbox-troubleshooting.credentials"></a>

**問題：**嘗試使用命令 連線至 CodeBuild 沙盒環境時`ssh codebuild-sandbox-ssh=<sandbox-arn>`，您可能會遇到下列登入資料錯誤：

```
Unable to locate credentials. You can configure credentials by running 
"aws configure".
```

**可能的原因：** AWS 憑證尚未在您的本機環境中正確設定。

**建議的解決方案：**遵循 第 *AWS 2 版命令列界面使用者指南*中的官方文件：[設定 的設定 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)，以設定您的 AWS CLI 登入資料。

## `StartSandboxConnection` `AccessDeniedException` SSH 進入 CodeBuild 沙盒環境時發生錯誤
<a name="sandbox-troubleshooting.access-denied"></a>

**問題：**嘗試使用命令 連線至 CodeBuild 沙盒環境時`ssh codebuild-sandbox-ssh=<sandbox-arn>`，您可能會遇到下列許可錯誤：

```
An error occurred (AccessDeniedException) when calling the StartSandboxConnection 
operation: 
User: arn:aws:sts::account-id:assumed-role/role-name
is not authorized to perform: codebuild:StartSandboxConnection on resource: 
sandbox-arn
because no identity-based policy allows the codebuild:StartSandboxConnection action
```

**可能原因：**您的 AWS 登入資料缺少執行此操作所需的 CodeBuild 許可。

**建議的解決方案：**確保與您的 AWS CLI 登入資料相關聯的 IAM 使用者或角色具有下列許可：

```
{
    "Effect": "Allow",
    "Action": [
       "codebuild:StartSandboxConnection"
     ],
     "Resource": [
        "arn:aws:codebuild:region:account-id:sandbox/*"
     ]
}
```

## 錯誤：當 SSH 進入 CodeBuild 沙盒環境時，「ssh：無法解析主機名稱」
<a name="sandbox-troubleshooting.hostname"></a>

**問題：**嘗試使用命令 連線至 CodeBuild 沙盒環境時`ssh codebuild-sandbox-ssh=<sandbox-arn>`，您遇到下列主機名稱解析錯誤：

```
ssh: Could not resolve hostname
```

**可能原因：**當本機環境中未正確執行所需的 CodeBuild 沙盒連線指令碼時，通常會發生此錯誤。

**建議解決方案：**

1. 下載 CodeBuild 沙盒連線指令碼。

1. 在終端機中執行指令碼，以建立必要的 SSH 組態。

1. 重試 SSH 連線至沙盒環境。

# 使用 Session Manager 偵錯組建
<a name="session-manager"></a>

在 中 AWS CodeBuild，您可以暫停執行中的組建，然後使用 AWS Systems Manager Session Manager 連線到組建容器，並檢視容器的狀態。

**注意**  
此功能不適用於 Windows 環境。

**Topics**
+ [

## 先決條件
](#ssm.prerequisites)
+ [

## 暫停建置
](#ssm-pause-build)
+ [

## 啟動建置
](#ssm-start-build)
+ [

## 連線至建置容器
](#ssm-connect)
+ [

## 繼續建置
](#ssm-resume-build)

## 先決條件
<a name="ssm.prerequisites"></a>

若要允許 Session Manager 與建置工作階段搭配使用，您必須啟用建置的工作階段連線。有兩個先決條件：
+ CodeBuild Linux 標準精選映像已安裝 SSM 代理程式並啟用 SSM 代理程式 ContainerMode。

  如果您使用建置的自訂映像，請執行下列動作：

  1. 安裝 SSM Agent。如需詳細資訊，請參閱 AWS Systems Manager 《 使用者指南》中的在 [Linux 的 EC2 執行個體上手動安裝 SSM 代理](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-manual-agent-install.html)程式。SSM Agent 版本必須為 3.0.1295.0 或更新版本。

  1. 將檔案 [https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.0/amazon-ssm-agent.json](https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.0/amazon-ssm-agent.json) 複製到映像中的 `/etc/amazon/ssm/` 目錄。這會在 SSM 代理程式中啟用容器模式。
**注意**  
自訂映像需要最新 SSM 代理程式，此功能才能如預期運作。
+ CodeBuild 服務角色必須具有下列 SSM 政策：

------
#### [ JSON ]

****  

  ```
  {
     "Version":"2012-10-17",		 	 	  
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
            "ssmmessages:CreateControlChannel",
            "ssmmessages:CreateDataChannel",
            "ssmmessages:OpenControlChannel",
            "ssmmessages:OpenDataChannel"
         ],
         "Resource": "*"
       }
     ]
  }
  ```

------

  您可以在啟動建置時，讓 CodeBuild 主控台自動將此政策連接至您的服務角色。或者，您可以手動將此政策連接至您的服務角色。
+ 如果您在 Systems Manager 偏好設定中已啟用**稽核和記錄工作階段活動**，則 CodeBuild 服務角色也必須具有其他許可。許可不同，取決於日誌的存放位置。  
CloudWatch Logs  
如果使用 CloudWatch Logs 存放日誌，請將下列許可新增至 CodeBuild 服務角色：    
****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Effect": "Allow",
              "Action": "logs:DescribeLogGroups",
              "Resource": "arn:aws:logs:us-east-1:111122223333:log-group:*:*"
          },
          {
              "Effect": "Allow",
              "Action": [
                  "logs:CreateLogStream",
                  "logs:PutLogEvents"
              ],
              "Resource": "arn:aws:logs:us-east-1:111122223333:log-group:MyLogGroup:*"
          }
      ]
  }
  ```  
Amazon S3  
如果使用 Amazon S3 存放日誌，請將下列許可新增至 CodeBuild 服務角色：    
****  

  ```
  {
    "Version":"2012-10-17",		 	 	 
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "s3:GetEncryptionConfiguration",
          "s3:PutObject"
        ],
        "Resource": [
          "arn:aws:s3:::<bucket-name>",
          "arn:aws:s3:::<bucket-name>/*"
        ]
      }
    ]
  }
  ```

  如需詳細資訊，請參閱*AWS Systems Manager 《 使用者指南*》中的[稽核和記錄工作階段活動](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-logging-auditing.html)。

## 暫停建置
<a name="ssm-pause-build"></a>

若要暫停建置，請在 buildspec 檔案中的任何建置階段插入 **codebuild-breakpoint**命令。建置將在此時暫停，這可讓您連線至建置容器，並檢視其目前狀態的容器。

例如，將下列項目新增至 buildspec 檔案中的建置階段。

```
phases:
  pre_build:
    commands:
      - echo Entered the pre_build phase...
      - echo "Hello World" > /tmp/hello-world
      - codebuild-breakpoint
```

此程式碼會建立 `/tmp/hello-world` 檔案，然後在此時暫停建置。

## 啟動建置
<a name="ssm-start-build"></a>

若要允許 Session Manager 與建置工作階段搭配使用，您必須啟用建置的工作階段連線。若要這樣做，在開始建置時，請依照下列步驟執行：

1. 在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1. 在導覽窗格中，選擇 **Build projects (建置專案)**。選擇建置專案，然後選擇**使用覆寫開始建置**。

1. 選擇 **Advanced build overrides (進階組建覆寫)**。

1. 在**環境**區段中，選擇**啟用工作階段連線**選項。如果未選取此選項，則會忽略所有 **codebuild-breakpoint**和 **codebuild-resume**命令。

1. 進行任何其他所需的變更，然後選擇**開始建置**。

1. 在 主控台中監控建置狀態。當工作階段可用時，**AWS 工作階段管理員**連結會出現在**建置狀態**區段中。

## 連線至建置容器
<a name="ssm-connect"></a>

您可以透過下列兩種方式之一連線到建置容器：

CodeBuild 主控台  
在 Web 瀏覽器中，開啟 **AWS Session Manager** 連結以連線至建置容器。終端機工作階段隨即開啟，可讓您瀏覽和控制建置容器。

AWS CLI  
您的本機電腦必須安裝此程序的 Session Manager 外掛程式。如需詳細資訊，請參閱 AWS Systems Manager 《 使用者指南》中的[安裝 CLI AWS 的 Session Manager 外掛程式](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)。

1. 使用組建 ID 呼叫 **batch-get-builds** api 以取得組建的相關資訊，包括工作階段目標識別符。工作階段目標識別符屬性名稱會根據`aws`命令的輸出類型而有所不同。這就是`--output json`將 新增至命令的原因。

   ```
   aws codebuild batch-get-builds --ids <buildID> --region <region> --output json
   ```

1. 複製 `sessionTarget` 屬性值。`sessionTarget` 屬性名稱可能會因`aws`命令的輸出類型而有所不同。這就是為什麼 `--output json` 會新增至上一個步驟中的 命令。

1. 使用下列命令來連線至建置容器。

   ```
   aws ssm start-session --target <sessionTarget> --region <region>
   ```

在此範例中，請確認`/tmp/hello-world`檔案存在且包含文字 `Hello World`。

## 繼續建置
<a name="ssm-resume-build"></a>

完成檢查建置容器後，請從容器 Shell 發出 **codebuild-resume**命令。

```
$ codebuild-resume
```

# 在 中刪除組建 AWS CodeBuild
<a name="delete-builds"></a>

您可以使用 AWS CLI 或 AWS SDKs 來刪除 中的組建 AWS CodeBuild。

**Topics**
+ [

## 刪除建置 (AWS CLI)
](#delete-builds-cli)
+ [

## 刪除組建 (AWS SDKs)
](#delete-builds-sdks)

## 刪除建置 (AWS CLI)
<a name="delete-builds-cli"></a>

執行 `batch-delete-builds` 命令：

```
aws codebuild batch-delete-builds --ids ids
```

在上述命令中，取代下列預留位置：
+ *ids*：必要的字串。要刪除的組建 ID。若要指定多個組建，請以空格將每個組建 ID 分開。若要取得建置 ID 的清單，請參閱下列主題：
  + [檢視建置 ID 清單 (AWS CLI)](view-build-list.md#view-build-list-cli)
  + [檢視建置專案的建置 ID 清單 (AWS CLI)](view-builds-for-project.md#view-builds-for-project-cli)

如果成功，輸出中會出現 `buildsDeleted` 陣列，其中包含成功刪除之每個組建的 Amazon Resource Name (ARN)。未成功刪除之組建的相關資訊會出現在輸出中的 `buildsNotDeleted` 陣列內。

例如，如果您執行此命令：

```
aws codebuild batch-delete-builds --ids my-demo-build-project:f8b888d2-5e1e-4032-8645-b115195648EX my-other-demo-build-project:a18bc6ee-e499-4887-b36a-8c90349c7eEX
```

類似下列內容的資訊會顯示在輸出中：

```
{
  "buildsNotDeleted": [
    {
      "id": "arn:aws:codebuild:us-west-2:123456789012:build/my-demo-build-project:f8b888d2-5e1e-4032-8645-b115195648EX",
      "statusCode": "BUILD_IN_PROGRESS"
    }
  ], 
  "buildsDeleted": [
    "arn:aws:codebuild:us-west-2:123456789012:build/my-other-demo-build-project:a18bc6ee-e499-4887-b36a-8c90349c7eEX"
  ]
}
```

## 刪除組建 (AWS SDKs)
<a name="delete-builds-sdks"></a>

如需 AWS CodeBuild 搭配 AWS SDKs 使用 的詳細資訊，請參閱 [AWS SDKs和工具參考](sdk-ref.md)。

# 在 中手動重試建置 AWS CodeBuild
<a name="retry-build"></a>

您可以使用 AWS CodeBuild 主控台 AWS CLI，或 AWS SDKs手動重試單一建置或批次建置 AWS CodeBuild。

**Topics**
+ [

## 手動重試組建 （主控台）
](#retry-build-console)
+ [

## 手動重試組建 (AWS CLI)
](#retry-build-cli)
+ [

## 手動重試組建 (AWS SDKs)
](#retry-build-sdks)

## 手動重試組建 （主控台）
<a name="retry-build-console"></a>

1. 在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1. 執行以下任意一項：
   + 如果顯示 ***build-project-name*：*build-ID*** 頁面，請選擇**重試建置**。
   + 在導覽窗格中，選擇 **Build history (組建歷史記錄)**。在組建清單中，選取組建的方塊，然後選擇**重試組建**。
   + 在導覽窗格中，選擇 **Build projects (建置專案)**。在組建專案清單中的 **Name (名稱)** 欄中，選擇組建專案名稱的連結。在組建清單中，選取組建的方塊，然後選擇**重試組建**。

**注意**  
根據預設，只會顯示最新 100 個組建或組建專案。若要檢視更多組建或組建專案，請選擇齒輪圖示，然後針對 **Builds per page (每頁顯示組建數)** 或 **Projects per page (每頁顯示專案數)** 選擇不同的值，或使用向前和向後箭頭。

## 手動重試組建 (AWS CLI)
<a name="retry-build-cli"></a>
+ 執行 **retry-build** 命令：

  ```
  aws codebuild retry-build --id <build-id> --idempotency-token <idempotencyToken>
  ```

  在上述命令中，取代下列預留位置：
  + *<build-id>*：必要字串。要重試的建置或批次建置 ID。若要取得建置 ID 的清單，請參閱下列主題：
    + [檢視建置 ID 清單 (AWS CLI)](view-build-list.md#view-build-list-cli)
    + [檢視批次建置 IDs的清單 (AWS CLI)](view-build-list.md#view-batch-build-list-cli)
    + [檢視建置專案的建置 ID 清單 (AWS CLI)](view-builds-for-project.md#view-builds-for-project-cli)
    + [檢視組建專案的批次組建 IDs 清單 (AWS CLI)](view-builds-for-project.md#view-batch-builds-for-project-cli)
  + `--idempotency-token`：選用。如果您使用 選項執行 **retry-build**命令，`retry-build`則請求中會包含唯一的區分大小寫識別符或字符。此字符在 請求之後的 5 分鐘內有效。如果您使用相同的字符重複`retry-build`請求，但變更參數，CodeBuild 會傳回參數不相符錯誤。

## 手動重試組建 (AWS SDKs)
<a name="retry-build-sdks"></a>

如需 AWS CodeBuild 搭配 AWS SDKs 使用 的詳細資訊，請參閱 [AWS SDKs和工具參考](sdk-ref.md)。

# 在 中自動重試建置 AWS CodeBuild
<a name="auto-retry-build"></a>

您可以使用 AWS CodeBuild 主控台 AWS CLI或 AWS SDKs 自動重試您的建置 AWS CodeBuild。啟用自動重試後，CodeBuild 會在失敗的建置達到指定的限制後`RetryBuild`，使用專案的服務角色自動呼叫 。例如，如果自動重試限制設為 2，CodeBuild 將呼叫 `RetryBuild` API 以自動重試您的組建最多兩次。

**注意**  
CodeBuild 不支援 CodePipeline 的自動重試。

**Topics**
+ [

## 自動重試組建 （主控台）
](#auto-retry-build-console)
+ [

## 自動重試組建 (AWS CLI)
](#auto-retry-build-cli)
+ [

## 自動重試組建 (AWS SDKs)
](#auto-retry-build-sdks)

## 自動重試組建 （主控台）
<a name="auto-retry-build-console"></a>

1. 開啟 AWS CodeBuild 主控台，網址為 [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)：//。

1. 選擇**建立專案**。如需詳細資訊，請參閱 [建立組建專案 (主控台)](create-project.md#create-project-console) 及 [執行建置 (主控台)](run-build-console.md)。
   +  在 **Environment (環境)** 中：
     +  針對**自動重試限制**，輸入建置失敗後所需的自動重試次數上限。

1. 在**環境中**，選擇**其他組態**。

1. 繼續執行預設值，然後選擇**建立建置專案**。

## 自動重試組建 (AWS CLI)
<a name="auto-retry-build-cli"></a>
+ 執行 **create-project** 命令：

  ```
  aws codebuild create-project \
      --name "<project-name>" \
      --auto-retry-limit <auto-retry-limit> \
      --source "<source>" \
      --artifacts {<artifacts>} \
      --environment "{\"type\": \"environment-type>\",\"image\": \"image-type>\",\"computeType\": \"compute-type>\"}" \
      --service-role "service-role>"
  ```

  在上述命令中，取代下列預留位置：
  + *<auto-retry-limit>*：將自動重試限制設定為建置失敗後所需的自動重試次數上限。
  + *<project-name>*、*<source>*、*<artifacts>*、*environ-type>*、*image-type>*、*comput-type>* 和 *service-role>*：設定所需的專案組態設定。

## 自動重試組建 (AWS SDKs)
<a name="auto-retry-build-sdks"></a>

如需 AWS CodeBuild 搭配 AWS SDKs 使用 的詳細資訊，請參閱 [AWS SDKs和工具參考](sdk-ref.md)。

# 在 中停止建置 AWS CodeBuild
<a name="stop-build"></a>

您可以使用 AWS CodeBuild 主控台 AWS CLI，或 AWS SDKs來停止 中的建置 AWS CodeBuild。

**Topics**
+ [

## 停止建置 (主控台)
](#stop-build-console)
+ [

## 停止建置 (AWS CLI)
](#stop-build-cli)
+ [

## 停止建置 (AWS SDKs)
](#stop-build-sdks)

## 停止建置 (主控台)
<a name="stop-build-console"></a>

1. 開啟 AWS CodeBuild 主控台，網址為 [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)：//。

1. 執行以下任意一項：
   + 如果顯示 ***build-project-name*:*build-ID*** 頁面，請選擇 **Stop build (停止組建)**。
   + 在導覽窗格中，選擇 **Build history (組建歷史記錄)**。在組建清單中，選取組建的方塊，然後選擇 **Stop build (停止組建)**。
   + 在導覽窗格中，選擇 **Build projects (建置專案)**。在組建專案清單中的 **Name (名稱)** 欄中，選擇組建專案名稱的連結。在組建清單中，選取組建的方塊，然後選擇 **Stop build (停止組建)**。

**注意**  
根據預設，只會顯示最新 100 個組建或組建專案。若要檢視更多組建或組建專案，請選擇齒輪圖示，然後針對 **Builds per page (每頁顯示組建數)** 或 **Projects per page (每頁顯示專案數)** 選擇不同的值，或使用向前和向後箭頭。  
如果 AWS CodeBuild 無法成功停止建置 （例如，如果建置程序已完成），則會停用**停止**按鈕，否則可能不會顯示。

## 停止建置 (AWS CLI)
<a name="stop-build-cli"></a>
+ 執行 **stop-build** 命令：

  ```
  aws codebuild stop-build --id id
  ```

  在上述命令中，取代下列預留位置：
  + *id*：必要的字串。要停止的組建 ID。若要取得建置 ID 的清單，請參閱下列主題：
    + [檢視建置 ID 清單 (AWS CLI)](view-build-list.md#view-build-list-cli)
    + [檢視建置專案的建置 ID 清單 (AWS CLI)](view-builds-for-project.md#view-builds-for-project-cli)

  如果 AWS CodeBuild 成功停止建置，輸出中`build`物件中的`buildStatus`值為 `STOPPED`。

  如果 CodeBuild 無法成功停止組建 （例如，如果組建已完成），則輸出中`build`物件中的`buildStatus`值為最終組建狀態 （例如，`SUCCEEDED`)。

## 停止建置 (AWS SDKs)
<a name="stop-build-sdks"></a>

如需 AWS CodeBuild 搭配 AWS SDKs 使用 的詳細資訊，請參閱 [AWS SDKs和工具參考](sdk-ref.md)。

# 在 中停止批次建置 AWS CodeBuild
<a name="stop-batch-build"></a>

您可以使用 AWS CodeBuild 主控台 AWS CLI，或 AWS SDKs來停止 中的批次建置 AWS CodeBuild。

**注意**  
如果您在批次建置中使用 Lambda 運算，則無法停止進行中的 Lambda 建置。

**Topics**
+ [

## 停止批次建置 （主控台）
](#stop-batch-build-console)
+ [

## 停止批次建置 (AWS CLI)
](#stop-batch-build-cli)
+ [

## 停止批次建置AWS SDKs)
](#stop-batch-build-sdks)

## 停止批次建置 （主控台）
<a name="stop-batch-build-console"></a>

1. 開啟 AWS CodeBuild 主控台，網址為 [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)：//。

1. 執行以下任意一項：
   + 如果顯示 ***build-project-name*:*build-ID*** 頁面，請選擇 **Stop build (停止組建)**。
   + 在導覽窗格中，選擇 **Build history (組建歷史記錄)**。在組建清單中，選取組建的方塊，然後選擇 **Stop build (停止組建)**。
   + 在導覽窗格中，選擇 **Build projects (建置專案)**。在組建專案清單中的 **Name (名稱)** 欄中，選擇組建專案名稱的連結。在組建清單中，選取組建的方塊，然後選擇 **Stop build (停止組建)**。

**注意**  
根據預設，只會顯示最新 100 個組建或組建專案。若要檢視更多組建或組建專案，請選擇齒輪圖示，然後針對 **Builds per page (每頁顯示組建數)** 或 **Projects per page (每頁顯示專案數)** 選擇不同的值，或使用向前和向後箭頭。

## 停止批次建置 (AWS CLI)
<a name="stop-batch-build-cli"></a>
+ 執行 [https://docs.aws.amazon.com/cli/latest/reference/codebuild/stop-build-batch.html](https://docs.aws.amazon.com/cli/latest/reference/codebuild/stop-build-batch.html) 命令：

  ```
  aws codebuild stop-build-batch --id <batch-build-id>
  ```

  在上述命令中，取代下列預留位置：
  + *<batch-build-id>*：必要字串。要停止的批次建置識別符。若要取得批次建置識別符的清單，請參閱下列主題：
    + [檢視批次建置 IDs的清單 (AWS CLI)](view-build-list.md#view-batch-build-list-cli)
    + [檢視組建專案的批次組建 IDs 清單 (AWS CLI)](view-builds-for-project.md#view-batch-builds-for-project-cli)

## 停止批次建置AWS SDKs)
<a name="stop-batch-build-sdks"></a>

如需 AWS CodeBuild 搭配 AWS SDKs 使用 的詳細資訊，請參閱 [AWS SDKs和工具參考](sdk-ref.md)。

# 自動觸發 AWS CodeBuild 建置
<a name="build-triggers"></a>

您可以在專案上建立觸發來排定每小時、每天或每週執行一次組建。您也可以編輯觸發條件，以使用具有 Amazon CloudWatch Cron 表達式的自訂規則。例如，您可以使用 cron 表達式來排定在每個工作日的特定時間執行組建。如需建立和編輯觸發的詳細資訊，請參閱 [建立 AWS CodeBuild 觸發](#trigger-create)和 [編輯 AWS CodeBuild 觸發](triggers-edit.md)。

**Topics**
+ [

## 建立 AWS CodeBuild 觸發
](#trigger-create)
+ [

# 編輯 AWS CodeBuild 觸發
](triggers-edit.md)

## 建立 AWS CodeBuild 觸發
<a name="trigger-create"></a>

您可以在專案上建立觸發來排定每小時、每天或每週執行一次組建。您也可以使用具有 Amazon CloudWatch Cron 表達式的自訂規則來建立觸發。例如，您可以使用 cron 表達式來排定在每個工作日的特定時間執行組建。

**注意**  
無法從組建觸發、Amazon EventBridge 事件或 AWS Step Functions 任務啟動批次組建。

**Topics**
+ [

### 建立 AWS CodeBuild 觸發 （主控台）
](#trigger-create-console)
+ [

### 以程式設計方式建立 AWS CodeBuild 觸發
](#trigger-create-code)

### 建立 AWS CodeBuild 觸發 （主控台）
<a name="trigger-create-console"></a>

使用下列程序，使用 建立觸發 AWS 管理主控台。

**建立觸發** 

1. 開啟 AWS CodeBuild 主控台，網址為 http：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)。

1. 在導覽窗格中，選擇 **Build projects (建置專案)**。

1. 選擇您想要新增觸發的組建專案的連結，然後選擇 **Build triggers (組建觸發)** 索引標籤。
**注意**  
根據預設，會顯示 100 個最新的建置專案。若要檢視更多組建專案，請選擇齒輪圖示，然後針對 **Projects per page (每頁顯示專案數)** 選擇不同的值，或使用向前和向後箭頭。

1. 選擇 **Create trigger (建立觸發)**。

1. 在 **Trigger name (觸發名稱)** 中輸入名稱。

1. 從 **Frequency (頻率)** 下拉式清單中，選擇觸發的頻率。如果想要使用 Cron 表達式建立頻率，請選擇 **Custom (自訂)**。

1. 指定觸發的頻率參數。您可以在文字方塊中鍵入選項的前幾個字元來篩選下拉式選單項目。
**注意**  
 開始時間和分鐘都是以零為基礎。開始分鐘是介於零到 59 之間的數字。開始時間是介於零到 23 之間的數字。例如，每天下午 12：15 開始的每日觸發。開始時間為 12，開始時間為 15。每日午夜開始的觸發，開始時間為零，開始分鐘為零。每日下午 11：59 開始的觸發，開始時間為 23，開始時間為 59。  
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/build-triggers.html)

1.  選取 **Enable this trigger (啟用此觸發)**。

1.  (選用) 展開 **Advanced (進階)** 區段。在 **Source version (來源版本)** 中，輸入來源的版本。
   +  針對 Amazon S3，輸入對應至您要建置之輸入成品版本的版本 ID。如果 **Source version** (來源版本) 為空白，將使用最新版本。
   +  對於 AWS CodeCommit，輸入遞交 ID。如果 **Source version (來源版本)** 為空白，將使用預設分支的 HEAD 遞交 ID。
   + 針對 GitHub 或 GitHub Enterprise，輸入遞交 ID、提取要求 ID、分支名稱，或與您想要建置之原始碼版本對應的標籤名稱。如果指定提取要求 ID，其格式必須為 `pr/pull-request-ID` (例如，`pr/25`)。如果指定分支名稱，將使用分支的 HEAD 遞交 ID。如果 **Source version (來源版本)** 空白，則會使用預設分支的 HEAD 遞交 ID。
   + 針對 Bitbucket，輸入遞交 ID、分支名稱，或與您想要建置之原始碼版本對應的標籤名稱。如果指定分支名稱，將使用分支的 HEAD 遞交 ID。如果 **Source version (來源版本)** 空白，則會使用預設分支的 HEAD 遞交 ID。

1. （選用） 指定介於 5 分鐘到 2160 分鐘 (36 小時） 之間的逾時。此值會指定建置停止前 AWS CodeBuild 嘗試建置的時間長度。如果 **Hours (小時)** 和 **Minutes (分鐘)** 空白，則會使用專案中指定的預設逾時值。

1. 選擇 **Create trigger (建立觸發)**。

### 以程式設計方式建立 AWS CodeBuild 觸發
<a name="trigger-create-code"></a>

CodeBuild 使用 Amazon EventBridge 規則進行建置觸發。您可以使用 EventBridge API，以程式設計方式為您的 CodeBuild 專案建立建置觸發。如需詳細資訊，請參閱 [Amazon EventBridge API 參考](https://docs.aws.amazon.com/eventbridge/latest/APIReference/)。

# 編輯 AWS CodeBuild 觸發
<a name="triggers-edit"></a>

您可以在專案上編輯觸發來排定每小時、每天或每週執行一次組建。您也可以編輯觸發條件，以使用具有 Amazon CloudWatch Cron 表達式的自訂規則。例如，您可以使用 cron 表達式來排定在每個工作日的特定時間執行組建。如需有關建立觸發的資訊，請參閱[建立 AWS CodeBuild 觸發](build-triggers.md#trigger-create)。

**Topics**
+ [

## 編輯 AWS CodeBuild 觸發 （主控台）
](#triggers-edit-console)
+ [

## 以程式設計方式編輯 AWS CodeBuild 觸發
](#trigger-edit-code)

## 編輯 AWS CodeBuild 觸發 （主控台）
<a name="triggers-edit-console"></a>

使用下列程序來編輯使用 的觸發 AWS 管理主控台。

**如何編輯觸發條件**

1. 開啟 AWS CodeBuild 主控台，網址為 [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)：//。

1. 在導覽窗格中，選擇 **Build projects (建置專案)**。

1. 選擇您想要變更的組建專案的連結，然後選擇 **Build triggers (組建觸發)** 索引標籤。
**注意**  
根據預設，會顯示 100 個最新的建置專案。若要檢視更多組建專案，請選擇齒輪圖示，然後針對 **Projects per page (每頁顯示專案數)** 選擇不同的值，或使用向前和向後箭頭。

1. 選擇您想要變更的觸發旁邊的選項按鈕，然後選擇 **Edit (編輯)**。

1. 從 **Frequency (頻率)** 下拉式清單中，選擇觸發的頻率。如果想要使用 Cron 表達式建立頻率，請選擇 **Custom (自訂)**。

1. 指定觸發的頻率參數。您可以在文字方塊中鍵入選項的前幾個字元來篩選下拉式選單項目。
**注意**  
 開始時間和分鐘都是以零為基礎。開始分鐘是介於零到 59 之間的數字。開始時間是介於零到 23 之間的數字。例如，每天下午 12：15 開始的每日觸發。開始時間為 12，開始時間為 15。每天午夜開始的每日觸發，開始時間為零，開始分鐘為零。每天下午 11：59 開始的每日觸發。開始時間為 23，開始時間為 59。  
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/triggers-edit.html)

1.  選取 **Enable this trigger (啟用此觸發)**。

**注意**  
您可以使用 Amazon CloudWatch 主控台，網址為 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)：// AWS CodeBuild https：//www.microsoft.com/microsoft.com/microsoft.com/microsoft.com/microsoft.com/soft.com/soft.com/soft.com/soft.com/soft.com/soft.com/soft.com/soft.com/soft.com/soft.com/soft.com/

## 以程式設計方式編輯 AWS CodeBuild 觸發
<a name="trigger-edit-code"></a>

CodeBuild 使用 Amazon EventBridge 規則進行建置觸發。您可以使用 EventBridge API 以程式設計方式編輯 CodeBuild 專案的建置觸發條件。如需詳細資訊，請參閱 [Amazon EventBridge API 參考](https://docs.aws.amazon.com/eventbridge/latest/APIReference/)。

# 在 中檢視建置詳細資訊 AWS CodeBuild
<a name="view-build-details"></a>

您可以使用 AWS CodeBuild 主控台 AWS CLI或 AWS SDKs來檢視 CodeBuild 管理之組建的詳細資訊。

**Topics**
+ [

## 檢視建置的詳細資訊 (主控台)
](#view-build-details-console)
+ [

## 檢視建置的詳細資訊 (AWS CLI)
](#view-build-details-cli)
+ [

## 檢視建置詳細資訊AWS SDKs)
](#view-build-details-sdks)
+ [

# 建置階段轉換
](view-build-details-phases.md)

## 檢視建置的詳細資訊 (主控台)
<a name="view-build-details-console"></a>

1. 在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1. 執行以下任意一項：
   + 在導覽窗格中，選擇 **Build history (組建歷史記錄)**。在組建清單中的 **Build run (組建執行)** 欄中，選擇組建的連結。
   + 在導覽窗格中，選擇 **Build projects (建置專案)**。在組建專案清單中的 **Name (名稱)** 欄中，選擇組建專案名稱的連結。然後，在組建清單中的 **Build run (組建執行)** 欄中，選擇組建的連結。
**注意**  
根據預設，只會顯示最新 10 個組建或組建專案。若要檢視更多組建或組建專案，請選擇齒輪圖示，然後針對 **Builds per page (每頁顯示組建數)** 或 **Projects per page (每頁顯示專案數)** 選擇不同的值，或使用向前和向後箭頭。

## 檢視建置的詳細資訊 (AWS CLI)
<a name="view-build-details-cli"></a>

如需 AWS CLI 搭配 使用 的詳細資訊 AWS CodeBuild，請參閱 [命令列參考](cmd-ref.md)。

執行 **batch-get-builds** 命令：

```
aws codebuild batch-get-builds --ids ids
```

取代下列預留位置：
+ *ids*：必要的字串。要檢視詳細資訊的一或多個組建 ID。若要指定一個以上的組建 ID，請以空格將每個組建 ID 分開。您最多可以指定 100 個組建 ID。若要取得建置 ID 的清單，請參閱下列主題：
  + [檢視建置 ID 清單 (AWS CLI)](view-build-list.md#view-build-list-cli)
  + [檢視建置專案的建置 ID 清單 (AWS CLI)](view-builds-for-project.md#view-builds-for-project-cli)

例如，如果您執行此命令：

```
aws codebuild batch-get-builds --ids codebuild-demo-project:e9c4f4df-3f43-41d2-ab3a-60fe2EXAMPLE codebuild-demo-project:815e755f-bade-4a7e-80f0-efe51EXAMPLE my-other-project:813bb6c6-891b-426a-9dd7-6d8a3EXAMPLE
```

如果命令成功，輸出中會顯示類似於 [檢視摘要建置資訊](getting-started-overview.md#getting-started-cli-monitor-build-cli) 所述的資料。

## 檢視建置詳細資訊AWS SDKs)
<a name="view-build-details-sdks"></a>

如需 AWS CodeBuild 搭配 AWS SDKs 使用 的詳細資訊，請參閱 [AWS SDKs和工具參考](sdk-ref.md)。

# 建置階段轉換
<a name="view-build-details-phases"></a>

逐步建置 AWS CodeBuild ：



![\[CodeBuild 階段。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/build-phases.png)




**重要**  
即使 `BUILD` 階段失敗，也一定會嘗試 `UPLOAD_ARTIFACTS` 階段。

# 檢視 中的組建 IDs清單 AWS CodeBuild
<a name="view-build-list"></a>

您可以使用 AWS CodeBuild 主控台 AWS CLI或 AWS SDKs來檢視 CodeBuild 管理之組建IDs 清單。

**Topics**
+ [

## 檢視建置 ID 清單 (主控台)
](#view-build-list-console)
+ [

## 檢視建置 ID 清單 (AWS CLI)
](#view-build-list-cli)
+ [

## 檢視批次建置 IDs的清單 (AWS CLI)
](#view-batch-build-list-cli)
+ [

## 檢視組建 IDs(AWS SDKs的清單
](#view-build-list-sdks)

## 檢視建置 ID 清單 (主控台)
<a name="view-build-list-console"></a>

1. 在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1. 在導覽窗格中，選擇 **Build history (組建歷史記錄)**。
**注意**  
根據預設，只會顯示最新 10 個組建。若要檢視更多組建，請選擇齒輪圖示，然後針對 **Builds per page (每頁顯示組建數)** 選擇不同的值，或使用向前和向後箭頭。

## 檢視建置 ID 清單 (AWS CLI)
<a name="view-build-list-cli"></a>

如需 AWS CLI 搭配 CodeBuild 使用 的詳細資訊，請參閱 [命令列參考](cmd-ref.md)。
+ 執行 **list-builds** 命令：

  ```
  aws codebuild list-builds --sort-order sort-order --next-token next-token
  ```

  在上述命令中，取代下列預留位置：
  + *sort-order*：用於表示如何列出組建 ID 的選用字串。有效值包括 `ASCENDING` 與 `DESCENDING`。
  + *next-token*：選用字串。在先前的執行中，如果清單具有超過 100 個項目，則只會傳回前 100 個項目，以及稱為 *next token* 的唯一字串。若要取得清單中下一個批次中的項目，請再次執行此命令，將 next token 新增至呼叫。若要取得清單中的所有項目，請繼續對每個後續的 next token 執行此命令，直到不再傳回 next token 為止。

  例如，如果您執行此命令：

  ```
  aws codebuild list-builds --sort-order ASCENDING
  ```

  類似下列的結果可能會顯示於輸出：

  ```
  {
    "nextToken": "4AEA6u7J...The full token has been omitted for brevity...MzY2OA==",
    "ids": [
      "codebuild-demo-project:815e755f-bade-4a7e-80f0-efe51EXAMPLE"
      "codebuild-demo-project:84a7f3d1-d40e-4956-b4cf-7a9d4EXAMPLE"
      ... The full list of build IDs has been omitted for brevity ...
      "codebuild-demo-project:931d0b72-bf6f-4040-a472-5c707EXAMPLE"
    ]
  }
  ```

  如果您再次執行此命令：

  ```
  aws codebuild list-builds --sort-order ASCENDING --next-token 4AEA6u7J...The full token has been omitted for brevity...MzY2OA==
  ```

  類似下列的結果可能會顯示於輸出：

  ```
  {
    "ids": [
      "codebuild-demo-project:49015049-21cf-4b50-9708-df115EXAMPLE",
      "codebuild-demo-project:543e7206-68a3-46d6-a4da-759abEXAMPLE",
      ... The full list of build IDs has been omitted for brevity ...
      "codebuild-demo-project:c282f198-4582-4b38-bdc0-26f96EXAMPLE"
    ]
  }
  ```

## 檢視批次建置 IDs的清單 (AWS CLI)
<a name="view-batch-build-list-cli"></a>

如需 AWS CLI 搭配 CodeBuild 使用 的詳細資訊，請參閱 [命令列參考](cmd-ref.md)。
+ 執行 **list-build-batches** 命令：

  ```
  aws codebuild list-build-batches --sort-order sort-order --next-token next-token
  ```

  在上述命令中，取代下列預留位置：
  + *sort-order*：選用字串，用於指示如何列出批次建置 IDs。有效值包括 `ASCENDING` 與 `DESCENDING`。
  + *next-token*：選用字串。在先前的執行中，如果清單具有超過 100 個項目，則只會傳回前 100 個項目，以及稱為 *next token* 的唯一字串。若要取得清單中下一個批次中的項目，請再次執行此命令，將 next token 新增至呼叫。若要取得清單中的所有項目，請繼續對每個後續的 next token 執行此命令，直到不再傳回 next token 為止。

  例如，如果您執行此命令：

  ```
  aws codebuild list-build-batches --sort-order ASCENDING
  ```

  類似下列的結果可能會顯示於輸出：

  ```
  {
    "nextToken": "4AEA6u7J...The full token has been omitted for brevity...MzY2OA==",
    "ids": [
      "codebuild-demo-project:815e755f-bade-4a7e-80f0-efe51EXAMPLE"
      "codebuild-demo-project:84a7f3d1-d40e-4956-b4cf-7a9d4EXAMPLE"
      ... The full list of build IDs has been omitted for brevity ...
      "codebuild-demo-project:931d0b72-bf6f-4040-a472-5c707EXAMPLE"
    ]
  }
  ```

  如果您再次執行此命令：

  ```
  aws codebuild list-build-batches --sort-order ASCENDING --next-token 4AEA6u7J...The full token has been omitted for brevity...MzY2OA==
  ```

  類似下列的結果可能會顯示於輸出：

  ```
  {
    "ids": [
      "codebuild-demo-project:49015049-21cf-4b50-9708-df115EXAMPLE",
      "codebuild-demo-project:543e7206-68a3-46d6-a4da-759abEXAMPLE",
      ... The full list of build IDs has been omitted for brevity ...
      "codebuild-demo-project:c282f198-4582-4b38-bdc0-26f96EXAMPLE"
    ]
  }
  ```

## 檢視組建 IDs(AWS SDKs的清單
<a name="view-build-list-sdks"></a>

如需搭配 AWS SDKs 使用 CodeBuild 的詳細資訊，請參閱 [AWS SDKs和工具參考](sdk-ref.md)。

# 在 中檢視組建專案的組建 IDs 清單 AWS CodeBuild
<a name="view-builds-for-project"></a>

您可以使用 AWS CodeBuild 主控台 AWS CLI或 AWS SDKs在 CodeBuild 中檢視組建IDs 清單。

**Topics**
+ [

## 檢視建置專案的建置 ID 清單 (主控台)
](#view-builds-for-project-console)
+ [

## 檢視建置專案的建置 ID 清單 (AWS CLI)
](#view-builds-for-project-cli)
+ [

## 檢視組建專案的批次組建 IDs 清單 (AWS CLI)
](#view-batch-builds-for-project-cli)
+ [

## 檢視組建專案的組建 IDs 清單 (AWS SDKs)
](#view-builds-for-project-sdks)

## 檢視建置專案的建置 ID 清單 (主控台)
<a name="view-builds-for-project-console"></a>

1. 前往 [https://console.aws.amazon.com/codebuild/](https://console.aws.amazon.com/codebuild/) 開啟 CodeBuild 主控台。

1. 在導覽窗格中，選擇 **Build projects (建置專案)**。在組建專案清單中，於 **Name (名稱)** 欄中，選擇組建專案。

**注意**  
根據預設，只會顯示最新 100 個組建或組建專案。若要檢視更多組建或組建專案，請選擇齒輪圖示，然後針對 **Builds per page (每頁顯示組建數)** 或 **Projects per page (每頁顯示專案數)** 選擇不同的值，或使用向前和向後箭頭。

## 檢視建置專案的建置 ID 清單 (AWS CLI)
<a name="view-builds-for-project-cli"></a>

如需 AWS CLI 搭配 使用 的詳細資訊 AWS CodeBuild，請參閱 [命令列參考](cmd-ref.md)。

執行 **list-builds-for-project** 命令，如下所示：

```
aws codebuild list-builds-for-project --project-name project-name --sort-order sort-order --next-token next-token
```

在上述命令中，取代下列預留位置：
+ *project-name*：必要字串，用於表示要列出組建 ID 的組建專案名稱。若要取得組建專案清單，請參閱[檢視建置專案名稱清單 (AWS CLI)](view-project-list.md#view-project-list-cli)。
+ *sort-order*：用於表示如何列出組建 ID 的選用字串。有效值包括 `ASCENDING` 與 `DESCENDING`。
+ *next-token*：選用字串。在先前的執行中，如果清單具有超過 100 個項目，則只會傳回前 100 個項目，以及稱為 *next token* 的唯一字串。若要取得清單中下一個批次中的項目，請再次執行此命令，將 next token 新增至呼叫。若要取得清單中的所有項目，請繼續對每個後續傳回的 next token 執行此命令，直到不再傳回 next token 為止。

例如，如果您執行與下列類似的這個命令：

```
aws codebuild list-builds-for-project --project-name codebuild-demo-project --sort-order ASCENDING
```

輸出中可能會顯示與下列類似的結果：

```
{
  "nextToken": "4AEA6u7J...The full token has been omitted for brevity...MzY2OA==",
  "ids": [
    "codebuild-demo-project:9b175d16-66fd-4e71-93a0-50a08EXAMPLE"
    "codebuild-demo-project:a9d1bd09-18a2-456b-8a36-7d65aEXAMPLE"
    ... The full list of build IDs has been omitted for brevity ...
    "codebuild-demo-project:fe70d102-c04f-421a-9cfa-2dc15EXAMPLE"
  ]
}
```

如果您再次執行此命令：

```
aws codebuild list-builds-for-project --project-name codebuild-demo-project --sort-order ASCENDING --next-token 4AEA6u7J...The full token has been omitted for brevity...MzY2OA==
```

您在輸出中可能會看到如下的結果：

```
{
  "ids": [
    "codebuild-demo-project:98253670-7a8a-4546-b908-dc890EXAMPLE"
    "codebuild-demo-project:ad5405b2-1ab3-44df-ae2d-fba84EXAMPLE"
    ... The full list of build IDs has been omitted for brevity ...
    "codebuild-demo-project:f721a282-380f-4b08-850a-e0ac1EXAMPLE"
  ]
}
```

## 檢視組建專案的批次組建 IDs 清單 (AWS CLI)
<a name="view-batch-builds-for-project-cli"></a>

如需 AWS CLI 搭配 使用 的詳細資訊 AWS CodeBuild，請參閱 [命令列參考](cmd-ref.md)。

執行 **list-build-batches-for-project** 命令，如下所示：

```
aws codebuild list-build-batches-for-project --project-name project-name --sort-order sort-order --next-token next-token
```

在上述命令中，取代下列預留位置：
+ *project-name*：必要字串，用於表示要列出組建 ID 的組建專案名稱。若要取得組建專案清單，請參閱[檢視建置專案名稱清單 (AWS CLI)](view-project-list.md#view-project-list-cli)。
+ *sort-order*：用於表示如何列出組建 ID 的選用字串。有效值包括 `ASCENDING` 與 `DESCENDING`。
+ *next-token*：選用字串。在先前的執行中，如果清單具有超過 100 個項目，則只會傳回前 100 個項目，以及稱為 *next token* 的唯一字串。若要取得清單中下一個批次中的項目，請再次執行此命令，將 next token 新增至呼叫。若要取得清單中的所有項目，請繼續對每個後續傳回的 next token 執行此命令，直到不再傳回 next token 為止。

例如，如果您執行與下列類似的這個命令：

```
aws codebuild list-build-batches-for-project --project-name codebuild-demo-project --sort-order ASCENDING
```

輸出中可能會顯示與下列類似的結果：

```
{
  "nextToken": "4AEA6u7J...The full token has been omitted for brevity...MzY2OA==",
  "ids": [
    "codebuild-demo-project:9b175d16-66fd-4e71-93a0-50a08EXAMPLE"
    "codebuild-demo-project:a9d1bd09-18a2-456b-8a36-7d65aEXAMPLE"
    ... The full list of build IDs has been omitted for brevity ...
    "codebuild-demo-project:fe70d102-c04f-421a-9cfa-2dc15EXAMPLE"
  ]
}
```

如果您再次執行此命令：

```
aws codebuild list-build-batches-for-project --project-name codebuild-demo-project --sort-order ASCENDING --next-token 4AEA6u7J...The full token has been omitted for brevity...MzY2OA==
```

您在輸出中可能會看到如下的結果：

```
{
  "ids": [
    "codebuild-demo-project:98253670-7a8a-4546-b908-dc890EXAMPLE"
    "codebuild-demo-project:ad5405b2-1ab3-44df-ae2d-fba84EXAMPLE"
    ... The full list of build IDs has been omitted for brevity ...
    "codebuild-demo-project:f721a282-380f-4b08-850a-e0ac1EXAMPLE"
  ]
}
```

## 檢視組建專案的組建 IDs 清單 (AWS SDKs)
<a name="view-builds-for-project-sdks"></a>

如需 AWS CodeBuild 搭配 AWS SDKs 使用 的詳細資訊，請參閱 [AWS SDKs和工具參考](sdk-ref.md)。