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

# 執行建置 (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)。