本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 在中创建和添加自定义操作 CodePipeline
<a name="actions-create-custom-action"></a>

Amazon CodePipeline 包括许多操作，可帮助您为自动发布流程配置构建、测试和部署资源。如果您的发布过程包括默认操作中不包含的活动，例如内部开发的构建过程或测试套件，则可以为此目的创建自定义操作，并将其包含在管道中。您可以使用在 Amazon CLI 与您的 Amazon 账户关联的管道中创建自定义操作。

您可以为以下操作类别创建自定义 Amazon CodePipeline 操作：
+ 用于构建或转换项目的自定义构建操作
+ 用于将项目部署到一个或多个服务器、网站或存储库的自定义部署操作
+ 用于配置和运行自动化测试的自定义测试操作
+ 用于运行函数的自定义调用操作

创建自定义操作时，您还必须创建一个作业辅助角色，该工作人员将轮询 CodePipeline 此自定义操作的任务请求，执行该作业，并将状态结果返回到 CodePipeline。该作业辅助角色可以位于任何计算机或资源上，只要它能够 CodePipeline 的公有终端节点即可。要轻松管理访问权限和安全性，请考虑在 Amazon EC2 实例上托管您的作业辅助角色。

下图展示了包含自定义构建操作的管道的概要视图：

![\[包含自定义构建操作的管道的概要视图。\]](http://docs.amazonaws.cn/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)

## 创建自定义操作
<a name="actions-create-custom-action-cli"></a>

**要使用创建自定义动作 Amazon 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`。只要配置属性是必需的且不为私有，您就可以遵照以下格式在 URL 模板内引用自定义操作的配置属性中的名称：`{Config:name}`。例如，在上面的示例中，该`entityUrlTemplate`值指的是配置属性*ProjectName*。
   + `entityUrlTemplate`：用于提供操作服务提供方相关信息的静态链接。在示例中，构建系统包含一个指向每个构建项目的静态链接。链接格式可能不同，具体取决于您的构建提供程序（或者如果您创建的是其他操作类型，比如测试，则取决于其他服务提供方）。您必须提供此链接格式，以便在添加自定义操作时，用户可以选择此链接来打开浏览器，从而打开您的网站上提供生成项目 (或测试环境) 具体细节的页面。
   + `executionUrlTemplate`：将会使用有关当前或最新运行的操作进行更新的动态链接。当您的自定义作业辅助角色更新作业的状态（例如成功、失败或正在进行）时，它还将提供一个 `externalExecutionId` 用于完成此链接。此链接可用于提供有关操作运行的详细信息。

   例如，当您查看管道中的操作时，您将看到以下两个链接：  
![\[CodePipeline 控制台中的链接可提供有关管道运行的更多信息。\]](http://docs.amazonaws.cn/codepipeline/latest/userguide/images/codepipeline-calinksexplained.png)

   ![\[1\]](http://docs.amazonaws.cn/codepipeline/latest/userguide/images/number-1.png) 此静态链接在您添加自定义操作时显示，指向 `entityUrlTemplate` 中您在创建自定义操作时指定的地址。

   ![\[2\]](http://docs.amazonaws.cn/codepipeline/latest/userguide/images/number-2.png) 此动态链接在每次操作运行后更新，指向 `executionUrlTemplate` 中您在创建自定义操作时指定的地址。

   有关这些链接类型以及`RevisionURLTemplate`和的更多信息`ThirdPartyURL`，请参阅 [CodePipeline API 参考[CreateCustomActionType](https://docs.amazonaws.cn/codepipeline/latest/APIReference/API_CreateCustomActionType.html)](https://docs.amazonaws.cn/codepipeline/latest/APIReference/)中的[ActionTypeSettings](https://docs.amazonaws.cn/codepipeline/latest/APIReference/API_ActionTypeSettings.html)和。有关操作结构要求以及如何创建操作的更多信息，请参阅 [CodePipeline 管道结构参考](reference-pipeline-structure.md)。

1. 保存 JSON 文件并为其指定一个易于记住的名称（例如，*MyCustomAction*.json）。

1. 在您安装了 Amazon CLI的计算机上打开终端会话 (Linux、OS X、Unix) 或命令提示符 (Windows)。

1. 使用运行**aws codepipeline create-custom-action-type**命令，指定您刚刚创建的 JSON 文件的名称。 Amazon CLI 

   例如，要创建一个构建自定义操作：
**重要**  
务必在文件名前包含 `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** 命令时，无法分配或更改此值。

## 为自定义操作创建作业辅助角色
<a name="actions-create-custom-action-job-worker"></a>

自定义操作需要作业工作人员轮 CodePipeline 询自定义操作的作业请求，执行任务并将状态结果返回到 CodePipeline。作业辅助角色可以位于任何计算机或资源上，只要它能够访问 CodePipeline 的公有终端节点即可。

有许多方法可以设计您的作业辅助角色。以下各节针对为 CodePipeline 开发自定义作业辅助角色提供了一些实用的指导。

**Topics**
+ [为作业辅助角色选择和配置权限管理策略](#actions-create-custom-action-permissions)
+ [为自定义操作开发作业辅助角色](#actions-create-custom-action-job-worker-workflow)
+ [自定义作业辅助角色架构和示例](#actions-create-custom-action-job-worker-common)

### 为作业辅助角色选择和配置权限管理策略
<a name="actions-create-custom-action-permissions"></a>

要在中为你的自定义操作开发自定义工作人员 CodePipeline，你需要一个集成用户和权限管理的策略。

最简单的策略是通过创建具有 IAM 实例角色的 Amazon EC2 实例，为您的自定义作业辅助角色添加所需的基础设施，从而允许您轻松纵向扩展集成所需的资源。您可以使用内置的集成 Amazon 来简化自定义作业工作人员和之间的交互 CodePipeline。

**设置 Amazon EC2 实例**

1. 了解更多有关 Amazon EC2 的信息，并确定其是否为适合您的集成的正确选择。有关信息，请参阅 [Amazon EC2 – 虚拟服务器托管](https://www.amazonaws.cn/ec2)。

1. 开始创建您的 Amazon EC2 实例。有关信息，请参阅[开始使用 Amazon EC2 Linux 实例](https://docs.amazonaws.cn/AWSEC2/latest/GettingStartedGuide/)。

另一个需要考虑的策略是使用 IAM 的身份联合验证来集成您的现有身份提供程序系统和资源。如果您已经拥有企业身份提供程序，或已经配置为支持使用网络身份提供程序的用户，则此策略特别有用。联合身份允许您授予对 Amazon 资源（包括）的安全访问权限 CodePipeline，而无需创建或管理 IAM 用户。您可以利用针对密码安全性要求和凭证轮换的功能和策略。您可以使用示例应用程序作为自己设计的模板。

**若要设置身份联合验证**

1. 了解有关 IAM 身份联合验证的更多信息。有关信息，请参阅[管理联合身份验证](https://www.amazonaws.cn/iam/details/manage-federation/)。

1.  查看[授予临时访问权限的情形](https://docs.amazonaws.cn/STS/latest/UsingSTS/STSUseCases.html)中的示例，以确定最适合您的自定义操作需求的临时访问情形。

1. 查看与您的基础设施相关的联合身份验证代码示例，例如：
   + [Active Directory 的联合身份验证示例应用程序使用案例](https://www.amazonaws.cn/code/1288653099190193)

1. 开始配置联合身份验证。有关信息，请参阅 *IAM 用户指南* 中的[身份提供程序和联合身份验证](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_providers.html)。

创建以下内容之一，以便在运行自定义操作和作业辅助工具时在您的 Amazon Web Services 账户 下使用。



如果用户想在 Amazon 外部进行交互，则需要编程访问权限 Amazon Web Services 管理控制台。 Amazon APIs 和 Amazon Command Line Interface 需要访问密钥。可能的话，创建临时凭证，该凭证由一个访问密钥 ID、一个秘密访问密钥和一个指示凭证何时到期的安全令牌组成。

要向用户授予编程式访问权限，请选择以下选项之一。


****  

| 哪个用户需要编程式访问权限？ | 目的 | 方式 | 
| --- | --- | --- | 
| IAM | 使用短期证书签署对 Amazon CLI 或的编程请求 Amazon APIs（直接或使用 Amazon SDKs）。 | 按照 IAM 用户指南中的将[临时证书与 Amazon 资源配合使用](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_credentials_temp_use-resources.html)中的说明进行操作。 | 
| IAM | （不推荐使用）使用长期证书签署对 Amazon CLI 或的编程请求 Amazon APIs（直接或使用 Amazon SDKs）。 | 按照《IAM 用户指南》中[管理 IAM 用户的访问密钥](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_credentials_access-keys.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` 托管式策略。

### 为自定义操作开发作业辅助角色
<a name="actions-create-custom-action-job-worker-workflow"></a>

在你选择了权限管理策略后，你应该考虑你的求职者将如何与之互动 CodePipeline。以下概要图表显示了构建过程的自定义操作和作业辅助角色的工作流。

![\[构建过程的自定义操作和作业辅助角色的工作流。\]](http://docs.amazonaws.cn/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. 当操作正在运行时，作业辅助角色可以使用延续令牌（由作业辅助角色生成的作业状态的序列化，例如 JSON 格式的构建标识符或一个 Amazon S3 对象键），以及将用于填充 `executionUrlTemplate` 中的链接的 `ExternalExecutionId` 信息来调用 `PutJobSuccessResult`。这将使用一个有效链接来更新管道的控制台视图，该链接提供正在进行中的操作的具体细节。虽然不是必需的，但它是最佳实践，因为它使用户能够在自定义操作运行时查看其状态。

   调用 `PutJobSuccessResult` 后，作业即视为完成。在中创建了一个 CodePipeline 包含延续令牌的新作业。如果您的作业辅助角色再次调用 `PollForJobs`，则会显示此作业。此新任务可用于检查操作的状态，然后返回延续令牌，或者在操作完成后不返回延续令牌。
**注意**  
如果您的作业辅助角色执行自定义操作的所有工作，则应考虑将作业辅助角色处理过程分为至少两个步骤。第一步是为您的操作建立详细信息页面。创建详细信息页面后，您可以将作业辅助角色的状态序列化，并将其作为延续令牌返回，同时遵守大小限制（请参阅 [Amazon CodePipeline 中的限额](limits.md)）。例如，您可以将操作的状态写入用作延续令牌的字符串中。作业辅助角色处理过程的第二步（以及后续步骤）将执行操作的实际工作。最后一步将成功或失败返回到 CodePipeline，最后一步没有延续标记。

   有关使用延续令牌的更多信息，请参阅 [CodePipeline API 参考`PutJobSuccessResult`](https://docs.amazonaws.cn/codepipeline/latest/APIReference)中的规范。

1. 自定义操作完成后，作业工作人员 CodePipeline 通过调用 APIs以下两种方法之一将自定义操作的结果返回到：
   + `PutJobSuccessResult`，不带延续令牌，表示自定义操作已成功运行
   + `PutJobFailureResult`，表示自定义操作未成功运行

   根据结果，管道将继续执行下一个操作（成功），或者停止（失败）。

### 自定义作业辅助角色架构和示例
<a name="actions-create-custom-action-job-worker-common"></a>

在制定概要工作流后，您可以创建作业辅助角色。尽管自定义操作的细节最终将决定作业辅助角色需要什么，但自定义操作的大多数作业辅助角色都包括以下功能：
+  CodePipeline 正在使用轮询作业`PollForJobs`。
+ 确认任务并将结果返回到 CodePipeline 使用`AcknowledgeJob``PutJobSuccessResult`、和`PutJobFailureResult`。
+ 通过将项目 and/or 放入管道的 Amazon S3 存储桶中检索项目。要从 Amazon S3 桶下载构件，您必须创建一个使用签名版本 4 (Sig V4) 签名的 Amazon S3 客户端。需要 Sig V4 才能使用。 Amazon KMS

  要将构件上传到 Amazon S3 桶，您还必须另外配置 Amazon S3 `[PutObject](https://docs.amazonaws.cn/AmazonS3/latest/API/SOAPPutObject.html)` 请求以使用加密。当前，仅支持 Amazon 密钥管理服务 (Amazon KMS) 进行加密。 Amazon KMS 使用 Amazon KMS keys。为了知道是使用客户管理的 Amazon 托管式密钥 密钥还是客户管理的密钥来上传工件，您的自定义作业工作人员必须查看[作业数据](https://docs.amazonaws.cn/codepipeline/latest/APIReference/API_JobData.html)并检查[加密密钥](https://docs.amazonaws.cn/codepipeline/latest/APIReference/API_EncryptionKey.html)属性。如果设置了该属性，则在配置时应使用该客户托管密钥 ID Amazon KMS。如果键属性为空，则使用 Amazon 托管式密钥。 CodePipeline Amazon 托管式密钥 除非另行配置，否则使用。

  有关演示如何使用 Java 或.NET 创建 Amazon KMS 参数的示例，请参阅[Amazon Key Management Service 在 Amazon S3 中使用指定 Amazon SDKs](https://docs.amazonaws.cn/AmazonS3/latest/userguide/kms-using-sdks.html)。有关的 Amazon S3 存储桶的更多信息 CodePipeline，请参阅[CodePipeline 概念 ](concepts.md)。

有关自定义作业工作人员的更复杂示例，请参见 GitHub。此示例是一个开源示例，按原样提供。
+ [Job Worker](https://github.com/awslabs/aws-codepipeline-custom-job-worker) 示例 CodePipeline：从 GitHub 存储库下载示例。

## 向管道添加自定义操作
<a name="actions-create-custom-action-add"></a>

有了作业辅助角色后，您可以通过以下方式将您的自定义操作添加到管道中：创建一个新的管道并在使用 “创建管道” 向导时选择该管道；编辑现有管道并添加自定义操作；或者使用 SDKs、或 APIs。 Amazon CLI

**注意**  
您可以在“Create Pipeline (创建管道)”向导中创建一个包含自定义操作（如果自定义操作是生成或部署操作）的管道。如果您的自定义操作位于测试类别中，则您必须通过编辑现有管道来添加它。

**Topics**
+ [向现有管道添加自定义操作 (CLI)](#actions-create-custom-action-add-cli)

### 向现有管道添加自定义操作 (CLI)
<a name="actions-create-custom-action-add-cli"></a>

您可以使用 Amazon 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 控制台，然后选择刚才编辑的管道的名称。

   管道将显示您的更改。当您下一次更改源位置时，管道会通过管道修订后的结构运行该修订。