在中建立並新增自訂動作 CodePipeline

AWS CodePipeline 包含許多動作，可協助您針對自動發行程序設定建置、測試和部署資源。如果您的發行程序包含預設動作中未包含的活動 (例如內部開發的建置程序或測試套件)，您可以建立該用途的自訂動作，並將其包含在管道中。您可以使用在 AWS CLI 與您 AWS 帳戶相關聯的管道中建立自訂動作。

您可以為下列 AWS CodePipeline 動作類別建立自訂動作：

建置或轉換項目的自訂建置動作
將項目部署至一或多個伺服器、網站或儲存庫的自訂部署動作
設定和執行自動化測試的自訂測試動作
執行函數的自訂呼叫動作

當您建立自訂動作時，您也必須建立工作 Worker，以輪詢 CodePipeline 此自訂動作的工作要求、執行工作，並將狀態結果傳回至 CodePipeline。此工作背景工作者可以位於任何電腦或資源上，只要它能夠存取的公用端點 CodePipeline。若要輕鬆管理存取和安全性，請考慮在 Amazon EC2 執行個體上託管您的工作者。

下圖顯示管道的高階檢視，其中包含自訂建置動作：

當管線包含自訂動作做為階段的一部分時，管線會建立工作要求。自訂任務工作者偵測到該請求，並執行該任務 (在此範例中，為使用第三方建置軟體的自訂程序)。動作完成時，任務工作者會傳回成功結果或失敗結果。如果收到成功結果，管線會將修訂版本及其成品提供給下一個動作。如果傳回失敗，管線將不會為管線中的下一個動作提供修訂版本。

注意

這些說明假設您已完成開始使用 CodePipeline 中的步驟。

建立自訂動作

使用建立自訂動作 AWS CLI

開啟文字編輯器，並為您的自訂動作建立 JSON 檔案，其中包含動作類別、動作提供者，以及自訂動作所需的任何設定。例如，若要建立只需要一個屬性的自訂建置動作，您的 JSON 檔案可能如下所示：
```
{
    "category": "Build",
    "provider": "My-Build-Provider-Name",
    "version": "1",
    "settings": {
        "entityUrlTemplate": "https://my-build-instance/job/{Config:ProjectName}/",
        "executionUrlTemplate": "https://my-build-instance/job/{Config:ProjectName}/lastSuccessfulBuild/{ExternalExecutionId}/"
    },
    "configurationProperties": [{
        "name": "ProjectName",
        "required": true,
        "key": true,
        "secret": false,
        "queryable": false,
        "description": "The name of the build project must be provided when this action is added to the pipeline.",
        "type": "String"
    }],
    "inputArtifactDetails": {
        "maximumCount": integer,
        "minimumCount": integer
    },
    "outputArtifactDetails": {
        "maximumCount": integer,
        "minimumCount": integer
    },
    "tags": [{
      "key": "Project",
      "value": "ProjectA"
    }]
}
```
此範例透過在自訂動作上包含 Project 標籤索引鍵和 ProjectA 值，將標籤新增到自訂動作。如需有關在中標記資源的更多資訊 CodePipeline，請參閱標記資源。

JSON 檔案中包含兩個屬性：entityUrlTemplate 和 executionUrlTemplate。您可以遵循 {Config:name} 格式來參照 URL 範本內自訂動作組態屬性中的名稱，只要組態屬性同時為必要且不是秘密。例如，在上述範例中，entityUrlTemplate值參照組態屬性ProjectName。
- entityUrlTemplate：靜態連結，可提供動作服務提供者的相關資訊。在此範例中，建置系統包含每個建置專案的靜態連結。此連結格式會根據建置提供者而不同 (或者，如果您建立不同的動作類型 (例如測試)，則為其他服務提供者)。您必須提供此連結格式，在新增自訂動作時，使用者可以選擇此連結，以將瀏覽器開啟到您網站上提供建置專案 (或測試環境) 特性的頁面。
- executionUrlTemplate：動態連結，可使用目前或最近執行動作的相關資訊予以更新。當您的自訂任務工作者更新任務狀態 (例如，成功、失敗或進行中) 時，也會提供將用來完成連結的 externalExecutionId。此連結可以用來提供動作執行的詳細資訊。
例如，當您在管道中檢視動作時，請參閱下列兩個連結：

在您新增自訂動作並指向 entityUrlTemplate 中的地址 (於建立自訂動作時所指定) 之後，會出現此靜態連結。

在每次執行動作並指向 executionUrlTemplate 中的地址 (於建立自訂動作時所指定) 之後，會更新動態連結。

如需這些連結類型的詳細資訊，以及RevisionURLTemplate和ThirdPartyURL，請參閱《CodePipeline API 參考》CreateCustomActionType中的ActionTypeSettings和。如需動作結構需求以及如何建立動作的詳細資訊，請參閱 CodePipeline 配管結構參照。
儲存 JSON 檔案，並指定您可以輕鬆記住的名稱 (例如 MyCustomAction.json)。
在已安裝 AWS CLI的電腦上，開啟終端機工作階段 (Linux、OS X、Unix) 或命令提示字元 (Windows)。
使用 AWS CLI 來執行命aws codepipeline create-custom-action-type令，指定您剛建立的 JSON 檔案的名稱。

例如，若要建立組建自訂動作：
重要
請確認在檔案名稱之前包含 file://。這是此命令必要項目。
```
aws codepipeline create-custom-action-type --cli-input-json file://MyCustomAction.json
```

此命令會傳回您所建立自訂動作的整個結構，以及為您新增的 JobList 動作組態屬性。當您將自訂動作新增至管道時，可以使用 JobList 指定提供者中您可以輪詢任務的專案。如果您未設定此項目，則會在自訂任務工作者輪詢任務時傳回所有可用的任務。

例如，上述命令可能會傳回與下列類似的結構：


{
    "actionType": {
        "inputArtifactDetails": {               
            "maximumCount": 1,                
            "minimumCount": 1
       },
       "actionConfigurationProperties": [
            {
                "secret": false,
                "required": true,
                "name": "ProjectName",
                "key": true,
                "description": "The name of the build project must be provided when this action is added to the pipeline."
            }
        ],
        "outputArtifactDetails": {               
            "maximumCount": 0,                
            "minimumCount": 0
        },
        "id": {
            "category": "Build",
            "owner": "Custom",
            "version": "1",
            "provider": "My-Build-Provider-Name"
        },
        "settings": {
            "entityUrlTemplate": "https://my-build-instance/job/{Config:ProjectName}/",
            "executionUrlTemplate": "https://my-build-instance/job/mybuildjob/lastSuccessfulBuild/{ExternalExecutionId}/"
        }
    }
}

注意

作為create-custom-action-type命令輸出的一部分，該id部分包括"owner": "Custom"。 CodePipeline 會自動指派Custom為自訂動作類型的擁有者。當您使用 create-custom-action-type 命令或 update-pipeline 命令時，無法指派或變更此值。

建立自訂動作的任務工作者

自訂動作需要工作者，該工作者將輪詢 CodePipeline 自訂動作的工作要求、執行工作並將狀態結果傳回至 CodePipeline。工作背景工作者可以位於任何電腦或資源上，只要它能夠存取的公用端點 CodePipeline。

有多種方式可以設計任務工作者。以下各節提供了一些開發自訂工作背景工作者的實用指南 CodePipeline。

主題

選擇和設定任務工作者的許可管理策略
開發自訂動作的任務工作者
自訂任務工作者架構和範例

選擇和設定任務工作者的許可管理策略

若要在中為您的自訂動作開發自訂工作背景工作者 CodePipeline，您需要整合使用者和權限管理的策略。

最簡單的策略是建立具有 IAM 執行個體角色的 Amazon EC2 執行個體，以新增自訂任務工作者所需的基礎設施，讓您輕鬆擴展整合所需的資源。您可以使用內建的整合 AWS 來簡化自訂工作背景工作者與 CodePipeline.

若要設定 Amazon EC2 執行個體

進一步了解 Amazon EC2，並判斷它是否是您整合的正確選擇。如需詳細資訊，請參閱 Amazon EC2-虛擬伺服器託管。
開始建立您的 Amazon EC2 執行個體。如需詳細資訊，請參閱開始使用 Amazon EC2 Linux 執行個體。

另一個需要考慮的策略是使用與 IAM 聯合身分識別來整合您現有的身分識別提供者系統和資源。如果您已有公司身分提供者，或已設定為使用 Web 身分提供者來支援使用者，則此策略特別有用。聯合身分可讓您授予 AWS 資源的安全存取權 CodePipeline，包括無需建立或管理 IAM 使用者。您可以使用功能和政策以符合密碼安全要求和輪換登入資料。您可以使用範例應用程式做為您自己設計的範本。

設定聯合身分

進一步了解 IAM 身分聯合。如需資訊，請參閱管理聯合。
檢閱授予臨時存取藍本中的範例，以識別最符合您自訂動作需求的臨時存取藍本。
檢閱與基礎設施相關的聯合身分程式碼範例，例如：
- 適用於 Active Directory 使用案例的聯合身分範例應用程式
開始設定聯合身分。如需詳細資訊，請參閱 IAM 使用者指南中的身分識別提供者和聯

運行自定義操作和工作線程 AWS 帳戶時，請執行以下其中一項以在您的下面使用。

如果使用者想要與 AWS 之外的 AWS Management Console. 授與程式設計存 AWS取權的方式取決於正在存取的使用者類型。

若要授與使用者程式設計存取權，請選擇下列其中一個選項。

哪個使用者需要程式設計存取權？	到	By
人力身分 (IAM Identity Center 中管理的使用者)	使用臨時登入資料來簽署對 AWS CLI、 AWS SDK 或 AWS API 的程式設計要求。	請依照您要使用的介面所提供的指示操作。如需詳細資訊 AWS CLI，請參閱《使 AWS CLI 用AWS Command Line Interface者指南》 AWS IAM Identity Center中的〈配置使用〉。如需 AWS SDK、工具和 AWS API，請參閱 AWS SDK 和工具參考指南中的 IAM 身分中心身分驗證。
IAM	使用臨時登入資料來簽署對 AWS CLI、 AWS SDK 或 AWS API 的程式設計要求。	遵循《IAM 使用者指南》中的〈將臨時登入資料搭配 AWS 資源使用〉中的指示
IAM	(不建議使用) 使用長期認證來簽署對 AWS CLI、 AWS SDK 或 AWS API 的程式設計要求。	請依照您要使用的介面所提供的指示操作。如需相關資訊 AWS CLI，請參閱使用指南中的使用 IAM 使用者登入資料進行驗證。AWS Command Line Interface 對於 AWS SDK 和工具，請參閱 AWS SDK 和工具參考指南中的使用長期憑據進行身份驗證。如需 AWS API，請參閱 IAM 使用者指南中的管理 IAM 使用者的存取金鑰。

哪個使用者需要程式設計存取權？

到

人力身分

(IAM Identity Center 中管理的使用者)

使用臨時登入資料來簽署對 AWS CLI、 AWS SDK 或 AWS API 的程式設計要求。

請依照您要使用的介面所提供的指示操作。

如需詳細資訊 AWS CLI，請參閱《使 AWS CLI 用AWS Command Line Interface者指南》 AWS IAM Identity Center中的〈配置使用〉。
如需 AWS SDK、工具和 AWS API，請參閱 AWS SDK 和工具參考指南中的 IAM 身分中心身分驗證。

IAM

使用臨時登入資料來簽署對 AWS CLI、 AWS SDK 或 AWS API 的程式設計要求。

遵循《IAM 使用者指南》中的〈將臨時登入資料搭配 AWS 資源使用〉中的指示

IAM

(不建議使用)

使用長期認證來簽署對 AWS CLI、 AWS SDK 或 AWS API 的程式設計要求。

請依照您要使用的介面所提供的指示操作。

如需相關資訊 AWS CLI，請參閱使用指南中的使用 IAM 使用者登入資料進行驗證。AWS Command Line Interface
對於 AWS SDK 和工具，請參閱 AWS SDK 和工具參考指南中的使用長期憑據進行身份驗證。
如需 AWS API，請參閱 IAM 使用者指南中的管理 IAM 使用者的存取金鑰。

您可以建立下列範例政策，以與自訂任務工作者搭配使用。此政策僅做為範例使用，並以現狀提供。


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codepipeline:PollForJobs",
        "codepipeline:AcknowledgeJob",
        "codepipeline:GetJobDetails",
        "codepipeline:PutJobSuccessResult",
        "codepipeline:PutJobFailureResult"
      ],
      "Resource": [
        "arn:aws:codepipeline:us-east-2::actionType:custom/Build/MyBuildProject/1/"  
      ]              
    }
  ]
}

注意

請考慮使用受AWSCodePipelineCustomActionAccess管理的原則。

開發自訂動作的任務工作者

選擇權限管理策略之後，您應該考慮工作者的互動方式 CodePipeline。下列高階圖表顯示建置程序的自訂動作和工作背景工作者的工作流程。

您的工作者 CodePipeline 使用PollForJobs.
管道來源階段中的變更觸發管道時 (例如，開發人員確認變更時)，即會開始自動化發行程序。程序會繼續進行，直到設定自訂動作的階段為止。當它在此階段達到您的動作時，會將工作 CodePipeline 排入佇列。如果您的任務工作者再次呼叫 PollForJobs 以取得狀態，則會顯示此任務。從 PollForJobs 取得任務詳細資訊，並將它傳遞回任務工作者。
工作人員打電話AcknowledgeJob給發送 CodePipeline 工作確認。 CodePipeline 傳回確認，指出工作 Worker 應該繼續工作 (InProgress)，或者，如果您有一個以上的工作 Worker 輪詢工作，而另一個工作 Worker 已宣告該工作，則會傳回錯InvalidNonceException誤回應。InProgress確認後， CodePipeline 等待結果返回。
工作 Worker 會在修訂版本上初始化您的自訂動作，然後執行您的動作。與任何其他動作一起，您的自訂動作會將結果傳回給工作 Worker。在建立自訂動作的範例中，動作會從 Amazon S3 儲存貯體提取成品、建立成品，然後將成功建置的成品推送回 Amazon S3 儲存貯體。
執行動作時，工作工作者可以使PutJobSuccessResult用延續權杖 (工作者產生的作業狀態的序列化，例如 JSON 格式的建置識別碼或 Amazon S3 物件金鑰) 呼叫，以及將用於填入連結的ExternalExecutionIdexecutionUrlTemplate資訊。這將使用指向特定操作詳細信息的工作鏈接更新管道的控制台視圖。雖然不需要，但為最佳實務，因為它可讓使用者檢視執行中自訂動作的狀態。

呼叫 PutJobSuccessResult 之後，會將任務視為完成。會在中建立包 CodePipeline 含接續權杖的新工作。如果您的任務工作者再次呼叫 PollForJobs，則會顯示此任務。新的任務可以用來檢查動作的狀態，並以接續字符傳回，或在動作完成之後以不含接續字符傳回。

注意
如果您的任務工作者執行所有適用於自訂動作的工作，則應該考慮將您的任務工作者處理分為至少兩個步驟。第一個步驟會建立您動作的詳細資訊頁面。在您建立詳細資訊頁面之後，即可序列化任務工作者的狀態，並根據大小限制將它傳回為接續字符 (請參閱配額 AWS CodePipeline)。例如，您可以將動作的狀態寫入用來做為接續字符的字串。任務工作者處理的第二個步驟 (和後續步驟) 會執行動作的實際工作。最後一個步驟會傳回成功或失敗 CodePipeline，最後一個步驟中沒有延續權杖。

如需有關使用延續權杖的詳細資訊，請參閱 CodePipeline API 參考PutJobSuccessResult中的規格。
自訂動作完成後，工作 Worker 會呼叫下列其中一個 API，將 CodePipeline 自訂動作的結果傳回至：
- PutJobSuccessResult沒有延續令牌，這表示自定義操作已成功運行
- PutJobFailureResult，表示自訂動作未成功執行
根據結果，管道會繼續進行下一個動作 (成功) 或停止 (失敗)。

自訂任務工作者架構和範例

在您映射高階工作流程之後，即可建立任務工作者。雖然您自訂動作的特性最終會判斷您任務工作者所需的內容，但是自訂動作的大部分任務工作者都會包含下列功能：

輪詢 CodePipeline 使用的工作PollForJobs。
確認工作並將結果傳回至 CodePipeline 使用AcknowledgeJobPutJobSuccessResult、和PutJobFailureResult。
從管道擷取成品和/或將成品放入 Amazon S3 儲存貯體。若要從 Amazon S3 儲存貯體下載成品，您必須建立一個使用簽名版本 4 簽署 (Sig V4) 的 Amazon S3 用戶端。簽名 V4 是必需的 AWS KMS.

若要將成品上傳到 Amazon S3 儲存貯體，您必須另外設定 Amazon S3 PutObject 請求以使用加密。目前僅支援 AWS 金鑰管理服務 (AWS KMS) 進行加密。 AWS KMS 用途 AWS KMS keys。為了知道是否使用 AWS 受管金鑰或客戶管理的金鑰來上傳人工因素，您的自訂工作者必須查看工作資料並檢查加密金鑰屬性。如果已設定屬性，您應在設定時使用該客戶管理的金鑰 ID AWS KMS。如果索引鍵屬性為 null，您可以使用 AWS 受管金鑰. CodePipeline 除非另有配置， AWS 受管金鑰否則會使用。

如需示範如何在 Java 或 .NET 中建立 AWS KMS 參數的範例，請參閱使用 AWS 開發套件 AWS Key Management Service 在 Amazon S3 中指定參數。如需有關的 Amazon S3 儲存貯體的詳細資訊 CodePipeline，請參閱CodePipeline 概念。

在上提供更複雜的自訂工作 Worker 範例 GitHub。此範例是開放原始碼，並以現狀提供。

Job 背景工作者範例 CodePipeline：從 GitHub 儲存庫下載範例。

將自訂動作新增至管道

擁有工作背景工作者之後，您可以透過建立新動作並在使用「建立管線」精靈時選擇自訂動作、編輯現有管道並新增自訂動作，或使用 SDK 或 API AWS CLI，將自訂動作新增至管道。

注意

如果自訂動作是建置或部署動作，則您可以在 Create Pipeline (建立管道) 精靈中建立包含該自訂動作的管道。如果您的自訂動作是在測試類別中，則您必須編輯現有管道予以新增。

主題

將自訂動作新增至現有管道 (CLI)

將自訂動作新增至現有管道 (CLI)

您可以使用 AWS CLI 將自訂動作新增至現有配管。

開啟終端機工作階段 (Linux、macOS 或 Unix) 或命令提示字元 (Windows)，然後執行get-pipeline指令，將您要編輯的管線結構複製到 JSON 檔案中。例如，針對名為 MyFirstPipeline 的管道，您會輸入下列命令：
```
aws codepipeline get-pipeline --name MyFirstPipeline >pipeline.json
```
此命令不會傳回任何內容，但您建立的檔案應該會顯示在您執行命令的目錄中。

使用任何文字編輯器開啟 JSON 檔案，並修改檔案的結構，以將自訂動作新增至現有階段。

注意

如果您想要您的動作與該階段中的另一個動作平行執行，則請確保您將與該動作相同的 runOrder 值指派給它。

例如，若要修改管道的結構以新增名為 Build 的階段，並將建置自訂動作新增至該階段，您可以先修改 JSON 以新增 Build 階段，再新增部署階段，如下所示：


,
    {
      "name": "MyBuildStage",
      "actions":  [
              {
                "inputArtifacts": [
                {
                   "name": "MyApp"
                 }
                   ],
                    "name": "MyBuildCustomAction",
                    "actionTypeId": {
                        "category": "Build",
                        "owner": "Custom",
                        "version": "1",
                        "provider": "My-Build-Provider-Name"
                    },
                    "outputArtifacts": [
                        {
                          "name": "MyBuiltApp"
                        }
                    ],
                    "configuration": {
                        "ProjectName": "MyBuildProject"
                    },
                    "runOrder": 1
                }
            ]
        },      
        {
            "name": "Staging",
            "actions": [
                    {
                        "inputArtifacts": [
                            {
                                "name": "MyBuiltApp"
                            }
                        ],
                        "name": "Deploy-CodeDeploy-Application",
                        "actionTypeId": {
                            "category": "Deploy",
                            "owner": "AWS",
                            "version": "1",
                            "provider": "CodeDeploy"
                        },
                        "outputArtifacts": [],
                        "configuration": {
                            "ApplicationName": "CodePipelineDemoApplication",
                            "DeploymentGroupName": "CodePipelineDemoFleet"
                        },
                        "runOrder": 1
                    }
                ]
             }      
    ]
}

若要套用您的變更，請執行 update-pipeline 命令，並指定管道 JSON 檔案，與下面類似：
重要
請確認在檔案名稱之前包含 file://。這是此命令必要項目。
```
aws codepipeline update-pipeline --cli-input-json file://pipeline.json
```
此命令會傳回所編輯管道的整個結構。
開啟主 CodePipeline 控台，然後選擇您剛才編輯的管線名稱。

此管道會顯示您的變更。下次您變更來源位置時，管道會透過修訂過的管道結構來執行該修訂版。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

使用動作類型

在中標記自訂動作 CodePipeline