本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 整合模型參考 第三方服務有數個預先建置的整合，可協助在管道發行程序中建置現有的客戶工具。合作夥伴或第三方服務提供者會使用整合模型來實作動作類型，以便在 CodePipeline 中使用。 當您規劃或使用以 CodePipeline 中支援的整合模型管理的動作類型時，請使用此參考。 若要將您的第三方動作類型認證為與 CodePipeline 的合作夥伴整合，請參閱 AWS 合作夥伴網路 (APN)。此資訊是 [AWS CLI 參考](https://docs.aws.amazon.com/cli/latest/reference/)的補充。 **Topics** + [第三方動作類型如何與整合器搭配使用](#reference-integrations-description) + [概念](#reference-integrations-concepts) + [支援的整合模型](#reference-integrations-models) + [Lambda 整合模型](#reference-integrations-models-lambda) + [任務工作者整合模型](#reference-integrations-models-worker) ## 第三方動作類型如何與整合器搭配使用 您可以將第三方動作類型新增至客戶管道，以完成客戶資源的任務。整合器會管理任務請求，並使用 CodePipeline 執行 動作。下圖顯示為客戶在其管道中使用而建立的第三方動作類型。客戶設定動作之後，動作會執行並建立由整合者的動作引擎處理的任務請求。 ![\[顯示整合工具動作引擎如何處理第三方動作類型和成品的影像\]](http://docs.aws.amazon.com/zh_tw/codepipeline/latest/userguide/images/codepipeline-integration-model.png) 圖表顯示下列步驟： 1. 動作定義已註冊並在 CodePipeline 中提供。第三方動作可供第三方供應商的客戶使用。 1. 供應商的客戶選擇和設定 CodePipeline 中的動作。 1. 動作執行和任務會在 CodePipeline 中排入佇列。當任務在 CodePipeline 中就緒時，它會傳送任務請求。 1. 整合商 （第三方輪詢 APIs 的任務工作者或 Lambda 函數） 會挑選任務請求、傳回確認，並處理動作的成品。 1. 整合器會傳回成功/失敗輸出 （任務工作者使用成功/失敗 APIs或 Lambda 函數傳送成功/失敗輸出），其中包含任務結果和接續字符。 如需可用來請求、檢視和更新動作類型之步驟的相關資訊，請參閱 [使用動作類型](action-types.md)。 ## 概念 本節針對第三方動作類型使用下列術語： **動作類型** 可重複的程序，可在執行相同持續交付工作負載的管道中重複使用。動作類型由 `Owner`、`Provider`、 `Category`和 識別`Version`。例如： ``` { "Category": "Deploy", "Owner": "AWS", "Provider": "CodeDeploy", "Version": "1" }, ``` 相同類型的所有動作都會共用相同的實作。 **Action** 動作類型的單一執行個體，這是管道階段內發生的其中一個分散程序。這通常包含此動作執行所在管道特有的使用者值。 **動作定義** 動作類型的結構描述，定義設定動作和輸入/輸出成品所需的屬性。 **動作執行** 已執行以判斷客戶管道上的動作是否成功的任務集合。 **動作執行引擎** 動作執行組態的 屬性，定義動作類型使用的整合類型。有效值為 `JobWorker` 和 `Lambda`。 **整合** 描述整合器執行以實作動作類型的軟體片段。CodePipeline 支援對應至兩個支援動作引擎 `JobWorker`和 的兩種整合類型`Lambda`。 **整合工具** 擁有 動作類型實作的人員。 **任務** 使用管道和客戶內容來執行整合的一段工作。動作執行由一或多個任務組成。 **任務工作者** 處理客戶輸入並執行任務的服務。 ## 支援的整合模型 CodePipeline 有兩個整合模型： + **Lambda 整合模型：**此整合模型是使用 CodePipeline 中動作類型的偏好方式。Lambda 整合模型使用 Lambda 函數，在您的動作執行時處理任務請求。 + **任務工作者整合模型：**任務工作者整合模型是先前用於第三方整合的模型。任務工作者整合模型使用設定為在動作執行時聯絡 CodePipeline APIs的任務工作者來處理任務請求。 為了進行比較，下表說明兩種模型的功能： **** | | **Lambda 整合模型** | **任務工作者整合模型** | | --- | --- | --- | | Description | 整合器會將整合寫入 Lambda 函數，每當有任務可供 動作使用時，CodePipeline 就會叫用此函數。Lambda 函數不會輪詢可用的任務，而是等到收到下一個任務請求。 | 整合器會將整合寫入為任務工作者，持續輪詢客戶管道上可用的任務。然後，任務工作者會執行任務，並使用 CodePipeline APIs 將任務結果提交回 CodePipeline。 | | 基礎設施 | AWS Lambda | 將任務工作者程式碼部署到整合者的基礎設施，例如 Amazon EC2 執行個體。 | | 開發工作 | 整合僅包含商業邏輯。 | 除了包含商業邏輯之外，整合還需要與 CodePipeline APIs 互動。 | | 操作工作 | 較少的營運工作，因為基礎設施只是 AWS 資源。 | 由於任務工作者需要其獨立硬體，因此作業工作量更高。 | | 最大任務執行時間 | 如果整合需要主動執行超過 15 分鐘，則無法使用此模型。此動作適用於需要啟動程序的整合商 （例如，根據客戶的程式碼成品啟動組建），並在完成時傳回結果。我們不建議整合器繼續等待建置完成。反之，請傳回接續。如果從整合器的程式碼收到接續任務，則 CodePipeline 會在 30 秒內建立新的任務，以檢查任務，直到任務完成為止。 | 使用此模型可以持續執行非常長的任務 （小時/天）。 | ## Lambda 整合模型 支援的 Lambda 整合模型包括建立 Lambda 函數，以及定義第三方動作類型的輸出。 ### 更新您的 Lambda 函數以處理 CodePipeline 的輸入 您可以建立新的 Lambda 函數。您可以將業務邏輯新增至 Lambda 函數，只要管道上有動作類型可用的任務時，就會執行該函數。例如，根據客戶和管道的內容，您可能想要在客戶的服務中開始建置。 使用下列參數來更新您的 Lambda 函數，以處理 CodePipeline 的輸入。 **格式：** + `jobId`: + 任務的唯一系統產生的 ID。 + 類型：字串 + 模式：【0-9a-f】\$18\$1-【0-9a-f】\$14\$1-【0-9a-f】\$14\$1-【0-9a-f】\$14\$1-【0-9a-f】\$112\$1 + `accountId`: + 執行任務時要使用的客戶 AWS 帳戶 ID。 + 類型：字串 + 模式：【0-9】\$112\$1 + `data`: + 整合用來完成任務之任務的其他資訊。 + 包含下列項目的映射： + `actionConfiguration`: + 動作的組態資料。動作組態欄位是索引鍵/值對的映射，供您的客戶輸入值。當您設定動作時，金鑰是由動作類型定義檔案中的金鑰參數決定。在此範例中，值是由在 `Username`和 `Password` 欄位中指定資訊的動作使用者決定。 + 類型：字串對字串映射，選擇性存在 範例： ``` "configuration": { "Username": "MyUser", "Password": "MyPassword" }, ``` + `encryptionKey`: + 代表用於加密成品存放區中資料之金鑰的相關資訊，例如 AWS KMS 金鑰。 + 內容：資料類型 的類型`encryptionKey`，選擇性存在 + `inputArtifacts`: + 要處理之成品的相關資訊清單，例如測試或建置成品。 + 內容：資料類型 的清單`Artifact`，選擇性存在 + `outputArtifacts`: + 動作輸出的相關資訊清單。 + 內容：資料類型 的清單`Artifact`，選擇性存在 + `actionCredentials`: + 代表 AWS 工作階段登入資料物件。這些登入資料是由 發行的臨時登入資料 AWS STS。它們可用於存取 S3 儲存貯體中的輸入和輸出成品，用於在 CodePipeline 中存放管道的成品。 這些登入資料也有與動作類型定義檔案中指定政策陳述式範本相同的許可。 + 內容：資料類型 的類型`AWSSessionCredentials`，選擇性存在 + `actionExecutionId`: + 動作執行的外部 ID。 + 類型：字串 + `continuationToken`: + 任務以非同步方式繼續任務所需的系統產生的字符，例如部署 ID。 + 類型：字串，選擇性存在 **資料類型：** + `encryptionKey`: + `id`: + 用來識別金鑰的 ID。對於 AWS KMS 金鑰，您可以使用金鑰 ID、金鑰 ARN 或別名 ARN。 + 類型：字串 + `type`: + 加密金鑰的類型，例如 AWS KMS 金鑰。 + 類型：字串 + 有效值：`KMS` + `Artifact`: + `name`: + 成品的名稱。 + 類型：字串，選擇性存在 + `revision`: + 成品的修訂 ID。根據物件的類型，這可能是遞交 ID (GitHub) 或修訂 ID (Amazon S3)。 + 類型：字串，選擇性存在 + `location`: + 成品的位置。 + 內容：資料類型 的類型`ArtifactLocation`，選擇性存在 + `ArtifactLocation`: + `type`: + 位置中的成品類型。 + 類型：字串，選擇性存在 + 有效值：`S3` + `s3Location`: + 包含修訂的 S3 儲存貯體位置。 + 內容：資料類型 的類型`S3Location`，選擇性存在 + `S3Location`: + `bucketName`: + S3 儲存貯體的名稱。 + 類型：字串 + `objectKey`: + S3 儲存貯體中物件的索引鍵，可唯一識別儲存貯體中的物件。 + 類型：字串 + `AWSSessionCredentials`: + `accessKeyId`: + 工作階段的存取金鑰。 + 類型：字串 + `secretAccessKey`: + 工作階段的私密存取金鑰。 + 類型：字串 + `sessionToken`: + 工作階段的字符。 + 類型：字串 範例： ``` { "jobId": "01234567-abcd-abcd-abcd-012345678910", "accountId": "012345678910", "data": { "actionConfiguration": { "key1": "value1", "key2": "value2" }, "encryptionKey": { "id": "123-abc", "type": "KMS" }, "inputArtifacts": [ { "name": "input-art-name", "location": { "type": "S3", "s3Location": { "bucketName": "inputBucket", "objectKey": "inputKey" } } } ], "outputArtifacts": [ { "name": "output-art-name", "location": { "type": "S3", "s3Location": { "bucketName": "outputBucket", "objectKey": "outputKey" } } } ], "actionExecutionId": "actionExecutionId", "actionCredentials": { "accessKeyId": "access-id", "secretAccessKey": "secret-id", "sessionToken": "session-id" }, "continuationToken": "continueId-xxyyzz" } } ``` ### 將 Lambda 函數的結果傳回 CodePipeline 整合者的任務工作者資源必須在成功、失敗或持續情況下傳回有效的承載。 **格式：** + `result`：任務的結果。 + 必要 + 有效值 （不區分大小寫）： + `Success`：表示任務成功並結束。 + `Continue`：表示任務成功且必須繼續，例如，如果針對相同的動作執行重新叫用任務工作者。 + `Fail`：表示任務失敗且為終端機。 + `failureType`：要與失敗任務相關聯的失敗類型。 合作夥伴動作的`failureType`類別描述執行任務時遇到的失敗類型。將任務失敗結果傳回 CodePipeline 時，整合工具會設定 類型以及失敗訊息。 + 選用。如果結果為 ，則為必要`Fail`。 + 如果 是 `Success`或 ，則必須`result`為 null `Continue` + 有效值： + ConfigurationError + JobFailed + PermissionsError + RevisionOutOfSync + RevisionUnavailable + SystemUnavailable + `continuation`：要傳遞給目前動作執行中下一個任務的持續狀態。 + 選用。如果結果為 ，則為必要`Continue`。 + 如果 `result`是 `Success`或 ，則必須為 null`Fail`。 + 屬性： + `State`：要傳遞的狀態雜湊。 + `status`：動作執行的狀態。 + 選用。 + 屬性： + `ExternalExecutionId`：要與任務建立關聯的選用外部執行 ID 或遞交 ID。 + `Summary`：所發生情況的選用摘要。在失敗案例中，這會成為使用者看到的失敗訊息。 + `outputVariables`：一組要傳遞給下一個動作執行的金鑰/值對。 + 選用。 + 如果 `result`是 `Continue`或 ，則必須為 null`Fail`。 範例： ``` { "result": "success", "failureType": null, "continuation": null, "status": { "externalExecutionId": "my-commit-id-123", "summary": "everything is dandy" }, "outputVariables": { "FirstOne": "Nice", "SecondOne": "Nicest", ... } } ``` ### 使用接續字符等待非同步程序的結果 `continuation` 字符是 Lambda 函數承載和結果的一部分。這是一種將任務狀態傳遞至 CodePipeline 並指出任務需要繼續的方式。例如，在整合商在其資源上為客戶啟動組建後，不會等待組建完成，而是向 CodePipeline 指出其沒有最終結果，方法是將 傳回`result`為 ，`continue`並將組建的唯一 ID 傳回給 CodePipeline 做為`continuation`權杖。 **注意** Lambda 函數最多只能執行 15 分鐘。如果任務需要執行更長的時間，您可以使用接續字符。 CodePipeline 團隊會在 30 秒後在其承載中使用相同的`continuation`字符叫用整合器，以便檢查整合器是否完成。如果建置完成，整合器會傳回終端機成功/失敗結果，否則會繼續。 ### 提供 CodePipeline 在執行時間叫用整合器 Lambda 函數的許可 您可以將許可新增至整合器 Lambda 函數，以提供 CodePipeline 服務使用 CodePipeline 服務主體叫用它的許可：`codepipeline.amazonaws.com`。您可以使用 CloudFormation 或命令列新增許可。如需範例，請參閱 [使用動作類型](action-types.md)。 ## 任務工作者整合模型 設計好高階工作流程之後，您就可以建立任務工作者。雖然第三方動作的詳細資訊決定了任務工作者的需求，但大多數第三方動作的任務工作者都包含下列功能： + 使用 從 CodePipeline 輪詢任務`PollForThirdPartyJobs`。 + 使用 `AcknowledgeThirdPartyJob`、 和 確認任務並將結果傳回 CodePipeline`PutThirdPartyJobSuccessResult``PutThirdPartyJobFailureResult`。 + 從管道的 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)`請求設定為透過 AWS Key Management Service (AWS KMS). AWS KMS uses 使用加密 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)。 ### 選擇和設定任務工作者的許可管理策略 若要在 CodePipeline 中開發第三方動作的任務工作者，您需要整合使用者和許可管理的策略。 最簡單的策略是使用 AWS Identity and Access Management (IAM) 執行個體角色建立 Amazon EC2 執行個體，為任務工作者新增所需的基礎設施，讓您可以輕鬆擴展整合所需的資源。您可以使用與 的內建整合 AWS 來簡化任務工作者與 CodePipeline 之間的互動。 進一步了解 Amazon EC2，並判斷它是否適合您的整合。如需詳細資訊，請參閱 [Amazon EC2 - Virtual Server 託管](https://aws.amazon.com/ec2)。如需設定 Amazon EC2 執行個體的資訊，請參閱 [Amazon EC2 Linux 執行個體入門](https://docs.aws.amazon.com/AWSEC2/latest/GettingStartedGuide/)。 另一個要考慮的策略是使用聯合身分與 IAM 來整合現有的身分提供者系統和資源。如果您已有企業身分提供者，或已設定為支援使用 Web 身分提供者的使用者，則此策略非常有用。聯合身分可讓您授予 AWS 資源的安全存取權，包括 CodePipeline，而無需建立或管理 IAM 使用者。您可以使用功能和政策以符合密碼安全要求和輪換登入資料。您可以使用範例應用程式做為您自己設計的範本。如需資訊，請參閱[管理聯合](https://aws.amazon.com/iam/details/manage-federation/)。 若要提供存取權，請新增權限至您的使用者、群組或角色： + 中的使用者和群組 AWS IAM Identity Center： 建立權限合集。請按照《*AWS IAM Identity Center 使用者指南*》中的[建立權限合集](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html)說明進行操作。 + 透過身分提供者在 IAM 中管理的使用者： 建立聯合身分的角色。遵循《*IAM 使用者指南*》的[為第三方身分提供者 (聯合) 建立角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html)中的指示。 + IAM 使用者： + 建立您的使用者可擔任的角色。請按照《*IAM 使用者指南*》的[為 IAM 使用者建立角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html)中的指示。 + (不建議) 將政策直接附加至使用者，或將使用者新增至使用者群組。請遵循《*IAM 使用者指南*》的[新增許可到使用者 (主控台)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) 中的指示。 以下是您可以建立以搭配第三方任務工作者使用的範例政策。此政策僅做為範例使用，並以現狀提供。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "codepipeline:PollForThirdPartyJobs", "codepipeline:AcknowledgeThirdPartyJob", "codepipeline:GetThirdPartyJobDetails", "codepipeline:PutThirdPartyJobSuccessResult", "codepipeline:PutThirdPartyJobFailureResult" ], "Resource": [ "arn:aws:codepipeline:us-east-2::actionType:ThirdParty/Build/Provider/1/" ] } ] } ``` ------