本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 运行构建 (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
   ```

   如果您要运行的构建具有早期版本的构建输入项目，或者如果您要覆盖构建输出项目、环境变量、构建规范或默认构建超时期限的设置，请使用此方法。

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 格式的数据将出现在输出中。将数据复制到本地计算机上或安装 `start-build.json` 的实例上某位置处的文件（如 AWS CLI）中。修改所复制的数据，使其符合以下格式，然后保存结果：

   ```
   {
     "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*：可选。构建项目中定义覆盖此构建项目的构建输出项目位置。
     + *path*：可选。构建项目中定义覆盖此构建项目的构建输出项目路径。
     + *namespaceType*：可选。构建项目中定义覆盖此构建项目的构建输出项目路径类型。
     + *name*：可选。构建项目中定义覆盖此构建项目的构建输出项目名称。
     + *packaging*：可选。构建项目中定义覆盖此构建项目的构建输出项目打包类型。
   + *buildspecOverride*：可选。构建项目中定义覆盖此构建项目的构建规范声明。如果设置了该值，则它可以是内联构建规范定义，也可以是指向相对于内置 `CODEBUILD_SRC_DIR` 环境变量的值的替代构建规范文件的路径，或者是指向 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` 对象。`location` 在 `ProjectCache` 对象中是必需的。
     + *cacheOverride-type*：可选。此构建的 `ProjectCache` 对象的类型，该对象将覆盖构建项目中指定的 `ProjectCache` 对象。`cacheOverride` 是可选的，它采用 `ProjectCache` 对象。`type` 在 `ProjectCache` 对象中是必需的。
   + *certificateOverride*：可选。此构建的证书的名称，该证书将覆盖构建项目中指定的证书。
   + *environmentTypeOverride*：可选。此构建的容器类型，该容器类型将覆盖构建项目中指定的容器类型。当前的有效字符串为 `LINUX_CONTAINER`。
   + 以下占位符适用于 `environmentVariablesOverride`。
     + *environmentVariablesOverride-name*：可选。构建项目中的环境变量名称，其值将会覆盖此构建项目中的相应值。
     + *environmentVariablesOverride-type*：可选。构建项目中的环境变量类型，其值将会覆盖此构建项目中的相应值。
     + *environmentVariablesValue*：可选。构建项目中定义的环境变量值，其值将会覆盖此构建项目中的相应值。
   + *gitCloneDepthOverride*：可选。构建项目中 **Git 克隆深度**的值，您希望此构建项目会覆盖其值。如果您的源类型是 Amazon S3，则不支持此值。
   + *imageOverride*：可选。此构建的映像的名称，该映像将覆盖构建项目中指定的映像。
   + *idempotencyToken*：可选。一个字符串，该字符串用作令牌来指定构建请求是幂等的。您可以选择任何包含 64 个或更少字符的字符串。令牌在发出 start-build 请求后的 5 分钟内有效。如果您重复发出带相同令牌的 start-build 请求，但更改了参数，则 CodeBuild 会返回“参数不匹配”错误。
   + *insecureSslOverride*：可选的布尔值，该值指定是否覆盖构建项目中指定的不安全的 TLS 设置。不安全的 TLS 设置确定是否忽略 TLS 警告，并连接到项目源代码。此覆盖仅在构建的源为 GitHub Enterprise Server 时适用。
   + *privilegedModeOverride*：可选的布尔值。如果设置为 true，则构建将覆盖构建项目中的特权模式。
   +  *queuedTimeoutInMinutesOverride*：可选整数，用于指定在超时前允许构建排队的分钟数。最小值为 5 分钟，最大值为 480 分钟（8 个小时）。
   + *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 Parameter Store 中。如果 Amazon EC2 Systems Manager Parameter Store 中存储的参数的名称以 `/CodeBuild/` 开头 (例如，`/CodeBuild/dockerLoginPassword`)，则 CodeBuild 可以使用该参数。您可以使用 CodeBuild 控制台在 Amazon EC2 Systems Manager 中创建参数。选择**创建参数**，然后按照说明操作。（在该对话框中，对于 **KMS 密钥**，您可以选择性指定您账户中的 AWS KMS 密钥的 ARN。Amazon EC2 Systems Manager 使用此密钥在存储过程中加密参数的值并在检索过程中解密参数的值。） 如果您使用 CodeBuild 控制台创建参数，控制台将在参数被存储时以 `/CodeBuild/` 作为它的开头。但是，如果您使用 Amazon EC2 Systems Manager Parameter Store 控制台创建参数，则必须使用以 `/CodeBuild/` 开头的参数名称，且必须将**类型**设置为**安全字符串**。有关更多信息，请参阅《Amazon EC2 Systems Manager 用户指南》中的 [AWS Systems Manager Parameter Store](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 Parameter Store 中存储的参数，则构建项目的服务角色必须允许 `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_` 打头的名称设置任何环境变量。此前缀是专为内部使用预留的。

   如果具有相同名称的环境变量在多处都有定义，则将按照如下方式确定环境变量的值：
   + 构建操作调用开始时的值优先级最高。
   + 构建项目定义中的值优先级次之。
   + 构建规范文件声明中的值优先级最低。

   有关这些占位符的有效值的信息，请参阅[创建构建项目 (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)。