本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 集成模型参考 我们预先构建了若干第三方服务集成，有助于将现有的客户工具植入管道发布流程。合作伙伴或第三方服务提供商使用集成模型来实现操作类型，以便在中使用 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_cn/codepipeline/latest/userguide/images/codepipeline-integration-model.png) 图中显示以下步骤： 1. 操作定义已在中注册并可用 CodePipeline。第三方提供商的客户可以使用第三方操作。 1. 提供商的客户在中选择并配置操作。 CodePipeline 1. 操作将运行，作业已进入队列。 CodePipeline当作业准备就绪时 CodePipeline，它会发送任务请求。 1. 集成商（第三方轮询 APIs 或 Lambda 函数的作业工作人员）接收任务请求，返回确认信息，然后处理操作的构件。 1. 集成器返回 success/failure 带有作业结果和延续令牌的success/failure APIs or the Lambda function sends success/failure输出（作业工作人员使用输出）。 有关可用于请求、查看和更新操作类型的步骤的信息，请参阅[使用操作类型](action-types.md)。 ## 概念 本节对第三方操作类型使用以下术语： **操作类型** 一种可重复的流程，可在执行相同持续交付工作负载的管道中重复使用。操作类型由 `Owner`、`Category`、`Provider` 和 `Version` 标识。例如： ``` { "Category": "Deploy", "Owner": "AWS", "Provider": "CodeDeploy", "Version": "1" }, ``` 相同类型的所有操作都采用相同的实现。 **Action** 操作类型的单个实例，即管道阶段内发生的非连续流程之一。这通常包括特定于运行此操作的管道的用户值。 **操作定义** 操作类型的架构，用于定义配置操作和 input/output 构件所需的属性。 **操作执行** 为确定客户管道上的操作是否成功而运行的一系列任务。 **操作执行引擎** 操作执行配置的一个属性，用于定义操作类型使用的集成类型。有效值为 `JobWorker` 和 `Lambda`。 **集成** 描述由集成商运行的用于实现操作类型的软件。 CodePipeline 支持两种集成类型，分别对应于两个支持的动作引擎`JobWorker`和`Lambda`。 **集成商** 负责实现操作类型的人。 **任务** 利用管道和客户背景来执行集成的一项工作。操作执行包含一个或多个任务。 **任务工作者** 处理客户输入并运行任务的服务。 ## 支持的集成模型 CodePipeline 有两种集成模型： + **Lambda 集成模型：**此集成模型是使用中的操作类型的首选方式。 CodePipeline当您的操作运行时，Lambda 集成模型使用 Lambda 函数来处理任务请求。 + **任务工作者集成模型：**任务工作者集成模型是以前用于第三方集成的模型。作业工作人员集成模型使用配置为在操作运行时联系的作业工作者 CodePipeline APIs 来处理作业请求。 为了进行比较，下表描述了这两种模型的特征： **** | | **Lambda 集成模型** | **任务工作者集成模型** | | --- | --- | --- | | 描述 | 集成器将集成写为 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`，则为必填项。 + 如果 `result` 为 `Success` 或 `Continue`，则必须为空 + 有效值： + ConfigurationError + JobFailed + PermissionsError + RevisionOutOfSync + RevisionUnavailable + SystemUnavailable + `continuation`：在当前操作执行中，要传递给下一个任务的延续状态。 + 可选。如果结果是 `Continue`，则为必填项。 + 如果 `result` 为 `Success` 或 `Fail`，则必须为空。 + 属性： + `State`：要传递的状态的哈希值。 + `status`：操作执行的状态。 + 可选。 + 属性： + `ExternalExecutionId`：与任务关联的可选外部执行 ID 或提交 ID。 + `Summary`：所发生情况的可选摘要。在失败情况下，这会成为用户看到的失败消息。 + `outputVariables`：一组要传递给下一个动作执行的 key/value 对。 + 可选。 + 如果 `result` 为 `Continue` 或 `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 并表明需要继续工作的方式。例如，集成商在其资源上为客户启动构建后，它不会等待构建完成，而是通过返回 as `continue` 并将版本的唯一 ID 返回 CodePipeline 到 a `result` s token 来 CodePipeline 表示它没有最终结果。`continuation` **注意** Lambda 函数只能运行不超过 15 分钟。如果任务需要运行更长的时间，可以使用延续令牌。 CodePipeline 队伍在 30 秒后调用积分器，其有效载荷中包含相同的`continuation`令牌，这样它就可以检查积分器是否完成。如果构建完成，则集成器返回终端 success/fail 结果，否则继续。 ### 提供 CodePipeline 在运行时调用集成商 Lambda 函数的权限 您可以向集成商 Lambda 函数添加权限，为服务提供 CodePipeline 使用服务委托人调用 CodePipeline 该函数的权限:。`codepipeline.amazonaws.com`您可以使用 CloudFormation 或命令行添加权限。有关示例，请参阅[使用操作类型](action-types.md)。 ## 任务工作者集成模型 设计完高层工作流后，您可以创建任务工作者。尽管第三方操作的细节决定了任务工作者需要什么，但大多数第三方操作的任务工作者都包括以下功能： + CodePipeline 正在使用轮询作业`PollForThirdPartyJobs`。 + 确认任务并将结果返回到 CodePipeline 使用`AcknowledgeThirdPartyJob``PutThirdPartyJobSuccessResult`、和`PutThirdPartyJobFailureResult`。 + 通过将项目 and/or 放入管道的 Amazon S3 存储桶中检索项目。要从 Amazon S3 桶下载构件，您必须创建一个使用签名版本 4 (Sig V4) 签名的 Amazon S3 客户端。需要 Sig V4 才能使用。 AWS KMS 要将项目上传到 Amazon S3 存储桶，您还必须通过 AWS Key Management Service (AWS KMS) 将 Amazon S3 `[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/SOAPPutObject.html)` 请求配置为使用加密。 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。如果密钥属性为空，则使用 AWS 托管式密钥。 CodePipeline AWS 托管式密钥 除非另行配置，否则使用。 有关演示如何使用 Java 或.NET 创建 AWS KMS 参数的示例，请参阅[AWS Key Management Service 在 Amazon S3 中使用指定 AWS SDKs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/kms-using-sdks.html)。有关的 Amazon S3 存储桶的更多信息 CodePipeline，请参阅[CodePipeline 概念 ](concepts.md)。 ### 为作业辅助角色选择和配置权限管理策略 要为你的第三方操作培养工作人员 CodePipeline，你需要一个整合用户和权限管理的策略。 最简单的策略是通过创建带有 AWS Identity and Access Management (IAM) 实例角色的 Amazon EC2 实例来添加作业人员所需的基础设施，这样您就可以轻松扩展集成所需的资源。您可以使用内置的集成 AWS 来简化作业人员与之间的互动 CodePipeline。 了解更多有关 Amazon EC2 的信息，并确定其是否为适合您的集成的正确选择。有关信息，请参阅 [Amazon EC2 – 虚拟服务器托管](https://aws.amazon.com/ec2)。有关设置 Amazon EC2 实例的更多信息，请参阅 [Amazon EC2 Linux 实例入门](https://docs.aws.amazon.com/AWSEC2/latest/GettingStartedGuide/)。 另一个需要考虑的策略是使用 IAM 的身份联合验证来集成您的现有身份提供程序系统和资源。如果您已经拥有企业身份提供程序，或已经配置为支持使用网络身份提供程序的用户，则此策略很有用。联合身份允许您授予对 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/" ] } ] } ``` ------