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

# 变量参考
<a name="reference-variables"></a>

本部分仅供参考。有关创建变量的信息，请参阅[使用变量](actions-variables.md)。

变量允许您使用在管道执行或操作执行时确定的值来配置管道操作。

一些操作提供方会生成一组定义的变量。您可以从该操作提供方的默认变量键中进行选择，例如提交 ID。

**重要**  
传递密钥参数时，请勿直接输入值。该值以明文形式提供，因此是可读的。出于安全原因，请勿使用纯文本表示密钥。我们强烈建议您使用 AWS Secrets Manager 来存储机密。

要查看使用变量的 step-by-step示例，请执行以下操作：
+ 有关在管道执行时传递的管道级变量的教程，请参阅[教程：使用管道级变量](tutorials-pipeline-variables.md)。
+ 有关使用上游操作 (CodeCommit) 中的变量并生成输出变量的 Lambda 操作的教程，请参阅。[教程：将变量与 Lambda 调用操作一起使用](tutorials-lambda-variables.md)
+ 有关引用上游 CloudFormation 操作堆栈输出变量的 CloudFormation 操作的教程，请参阅[教程：创建使用 AWS CloudFormation 部署操作中的变量的管道](tutorials-cloudformation-action.md)。
+ 有关手动批准操作的示例，其消息文本引用了解析为提 CodeCommit 交 ID 和提交消息的输出变量，请参阅[示例：在手动审批中使用变量](actions-variables.md#actions-variables-examples-approvals)。
+ 有关带有可解析为 GitHub分支名称的环境变量的 CodeBuild 操作示例，请参阅[示例：使用带有 CodeBuild 环境 BranchName 变量的变量](actions-variables.md#actions-variables-examples-env-branchname)。
+ CodeBuild actions 将所有作为构建一部分导出的环境变量生成为变量。有关更多信息，请参阅 [CodeBuild 操作输出变量](#reference-variables-list-configured-codebuild)。

**变量限制**

有关限制信息，请参阅 [AWS CodePipeline 中的限额](limits.md)。

**注意**  
在操作配置字段中输入变量语法时，请不要超过配置字段的 1000 个字符的限制。如果超过此限制，将会返回验证错误。

**Topics**
+ [概念](#reference-variables-concepts)
+ [变量使用案例](#reference-variables-cases)
+ [配置变量](#reference-variables-workflow)
+ [变量解析](#reference-variables-resolution)
+ [变量规则](#reference-variables-rules)
+ [可用于管道操作的变量](#reference-variables-list)

## 概念
<a name="reference-variables-concepts"></a>

此部分列出了与变量和命名空间相关的关键术语和概念。

### 变量
<a name="reference-variables-concepts-variablekeys"></a>

变量是键/值对，可用于在管道中动态配置操作。目前，有三种方法提供这些变量：
+ 在每个管道执行开始时，都有一组隐式可用的变量。这组变量当前包括 `PipelineExecutionId`，这是当前管道执行的 ID。
+ 管道级变量是在管道运行时间创建和解析管道时定义的。

  您可以在创建管道时指定管道级变量，也可以在管道执行时提供值。
+ 有的操作类型在执行时生成一组变量。您可以通过检查作为 [ListActionExecutions](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_ListActionExecutions.html)API 一部分的`outputVariables`字段来查看操作生成的变量。有关按操作提供方列出的可用键名称的列表，请参阅[可用于管道操作的变量](#reference-variables-list)。要查看每种操作类型产生的变量，请参阅 CodePipeline [操作结构参考](action-reference.md)。

要在操作配置中引用这些变量，您必须使用带有正确命名空间的变量引用语法。

 有关示例变量工作流，请参阅[配置变量](#reference-variables-workflow)。

### 命名空间
<a name="reference-variables-concepts-namespaces"></a>

为了确保可以唯一地引用该变量，必须将其分配到命名空间。将一组变量分配到命名空间后，您可以通过以下语法，使用命名空间和变量键在操作配置中引用这些变量：

```
#{namespace.variable_key}
```

您可以在三种类型的命名空间中分配变量：
+ **Codepipeline 预留命名空间**

  这是分配到在每个管道执行开始时可用的一组隐式变量的命名空间。此命名空间是 `codepipeline`。变量引用示例：

  ```
  #{codepipeline.PipelineExecutionId}
  ```
+ **管道级变量命名空间**

  这是分配给管道级变量的命名空间。所有管道级变量的命名空间是 `variables`。变量引用示例：

  ```
  #{variables.variable_name}
  ```
+ **已分配命名空间的操作**

  这是您分配给某个操作的命名空间。该操作生成的所有变量都属于此命名空间。要使某个操作生成的变量可在下游操作配置中使用，您必须使用命名空间配置生成操作。命名空间在整个管道定义中必须唯一，并且不能与任何构件名称冲突。以下是使用命名空间 `SourceVariables` 配置的操作的变量引用示例。

  ```
  #{SourceVariables.VersionId}
  ```

## 变量使用案例
<a name="reference-variables-cases"></a>

以下是管道级变量的一些常见使用案例，有助于确定如何根据自己的特定需求使用变量。
+ 管道级别的变量适用于希望每次都使用同一个管道但操作配置的输入略有差异的 CodePipeline 客户。任何启动管道的开发人员都会在管道启动时在 UI 中添加变量值。通过此配置，只为此次执行传递参数。
+ 使用管道级变量，您可以将动态输入传递给管道中的操作。您可以将参数化管道迁移到， CodePipeline 而不必维护同一管道的不同版本，也不必创建复杂的管道。
+ 您可以使用管道级变量传递输入参数，以便在每次执行时重复使用管道（例如当您要指定想要部署到生产环境的版本时），如此就不必复制管道了。
+ 您可以使用单个管道将资源部署到多个构建和部署环境。例如，对于带有 CodeCommit 存储库的管道，可以从指定的分支和目标部署环境进行部署， CodeBuild 并在管道级别传递 CodeDeploy参数。

**注意**  
对于 Amazon ECR、Amazon S3 或 CodeCommit 源，您还可以使用输入转换条目创建源替换，以便`revisionValue`在 EventBridge 管道事件中使用 in，其中派生自对象密钥、提交或图像 ID 的源事件变量。`revisionValue`有关更多信息，请参阅[Amazon ECR 源操作和 EventBridge 资源](create-cwe-ecr-source.md)、[连接到启用事件源的 Amazon S3 源操作](create-S3-source-events.md)或[CodeCommit 源操作和 EventBridge](triggering.md)下的流程中包含的输入转换条目的可选步骤。

## 配置变量
<a name="reference-variables-workflow"></a>

您可以在管道级别或管道结构中的操作级别配置变量。

### 配置管道级变量
<a name="reference-variables-pipeline-level"></a>

您可以添加一个或多个管道级变量。你可以在 CodePipeline 动作配置中引用这个值。您可以在创建管道时添加变量名称、默认值和描述。在执行时解析变量。

**注意**  
如果没有为管道级变量定义默认值，则认为该变量是必需的。启动管道时，必须为所有必需的变量指定覆盖，否则管道执行将因验证错误而失败。

您可以使用管道结构中的变量属性提供管道级变量。在以下示例中，变量 `Variable1` 的值为 `Value1`。

```
       "variables": [
            {
                "name": "Variable1",
                "defaultValue": "Value1",
                "description": "description"
            }
        ]
```

有关管道 JSON 结构的示例，请参阅[创建管道、阶段和操作](pipelines-create.md)。

有关在管道执行时传递的管道级变量的教程，请参阅[教程：使用管道级变量](tutorials-pipeline-variables.md)。

请注意，不支持在任何类型的源操作中使用管道级变量。

**注意**  
如果管道中的某些操作中已经使用 `variables` 命名空间，则必须更新操作定义并为冲突的操作选择另一个命名空间。

### 配置操作级变量
<a name="reference-variables-action-level"></a>

您可以通过为操作声明命名空间来配置操作以生成变量。该操作必须已经是生成变量的操作提供方之一。否则，可用的变量将为管道级别的变量。

您可以通过以下方法声明命名空间：
+ 在控制台的 **Edit action (编辑操作)** 页面上，在 **Variable namespace (变量命名空间)** 中输入命名空间。
+ 在 JSON 管道结构的 `namespace` 参数字段中输入命名空间。

在此示例中，您将名称为的`namespace`参数添加到 CodeCommit 源操作中`SourceVariables`。这会将操作配置为生成可用于该操作提供方的变量，例如 `CommitId`。

```
{
    "name": "Source",
    "actions": [
        {
            "outputArtifacts": [
                {
                    "name": "SourceArtifact"
                }
            ],
            "name": "Source",
            "namespace": "SourceVariables",
            "configuration": {
                "RepositoryName": "MyRepo",
                "BranchName": "mainline",
                "PollForSourceChanges": "false"
            },
            "inputArtifacts": [],
            "region": "us-west-2",
            "actionTypeId": {
                "provider": "CodeCommit",
                "category": "Source",
                "version": "1",
                "owner": "AWS"
            },
            "runOrder": 1
        }
    ]
},
```

接下来，您需要配置下游操作来使用由上一个操作生成的变量。您可以通过以下方法执行此操作：
+ 在控制台的 **Edit action (编辑操作)** 页面上，在操作配置字段中输入变量语法（针对下游操作）。
+ 在 JSON 管道结构的操作配置字段中输入变量语法（针对下游操作）

在此示例中，构建操作的配置字段显示在操作执行时更新的环境变量。该示例为执行 ID `#{codepipeline.PipelineExecutionId}` 指定命名空间和变量，并为提交 ID **\$1\$1SourceVariables.CommitId\$1** 指定命名空间和变量。

```
{
    "name": "Build",
    "actions": [
        {
            "outputArtifacts": [
                {
                    "name": "BuildArtifact"
                }
            ],
            "name": "Build",
            "configuration": {
                "EnvironmentVariables": "[{\"name\":\"Release_ID\",\"value\":\"#{codepipeline.PipelineExecutionId}\",\"type\":\"PLAINTEXT\"},{\"name\":\"Commit_ID\",\"value\":\"#{SourceVariables.CommitId}\",\"type\":\"PLAINTEXT\"}]",
                "ProjectName": "env-var-test"
            },
            "inputArtifacts": [
                {
                    "name": "SourceArtifact"
                }
            ],
            "region": "us-west-2",
            "actionTypeId": {
                "provider": "CodeBuild",
                "category": "Build",
                "version": "1",
                "owner": "AWS"
            },
            "runOrder": 1
        }
    ]
},
```

## 变量解析
<a name="reference-variables-resolution"></a>

每当在管道执行中执行某个操作时，该操作生成的变量均可用于确保在该操作之后运行的操作。要在使用操作中使用这些变量，您可以使用前面示例中显示的语法，将变量添加到使用操作的配置中。在它执行消耗操作之前，先 CodePipeline 解析配置中存在的所有变量引用，然后再启动动作执行。



![\[示例：用于多个操作的变量\]](http://docs.aws.amazon.com/zh_cn/codepipeline/latest/userguide/images/variables-workflow-example.png)


## 变量规则
<a name="reference-variables-rules"></a>

以下规则可帮助您进行变量的配置：
+ 您可以通过新的操作属性或通过编辑操作，为操作指定命名空间和变量。
+ 使用管道创建向导时，控制台会为该向导创建的每个操作生成一个命名空间。
+ 如果未指定命名空间，则无法在任何操作配置中引用该操作生成的变量。
+ 要引用操作生成的变量，引用操作必须发生在生成变量的操作之后。这意味着引用操作需要在生成变量的操作之后的阶段，或者在相同阶段中但具有较后的运行顺序。

## 可用于管道操作的变量
<a name="reference-variables-list"></a>

操作提供方确定操作可以生成哪些变量。

有关管理变量的 step-by-step过程，请参见[使用变量](actions-variables.md)。

### 使用已定义变量键的操作
<a name="reference-variables-list-defined"></a>

与可选择的命名空间不同，以下操作使用无法编辑的变量键。例如，对于 Amazon S3 操作提供方，只有 `ETag` 和 `VersionId` 变量键可用。

每次执行还具有一组 CodePipeline生成的管道变量，其中包含有关执行的数据，例如管道版本 ID。管道中的任何操作都可以使用这些变量。

**Topics**
+ [CodePipeline 执行 ID 变量](#w2aac64c33b7b9)
+ [Amazon ECR 操作输出变量](#reference-variables-output-ECR)
+ [CloudFormation StackSets 操作输出变量](#reference-variables-output-StackSets)
+ [CodeCommit 操作输出变量](#reference-variables-output-CodeCommit)
+ [CodeStarSourceConnection 操作输出变量](#reference-variables-output-CodeConnections)
+ [GitHub 操作输出变量（GitHub （通过 OAuth 应用程序）操作）](#reference-variables-output-GitHub-version1)
+ [S3 操作输出变量](#reference-variables-output-S3)

#### CodePipeline 执行 ID 变量
<a name="w2aac64c33b7b9"></a>


**CodePipeline 执行 ID 变量**  

| Provider | 变量键 | 示例值 | 变量语法示例 | 
| --- | --- | --- | --- | 
| codepipeline | PipelineExecutionId | 8abc75f0-fbf8-4f4c-bfEXAMPLE | \$1\$1codepipeline.PipelineExecutionId\$1 | 

#### Amazon ECR 操作输出变量
<a name="reference-variables-output-ECR"></a>


**Amazon ECR 变量**  

| 变量键 | 示例值 | 变量语法示例 | 
| --- | --- | --- | 
| ImageDigest | sha256: EXAMPLE1122334455 | \$1\$1SourceVariables.ImageDigest\$1 | 
| ImageTag | 最新 | \$1\$1SourceVariables.ImageTag\$1 | 
| ImageURI | 11111EXAMPLE.dkr.ecr.us-west-2.amazonaws.com/ecs-repo:latest | \$1\$1SourceVariables.ImageURI\$1 | 
| RegistryId | EXAMPLE12233 | \$1\$1SourceVariables.RegistryId\$1 | 
| RepositoryName | my-image-repo | \$1\$1SourceVariables.RepositoryName\$1 | 

#### CloudFormation StackSets 操作输出变量
<a name="reference-variables-output-StackSets"></a>


**CloudFormation StackSets 变量**  

| 变量键 | 示例值 | 变量语法示例 | 
| --- | --- | --- | 
| OperationId | 11111111-2bbb-111-2bbb-11111example | \$1\$1DeployVariables.OperationId\$1 | 
| StackSetId | my-stackset:1111aaaa-1111-2222-2bbb-11111example | \$1\$1DeployVariables.StackSetId\$1 | 

#### CodeCommit 操作输出变量
<a name="reference-variables-output-CodeCommit"></a>


**CodeCommit 变量**  

| 变量键 | 示例值 | 变量语法示例 | 
| --- | --- | --- | 
| AuthorDate | 2019-10-29T03:32:21Z | \$1\$1SourceVariables.AuthorDate\$1 | 
| BranchName | 发展 | \$1\$1SourceVariables.BranchName\$1 | 
| CommitId |  exampleb01f91b31  | \$1\$1SourceVariables.CommitId\$1 | 
| CommitMessage | 修复了一个错误（最大大小为 100 KB） | \$1\$1SourceVariables.CommitMessage\$1 | 
| CommitterDate | 2019-10-29T03:32:21Z | \$1\$1SourceVariables.CommitterDate\$1 | 
| RepositoryName | myCodeCommit回购 | \$1\$1SourceVariables.RepositoryName\$1 | 

#### CodeStarSourceConnection 操作输出变量
<a name="reference-variables-output-CodeConnections"></a>

可用的输出变量取决于触发器类型（推送、拉取请求或标签）。下表中标记为 “*全部*” 的变量是为每种触发器类型生成的。只有在该触发器启动管道执行时，才会生成标有特定触发器类型的变量。


**`CodeStarSourceConnection`变量（Bitbucket Cloud GitHub、、 GitHub 企业存储库和 GitLab .com）**  

| 变量键 | 示例值 | 变量语法示例 | 触发器类型 | 
| --- | --- | --- | --- | 
| AuthorDate | 2019-10-29T03:32:21Z | \$1\$1SourceVariables.AuthorDate\$1 | 全部 | 
| AuthorDisplayName | Jane Doe | \$1\$1SourceVariables.AuthorDisplayName\$1 | 全部 | 
| AuthorEmail | jane.doe@example.com | \$1\$1SourceVariables.AuthorEmail\$1 | 全部 | 
| AuthorId | janedoe | \$1\$1SourceVariables.AuthorId\$1 | 全部 | 
| BranchName | 发展 | \$1\$1SourceVariables.BranchName\$1 | 推送，标记 | 
| CommitId | exampleb01f91b31 | \$1\$1SourceVariables.CommitId\$1 | 全部 | 
| CommitMessage | 修复了一个错误（最大大小为 100 KB） | \$1\$1SourceVariables.CommitMessage\$1 | 全部 | 
| ConnectionArn | arn: aws: codestar-connections: 区域:: connection/ account-id connection-id | \$1\$1SourceVariables.ConnectionArn\$1 | 全部 | 
| DestinationBranchName | main | \$1\$1SourceVariables.DestinationBranchName\$1 | 拉取请求 | 
| FullRepositoryName | 用户名/ GitHubRepo | \$1\$1SourceVariables.FullRepositoryName\$1 | 全部 | 
| ProviderType | GitHub | \$1\$1SourceVariables.ProviderType\$1 | 全部 | 
| PullRequestId | 1 | \$1\$1SourceVariables.PullRequestId\$1 | 拉取请求 | 
| PullRequestTitle | 添加新功能 | \$1\$1SourceVariables.PullRequestTitle\$1 | 拉取请求 | 
| SourceBranchName | 功能分支 | \$1\$1SourceVariables.SourceBranchName\$1 | 拉取请求 | 
| TagName | v1.0.0 | \$1\$1SourceVariables.TagName\$1 | Tag | 

#### GitHub 操作输出变量（GitHub （通过 OAuth 应用程序）操作）
<a name="reference-variables-output-GitHub-version1"></a>


**GitHub 变量GitHub （（通过 OAuth 应用程序）操作）**  

| 变量键 | 示例值 | 变量语法示例 | 
| --- | --- | --- | 
| AuthorDate | 2019-10-29T03:32:21Z | \$1\$1SourceVariables.AuthorDate\$1 | 
| BranchName | main | \$1\$1SourceVariables.BranchName\$1 | 
| CommitId |  exampleb01f91b31  | \$1\$1SourceVariables.CommitId\$1 | 
| CommitMessage |  修复了一个错误（最大大小为 100 KB）  | \$1\$1SourceVariables.CommitMessage\$1 | 
| CommitterDate | 2019-10-29T03:32:21Z | \$1\$1SourceVariables.CommitterDate\$1 | 
| CommitUrl |  | \$1\$1SourceVariables.CommitUrl\$1 | 
| RepositoryName | myGitHub回购 | \$1\$1SourceVariables.RepositoryName\$1 | 

#### S3 操作输出变量
<a name="reference-variables-output-S3"></a>


**S3 变量**  

| 变量键 | 示例值 | 变量语法示例 | 
| --- | --- | --- | 
| ETag | example28be1c3 | \$1\$1SourceVariables.ETag\$1 | 
| VersionId | exampleta\$1 IUQCv | \$1\$1SourceVariables.VersionId\$1 | 

### 使用用户配置的变量键的操作
<a name="reference-variables-list-configured"></a>

对于 CodeBuild CloudFormation、和 Lambda 操作，变量键由用户配置。

**Topics**
+ [CloudFormation 操作输出变量](#w2aac64c33b9b7)
+ [CodeBuild 操作输出变量](#reference-variables-list-configured-codebuild)
+ [Lambda 操作输出变量](#w2aac64c33b9c11)

#### CloudFormation 操作输出变量
<a name="w2aac64c33b9b7"></a>


**CloudFormation 变量**  

| 变量键 | 变量语法示例 | 
| --- | --- | 
| 对于 CloudFormation 操作，变量由堆栈模板`Outputs`部分中指定的任何值生成。请注意，生成输出的唯一 CloudFormation 操作模式是那些导致创建或更新堆栈的操作模式，例如堆栈创建、堆栈更新和更改集执行。生成变量的相应操作模式包括：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/codepipeline/latest/userguide/reference-variables.html)有关这些操作模式的更多信息，请参阅[CloudFormation 部署操作参考](action-reference-CloudFormation.md)。有关介绍如何在使用 CloudFormation 输出变量的管道中使用 CloudFormation 部署操作创建管道的教程，请参阅[教程：创建使用 AWS CloudFormation 部署操作中的变量的管道](tutorials-cloudformation-action.md)。 | \$1\$1DeployVariables.StackName\$1 | 

#### CodeBuild 操作输出变量
<a name="reference-variables-list-configured-codebuild"></a>


**CodeBuild 变量**  

| 变量键 | 变量语法示例 | 
| --- | --- | 
|  对于 CodeBuild 操作，变量由导出的环境变量生成的值生成。通过编辑您的 CodeBuild操作 CodePipeline 或将 CodeBuild 环境变量添加到构建规范来设置环境变量。 在 CodeBuild 构建规范中添加说明，以便在导出的变量部分下添加环境变量。请参阅 *AWS CodeBuild 用户指南* 中的 [env/exported-variables](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.exported-variables)。  |  <pre>#{BuildVariables.EnvVar}</pre>  | 

#### Lambda 操作输出变量
<a name="w2aac64c33b9c11"></a>


**Lambda 变量**  

| 变量键 | 变量语法示例 | 
| --- | --- | 
| [Lambda 操作将生成包含在 API 请求`outputVariables`部分中的所有键值对作为变量。PutJobSuccessResult ](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_PutJobSuccessResult.html)有关使用上游操作 (CodeCommit) 中的变量并生成输出变量的 Lambda 操作的教程，请参阅。[教程：将变量与 Lambda 调用操作一起使用](tutorials-lambda-variables.md) | \$1\$1TestVariables.testRunId\$1 |