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

# 變數參考
<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 動作會以變數的形式產生所有做為組建一部分匯出的環境變數。如需詳細資訊，請參閱[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>

本節列出與變數和命名空間相關的主要術語和概念。

### Variables
<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 來源，您也可以使用輸入轉換項目建立來源覆寫，以針對管道事件在 EventBridge `revisionValue`中使用 ，其中 `revisionValue` 衍生自物件金鑰、遞交或映像 ID 的來源事件變數。如需詳細資訊，請參閱 [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` 參數新增至 名稱為 `SourceVariables` 的 CodeCommit 來源動作。這會設定動作來產生可供該動作提供者使用的變數，例如 `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 管道結構的動作組態欄位中輸入變數語法 (針對下游動作)

在此範例中，建置動作的組態欄位顯示動作執行時更新的環境變數。此範例以 `#{codepipeline.PipelineExecutionId}` 指定執行 ID 的命名空間和變數，以 **\$1\$1SourceVariables.CommitId\$1** 指定遞交 ID 的命名空間和變數。

```
{
    "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_tw/codepipeline/latest/userguide/images/variables-workflow-example.png)


## 變數的規則
<a name="reference-variables-rules"></a>

下列規則可協助您設定變數：
+ 您可以透過新的動作屬性或編輯動作，指定動作的命名空間和變數。
+ 當您使用管道建立精靈時，主控台會為精靈建立的每個動作產生命名空間。
+ 如果未指定命名空間，則無法在任何動作組態中參考該動作產生的變數。
+ 若要參考動作所產生的變數，參考動作必須在產生變數的動作之後發生。這意味著在比產生變數的動作更晚的階段，或在同一階段，但執行順序較高。

## 管道動作可用的變數
<a name="reference-variables-list"></a>

動作提供者決定哪些變數可以由動作產生。

如需管理變數的逐步程序，請參閱[使用變數](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 變數**  

| 供應商 | 變數索引鍵 | 範例值 | 變數語法範例 | 
| --- | --- | --- | --- | 
| 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 | 1111111111-2bbb-111-2bbb-11111 範例 | \$1\$1DeployVariables.OperationId\$1 | 
| StackSetId | my-stackset：1111aaaaaa-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 | myCodeCommitRepo | \$1\$1SourceVariables.RepositoryName\$1 | 

#### CodeStarSourceConnection 動作輸出變數
<a name="reference-variables-output-CodeConnections"></a>

可用的輸出變數取決於觸發類型 （推送、提取請求或標籤）。下表中標記為*全部*的變數會針對每個觸發類型產生。只有在管道執行由該觸發啟動時，才會產生標示為特定觸發類型的變數。


**`CodeStarSourceConnection` 變數 (Bitbucket Cloud、GitHub、GitHub Enterprise Repository 和 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：region：account-id：connection/connection-id | \$1\$1SourceVariables.ConnectionArn\$1 | 全部 | 
| DestinationBranchName | 主要 | \$1\$1SourceVariables.DestinationBranchName\$1 | 提取請求 | 
| FullRepositoryName | username/GitHubRepo | \$1\$1SourceVariables.FullRepositoryName\$1 | 全部 | 
| ProviderType | GitHub | \$1\$1SourceVariables.ProviderType\$1 | 全部 | 
| PullRequestId | 1 | \$1\$1SourceVariables.PullRequestId\$1 | 提取請求 | 
| PullRequestTitle | 新增新功能 | \$1\$1SourceVariables.PullRequestTitle\$1 | 提取請求 | 
| SourceBranchName | feature-branch | \$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 | 主要 | \$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 | myGitHubRepo | \$1\$1SourceVariables.RepositoryName\$1 | 

#### S3 動作輸出變數
<a name="reference-variables-output-S3"></a>


**S3 變數**  

| 變數索引鍵 | 範例值 | 變數語法範例 | 
| --- | --- | --- | 
| ETag | example28be1c3 | \$1\$1SourceVariables.ETag\$1 | 
| VersionId | exampleta\$1IUQCv | \$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_tw/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 動作，變數會從匯出環境變數所產生的值產生。在 CodePipeline 中編輯 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 動作會以變數的形式產生包含在 [PutJobSuccessResult API](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_PutJobSuccessResult.html) 請求 outputVariables區段中的所有鍵值對。如需使用上游動作 (CodeCommit) 變數並產生輸出變數的 Lambda 動作教學課程，請參閱 [教學課程：搭配 Lambda 叫用動作使用變數](tutorials-lambda-variables.md)。 | \$1\$1TestVariables.testRunId\$1 |