本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在 CodePipeline 中建立和新增自訂動作 AWS CodePipeline 包含許多動作，可協助您設定自動化發行程序的建置、測試和部署資源。如果您的發行程序包含預設動作中未包含的活動 (例如內部開發的建置程序或測試套件)，您可以建立該用途的自訂動作，並將其包含在管道中。您可以使用 AWS CLI 在與 AWS 您的帳戶相關聯的管道中建立自訂動作。 您可以為下列動作類別建立自訂 AWS CodePipeline 動作： + 建置或轉換項目的自訂建置動作 + 將項目部署至一或多個伺服器、網站或儲存庫的自訂部署動作 + 設定和執行自動化測試的自訂測試動作 + 執行函數的自訂呼叫動作 當您建立自訂動作時，也必須建立任務工作者，以輪詢 CodePipeline 以取得此自訂動作的任務請求、執行任務，並將狀態結果傳回 CodePipeline。只要此任務工作者可存取 CodePipeline 的公有端點，就可以位於任何電腦或資源上。若要輕鬆管理存取和安全性，請考慮在 Amazon EC2 執行個體上託管您的任務工作者。 下圖顯示管道的高階檢視，其中包含自訂建置動作： ![管道的高階檢視，其中包含自訂建置動作。](http://docs.aws.amazon.com/zh_tw/codepipeline/latest/userguide/images/PipelineCustomActionCS.png) 當管道包含自訂動作做為階段的一部分時，管道會建立任務請求。自訂任務工作者偵測到該請求，並執行該任務 (在此範例中，為使用第三方建置軟體的自訂程序)。動作完成時，任務工作者會傳回成功結果或失敗結果。如果收到成功結果，管道會將修訂及其成品提供給下一個動作。如果傳回失敗，管道不會提供管道中下一個動作的修訂。 **注意** 這些說明假設您已完成[CodePipeline 入門](getting-started-codepipeline.md) 中的步驟。 **Topics** + [建立自訂動作](#actions-create-custom-action-cli) + [建立自訂動作的任務工作者](#actions-create-custom-action-job-worker) + [將自訂動作新增至管道](#actions-create-custom-action-add) ## 建立自訂動作 **使用 建立自訂動作 AWS CLI** 1. 開啟文字編輯器，並為您的自訂動作建立 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 中標記資源的詳細資訊，請參閱 [標記 資源](tag-resources.md)。 JSON 檔案中包含兩個屬性：`entityUrlTemplate` 和 `executionUrlTemplate`。您可以遵循 `{Config:{{name}}}` 格式來參照 URL 範本內自訂動作組態屬性中的名稱，只要組態屬性同時為必要且不是秘密。例如，在上述範例中，`entityUrlTemplate` 值參照組態屬性 {{ProjectName}}。 + `entityUrlTemplate`：靜態連結，可提供動作服務提供者的相關資訊。在此範例中，建置系統包含每個建置專案的靜態連結。此連結格式會根據建置提供者而不同 (或者，如果您建立不同的動作類型 (例如測試)，則為其他服務提供者)。您必須提供此連結格式，在新增自訂動作時，使用者可以選擇此連結，以將瀏覽器開啟到您網站上提供建置專案 (或測試環境) 特性的頁面。 + `executionUrlTemplate`：動態連結，可使用目前或最近執行動作的相關資訊予以更新。當您的自訂任務工作者更新任務狀態 (例如，成功、失敗或進行中) 時，也會提供將用來完成連結的 `externalExecutionId`。此連結可以用來提供動作執行的詳細資訊。 例如，當您在管道中檢視動作時，請參閱下列兩個連結： ![CodePipeline 主控台中的連結可提供有關管道執行的詳細資訊。](http://docs.aws.amazon.com/zh_tw/codepipeline/latest/userguide/images/codepipeline-calinksexplained.png) ![1](http://docs.aws.amazon.com/zh_tw/codepipeline/latest/userguide/images/number-1.png) 在您新增自訂動作並指向 `entityUrlTemplate` 中的地址 (於建立自訂動作時所指定) 之後，會出現此靜態連結。 ![2](http://docs.aws.amazon.com/zh_tw/codepipeline/latest/userguide/images/number-2.png) 在每次執行動作並指向 `executionUrlTemplate` 中的地址 (於建立自訂動作時所指定) 之後，會更新動態連結。 如需這些連結類型以及 `RevisionURLTemplate`和 的詳細資訊`ThirdPartyURL`，請參閱 [CodePipeline API 參考](https://docs.aws.amazon.com/codepipeline/latest/APIReference/)中的 [ActionTypeSettings](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_ActionTypeSettings.html) 和 [CreateCustomActionType](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_CreateCustomActionType.html)。如需動作結構需求以及如何建立動作的詳細資訊，請參閱 [CodePipeline 管道結構參考](reference-pipeline-structure.md)。 1. 儲存 JSON 檔案，並提供您可以輕鬆記住的名稱 （例如 {{MyCustomAction}}.json)。 1. 在已安裝 AWS CLI的電腦上，開啟終端機工作階段 (Linux、OS X、Unix) 或命令提示字元 (Windows)。 1. 使用 AWS CLI 執行 **aws codepipeline create-custom-action-type**命令，指定您剛建立的 JSON 檔案名稱。 例如，若要建立建置自訂動作： **重要** 請確認在檔案名稱之前包含 `file://`。這是此命令必要項目。 ``` aws codepipeline create-custom-action-type --cli-input-json file://{{MyCustomAction}}.json ``` 1. 此命令會傳回您所建立自訂動作的整個結構，以及為您新增的 `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 的自訂任務工作者。 **Topics** + [選擇和設定任務工作者的許可管理策略](#actions-create-custom-action-permissions) + [開發自訂動作的任務工作者](#actions-create-custom-action-job-worker-workflow) + [自訂任務工作者架構和範例](#actions-create-custom-action-job-worker-common) ### 選擇和設定任務工作者的許可管理策略 若要在 CodePipeline 中為您的自訂動作開發自訂任務工作者，您需要整合使用者和許可管理的策略。 最簡單的策略是使用 IAM 執行個體角色建立 Amazon EC2 執行個體，以新增自訂任務工作者所需的基礎設施，讓您可以輕鬆擴展整合所需的資源。您可以使用與 的內建整合 AWS ，簡化自訂任務工作者與 CodePipeline 之間的互動。 **設定 Amazon EC2 執行個體** 1. 進一步了解 Amazon EC2，並判斷它是否適合您的整合。如需詳細資訊，請參閱 [Amazon EC2 - Virtual Server 託管](https://aws.amazon.com/ec2)。 1. 開始建立 Amazon EC2 執行個體。如需詳細資訊，請參閱 [Amazon EC2 Linux 執行個體入門](https://docs.aws.amazon.com/AWSEC2/latest/GettingStartedGuide/)。 另一個要考慮的策略是使用聯合身分與 IAM 來整合現有的身分提供者系統和資源。如果您已有公司身分提供者，或已設定為使用 Web 身分提供者來支援使用者，則此策略特別有用。聯合身分可讓您授予 AWS 資源的安全存取權，包括 CodePipeline，而無需建立或管理 IAM 使用者。您可以使用功能和政策以符合密碼安全要求和輪換登入資料。您可以使用範例應用程式做為您自己設計的範本。 **設定聯合身分** 1. 進一步了解 IAM 聯合身分。如需資訊，請參閱[管理聯合](https://aws.amazon.com/iam/details/manage-federation/)。 1. 檢閱[授予臨時存取藍本](https://docs.aws.amazon.com/STS/latest/UsingSTS/STSUseCases.html)中的範例，以識別最符合您自訂動作需求的臨時存取藍本。 1. 檢閱與基礎設施相關的聯合身分程式碼範例，例如： + [適用於 Active Directory 使用案例的聯合身分範例應用程式](https://aws.amazon.com/code/1288653099190193) 1. 開始設定聯合身分。如需詳細資訊，請參閱《*IAM 使用者指南*[》中的身分提供者和聯合](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html)。 在執行自訂動作和任務工作者 AWS 帳戶 時，在 下使用下列其中一項。 如果使用者想要與 AWS 外部互動，則需要程式設計存取權 AWS 管理主控台。授予程式設計存取權的方式取決於正在存取的使用者類型 AWS。 若要授予使用者程式設計存取權，請選擇下列其中一個選項。 **** | 哪個使用者需要程式設計存取權？ | 到 | 根據 | | --- | --- | --- | | IAM | （建議） 使用主控台登入資料做為臨時登入資料，以簽署對 AWS CLI、 AWS SDKs程式設計請求。 AWS APIs | 請依照您要使用的介面所提供的指示操作。[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/codepipeline/latest/userguide/actions-create-custom-action.html) | | 人力資源身分
(IAM Identity Center 中管理的使用者) | 使用暫時登入資料簽署對 AWS CLI、 AWS SDKs程式設計請求。 AWS APIs | 請依照您要使用的介面所提供的指示操作。[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/codepipeline/latest/userguide/actions-create-custom-action.html) | | IAM | 使用暫時登入資料簽署對 AWS CLI、 AWS SDKs程式設計請求。 AWS APIs | 遵循《IAM 使用者指南》中[將臨時登入資料與 AWS 資源](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html)搭配使用的指示。 | | IAM | (不建議使用)使用長期憑證簽署對 AWS CLI、 AWS SDKs程式設計請求。 AWS APIs | 請依照您要使用的介面所提供的指示操作。[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/codepipeline/latest/userguide/actions-create-custom-action.html) | 您可以建立下列範例政策，以與自訂任務工作者搭配使用。此政策僅做為範例使用，並以現狀提供。 ------ #### [ JSON ] **** ``` { "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 互動。下列高階圖表顯示建置程序的自訂動作和任務工作者工作流程。 ![建置程序的自訂動作和任務工作者工作流程。](http://docs.aws.amazon.com/zh_tw/codepipeline/latest/userguide/images/PipelineCustomAgent.png) 1. 您的任務工作者會使用 輪詢任務的 CodePipeline`PollForJobs`。 1. 管道來源階段中的變更觸發管道時 (例如，開發人員確認變更時)，即會開始自動化發行程序。程序會持續進行，直到已設定自訂動作的階段為止。當它在此階段到達您的動作時，CodePipeline 會將任務排入佇列。如果您的任務工作者再次呼叫 `PollForJobs` 以取得狀態，則會顯示此任務。從 `PollForJobs` 取得任務詳細資訊，並將它傳遞回任務工作者。 1. 任務工作者呼叫 `AcknowledgeJob`傳送任務確認給 CodePipeline。CodePipeline 會傳回確認，指出任務工作者應繼續任務 (`InProgress`)，或者，如果您有一個以上的任務工作者輪詢任務，而另一個任務工作者已申請任務，則會傳回`InvalidNonceException`錯誤回應。`InProgress` 在確認之後，CodePipeline 會等待結果傳回。 1. 任務工作者會在修訂版上啟動您的自訂動作，然後執行您的動作。除了任何其他動作之外，您的自訂動作也會將結果傳回給任務工作者。在建置自訂動作範例中，動作會從 Amazon S3 儲存貯體提取成品、建置成品，並將成功建置的成品推回 Amazon S3 儲存貯體。 1. 動作執行時，任務工作者可以使用`PutJobSuccessResult`接續字符呼叫 （任務工作者產生的任務狀態序列化，例如 JSON 格式的組建識別符或 Amazon S3 物件金鑰），以及將用於在 中填入連結`ExternalExecutionId`的資訊`executionUrlTemplate`。這將在管道進行時，使用特定動作詳細資訊的工作連結來更新管道的主控台檢視。雖然不需要，但為最佳實務，因為它可讓使用者檢視執行中自訂動作的狀態。 呼叫 `PutJobSuccessResult` 之後，會將任務視為完成。在 CodePipeline 中建立新的任務，其中包含接續字符。如果您的任務工作者再次呼叫 `PollForJobs`，則會顯示此任務。新的任務可以用來檢查動作的狀態，並以接續字符傳回，或在動作完成之後以不含接續字符傳回。 **注意** 如果您的任務工作者執行所有適用於自訂動作的工作，則應該考慮將您的任務工作者處理分為至少兩個步驟。第一個步驟會建立您動作的詳細資訊頁面。在您建立詳細資訊頁面之後，即可序列化任務工作者的狀態，並根據大小限制將它傳回為接續字符 (請參閱 [AWS CodePipeline 中的配額](limits.md))。例如，您可以將動作的狀態寫入用來做為接續字符的字串。任務工作者處理的第二個步驟 (和後續步驟) 會執行動作的實際工作。最後一個步驟會將成功或失敗傳回 CodePipeline，而最後一個步驟沒有接續權杖。 如需使用接續字符的詳細資訊，請參閱 [CodePipeline API 參考](https://docs.aws.amazon.com/codepipeline/latest/APIReference)`PutJobSuccessResult`中的 規格。 1. 自訂動作完成後，任務工作者會呼叫兩個 APIs之一，將自訂動作的結果傳回 CodePipeline： + `PutJobSuccessResult` 沒有接續字符，表示自訂動作已成功執行 + `PutJobFailureResult`，這表示自訂動作未成功執行 根據結果，管道會繼續進行下一個動作 (成功) 或停止 (失敗)。 ### 自訂任務工作者架構和範例 在您映射高階工作流程之後，即可建立任務工作者。雖然您自訂動作的特性最終會判斷您任務工作者所需的內容，但是自訂動作的大部分任務工作者都會包含下列功能： + 使用 從 CodePipeline 輪詢任務`PollForJobs`。 + 使用 `AcknowledgeJob`、 和 確認任務並將結果傳回 CodePipeline`PutJobSuccessResult``PutJobFailureResult`。 + 從管道的 Amazon S3 儲存貯體中擷取成品和/或將成品放入其中。若要從 Amazon S3 儲存貯體下載成品，您必須建立使用 Signature 第 4 版簽署 (Sig V4) 的 Amazon S3 用戶端。需要 Sig V4 AWS KMS。 若要將成品上傳到 Amazon S3 儲存貯體，您必須另外設定 Amazon S3 `[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/SOAPPutObject.html)`請求以使用加密。encryption. AWS KMS uses 目前僅支援 AWS Key Management Service (AWS KMS) AWS KMS keys。為了知道要使用 AWS 受管金鑰 或客戶受管金鑰上傳成品，您的自訂任務工作者必須查看[任務資料](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_JobData.html)並檢查[加密金鑰](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_EncryptionKey.html)屬性。如果已設定 屬性，您應該在設定時使用該客戶受管金鑰 ID AWS KMS。如果金鑰屬性為 null，您可以使用 AWS 受管金鑰。除非另有設定， AWS 受管金鑰 否則 CodePipeline 會使用 。 如需示範如何在 Java 或 .NET 中建立 AWS KMS 參數的範例，請參閱[使用 AWS SDKs 在 Amazon S3 AWS Key Management Service 中指定](https://docs.aws.amazon.com/AmazonS3/latest/userguide/kms-using-sdks.html) 。如需 CodePipeline 的 Amazon S3 儲存貯體的詳細資訊，請參閱 [CodePipeline 概念](concepts.md)。 GitHub 上提供更複雜的自訂任務工作者範例。此範例是開放原始碼，並以現狀提供。 + [CodePipeline 的範例任務工作者](https://github.com/awslabs/aws-codepipeline-custom-job-worker)：從 GitHub 儲存庫下載範例。 ## 將自訂動作新增至管道 擁有任務工作者之後，您可以透過建立新的管道，並在使用建立管道精靈時選擇它、編輯現有管道並新增自訂動作，或使用 AWS CLI、 SDKs 或 APIs，將自訂動作新增至管道。 **注意** 如果自訂動作是建置或部署動作，則您可以在 Create Pipeline (建立管道) 精靈中建立包含該自訂動作的管道。如果您的自訂動作是在測試類別中，則您必須編輯現有管道予以新增。 **Topics** + [將自訂動作新增至現有管道 (CLI)](#actions-create-custom-action-add-cli) ### 將自訂動作新增至現有管道 (CLI) 您可以使用 AWS CLI 將自訂動作新增至現有的管道。 1. 開啟終端機工作階段 (Linux、macOS 或 Unix) 或命令提示字元 (Windows)，然後執行 **get-pipeline**命令，將您要編輯的管道結構複製到 JSON 檔案。例如，針對名為 **MyFirstPipeline** 的管道，您會輸入下列命令： ``` aws codepipeline get-pipeline --name {{MyFirstPipeline}} >{{pipeline.json}} ``` 此命令不會傳回任何內容，但您建立的檔案應該會顯示在您執行命令的目錄中。 1. 使用任何文字編輯器開啟 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 } ] }{{ }} ] } ``` 1. 若要套用您的變更，請執行 **update-pipeline** 命令，並指定管道 JSON 檔案，與下面類似： **重要** 請確認在檔案名稱之前包含 `file://`。這是此命令必要項目。 ``` aws codepipeline update-pipeline --cli-input-json file://{{pipeline.json}} ``` 此命令會傳回所編輯管道的整個結構。 1. 開啟 CodePipeline 主控台，然後選擇您剛編輯的管道名稱。 此管道會顯示您的變更。下次您變更來源位置時，管道會透過修訂過的管道結構來執行該修訂版。