本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用動作類型
<a name="action-types"></a>

動作類型是您作為供應商，使用其中一個支援的整合模型為客戶建立的預先設定動作 AWS CodePipeline。

您可以請求、檢視和更新動作類型。如果為做為擁有者的帳戶建立動作類型，您可以使用 AWS CLI 檢視或更新動作類型屬性和結構。如果您是動作類型的提供者或擁有者，您的客戶可以選擇動作，並在 CodePipeline 中提供動作後將其新增至管道。

**注意**  
您可以在 `custom` `owner` 欄位中使用 建立動作，以搭配任務工作者執行。您不會使用 整合模型建立它們。如需自訂動作的相關資訊，請參閱 [在 CodePipeline 中建立和新增自訂動作](actions-create-custom-action.md)。

**動作類型元件**

下列元件組成 動作類型。
+ **動作類型 ID** – *ID* 包含 類別、擁有者、提供者和版本。下列範例顯示 動作類型 ID，其擁有者為 `ThirdParty`、 類別為 `Test`、供應商名為 `TestProvider`，以及 版本為 `1`。

  ```
              {
                  "Category": "Test",
                  "Owner": "ThirdParty",
                  "Provider": "TestProvider",
                  "Version": "1"
              },
  ```
+ **執行器組態** – 建立動作時指定的整合模型或動作引擎。當您為動作類型指定執行器時，您可以選擇兩種類型之一：
  + *Lambda：*動作類型擁有者會將整合寫入 Lambda 函數，每當有動作可用的任務時，CodePipeline 就會叫用該函數。
  + *JobWorker：*動作類型擁有者會將整合寫入為任務工作者，以輪詢客戶管道上可用的任務。然後，任務工作者會執行任務，並使用 CodePipeline APIs 將任務結果提交回 CodePipeline。
**注意**  
任務工作者整合模型不是偏好的整合模型。
+ **輸入和輸出成品：**動作類型擁有者為動作的客戶指定的成品限制。
+ **許可：**指定可存取第三方動作類型之客戶的許可策略。可用的許可策略取決於動作類型的所選整合模型。
+ **URLs：與客戶互動之資源的**深層連結，例如動作類型擁有者的組態頁面。

**Topics**
+ [請求動作類型](#action-types-request)
+ [將可用的動作類型新增至管道 （主控台）](#action-types-in-pipelines)
+ [檢視動作類型](#action-types-view-cli)
+ [更新動作類型](#action-types-update-cli)

## 請求動作類型
<a name="action-types-request"></a>

當第三方供應商請求新的 CodePipeline 動作類型時，會為 CodePipeline 中的動作類型擁有者建立動作類型，擁有者可以管理和檢視動作類型。

動作類型可以是私有或公有動作。建立動作類型時，它是私有的。若要請求將動作類型變更為公有動作，請聯絡 CodePipeline 服務團隊。

在為 CodePipeline 團隊建立動作定義檔案、執行器資源和動作類型請求之前，您必須選擇整合模型。



### 步驟 1：選擇您的整合模型
<a name="action-types-choose-model"></a>

選擇您的整合模型，然後建立該模型的組態。選擇整合模型後，您必須設定整合資源。
+ 對於 Lambda 整合模型，您可以建立 Lambda 函數並新增許可。將許可新增至您的整合器 Lambda 函數，以提供 CodePipeline 服務使用 CodePipeline 服務主體叫用它的許可：`codepipeline.amazonaws.com`。您可以使用 CloudFormation 或命令列新增許可。
  + 使用 新增許可的範例 CloudFormation：

    ```
      CodePipelineLambdaBasedActionPermission:
        Type: 'AWS::Lambda::Permission'
        Properties:
          Action: 'lambda:invokeFunction'
          FunctionName: {"Fn::Sub": "arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:function-name"}
          Principal: codepipeline.amazonaws.com
    ```
  + [命令列的文件](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html)
+ 對於任務工作者整合模型，您可以建立與允許帳戶清單的整合，其中任務工作者會使用 CodePipeline APIs 輪詢任務。

### 步驟 2：建立動作類型定義檔案
<a name="action-type-definition-file"></a>

您可以使用 JSON 在動作類型定義檔案中定義動作類型。在 檔案中，您會包含動作類別、用於管理動作類型的整合模型，以及組態屬性。

**注意**  
建立公有動作之後，您無法將 下的動作類型屬性`properties`從 變更為 `optional` `required`。您也無法變更 `owner`。

如需動作類型定義檔案參數的詳細資訊，請參閱 [CodePipeline API 參考](https://docs.aws.amazon.com/cli/latest/reference/codepipeline)中的 [ActionTypeDeclaration](https://docs.aws.amazon.com/cli/latest/reference/codepipelineAPI_ActionTypeDeclaration.html) 和 [UpdateActionType](https://docs.aws.amazon.com/cli/latest/reference/codepipelineAPI_UpdateActionType.html)。

動作類型定義檔案中有八個區段：
+ `description`：要更新之動作類型的描述。
+ `executor`：使用支援的整合模型建立之動作類型的執行器相關資訊，可以是 `Lambda`或 `job worker`。您只能`lambdaExecutorConfiguration`根據您的執行器類型提供 `jobWorkerExecutorConfiguration`或 。
  + `configuration`：動作類型的組態資源，以選擇的整合模型為基礎。對於 Lambda 整合模型，請使用 Lambda 函數 ARN。對於任務工作者整合模型，請使用 帳戶或任務工作者執行所在的帳戶清單。
  + `jobTimeout`：任務的逾時，以秒為單位。動作執行可以包含多個任務。這是單一任務的逾時，而不是整個動作執行的逾時。
**注意**  
對於 Lambda 整合模型，逾時上限為 15 分鐘。
  + `policyStatementsTemplate`：政策陳述式，指定 CodePipeline 客戶帳戶中成功執行動作執行所需的許可。
  + `type`：用於建立和更新動作類型的整合模型，`Lambda`或 `JobWorker`。
+ `id`：動作類型的類別、擁有者、提供者和版本 ID：
  + `category`：可以在 階段採取的動作類型：來源、建置、部署、測試、調用或核准。
  + `provider`：所呼叫動作類型的提供者，例如提供者公司或產品名稱。建立動作類型時，會提供提供者名稱。
  + `owner`：正在呼叫的動作類型的建立者： `AWS`或 `ThirdParty`。
  + `version`：用來版本動作類型的字串。對於第一個版本，將版本號碼設定為 1。
+ `inputArtifactDetails`：管道中上一個階段預期的成品數量。
+ `outputArtifactDetails`：從動作類型階段的結果預期成品數量。
+ `permissions`：識別具有使用 動作類型許可之帳戶的詳細資訊。
+ `properties`：完成專案任務所需的參數。
  + `description`：向使用者顯示的 屬性描述。
  + `optional`：組態屬性是否為選用。
  + `noEcho`：是否省略客戶輸入的欄位值。如果為 `true`，則值會在使用 GetPipeline API 請求傳回時修訂。
  + `key`：組態屬性是否為金鑰。
  + `queryable`： 屬性是否與輪詢搭配使用。動作類型最多可有一個可查詢的屬性。如果有，則該屬性必須是必要的，而且不是私密。
  + `name`：向使用者顯示的屬性名稱。
+ `urls`：CodePipeline 向使用者顯示的 URLs 清單。
  + `entityUrlTemplate`： 動作類型的外部資源 URL，例如組態頁面。
  + `executionUrlTemplate`：最新執行動作的詳細資訊 URL。
  + `revisionUrlTemplate`：顯示在 CodePipeline 主控台的 URL 至頁面，客戶可以在其中更新或變更外部動作的組態。
  + `thirdPartyConfigurationUrl`：頁面的 URL，使用者可以註冊外部服務，並對該服務提供的動作執行初始組態。

下列程式碼顯示範例動作類型定義檔案。

```
{
   "actionType": { 
      "description": "string",
      "executor": { 
         "configuration": { 
            "jobWorkerExecutorConfiguration": { 
               "pollingAccounts": [ "string" ],
               "pollingServicePrincipals": [ "string" ]
            },
            "lambdaExecutorConfiguration": { 
               "lambdaFunctionArn": "string"
            }
         },
         "jobTimeout": number,
         "policyStatementsTemplate": "string",
         "type": "string"
      },
      "id": { 
         "category": "string",
         "owner": "string",
         "provider": "string",
         "version": "string"
      },
      "inputArtifactDetails": { 
         "maximumCount": number,
         "minimumCount": number
      },
      "outputArtifactDetails": { 
         "maximumCount": number,
         "minimumCount": number
      },
      "permissions": { 
         "allowedAccounts": [ "string" ]
      },
      "properties": [ 
         { 
            "description": "string",
            "key": boolean,
            "name": "string",
            "noEcho": boolean,
            "optional": boolean,
            "queryable": boolean
         }
      ],
      "urls": { 
         "configurationUrl": "string",
         "entityUrlTemplate": "string",
         "executionUrlTemplate": "string",
         "revisionUrlTemplate": "string"
      }
   }
}
```



### 步驟 3：向 CodePipeline 註冊您的整合
<a name="action-types-register"></a>

若要向 CodePipeline 註冊動作類型，請搭配您的請求聯絡 CodePipeline 服務團隊。

CodePipeline 服務團隊會透過在服務程式碼庫中進行變更來註冊新的動作類型整合。CodePipeline 會註冊兩個新動作：*公有動作*和*私有動作*。您可以使用私有動作進行測試，然後在準備就緒時啟用公有動作來服務客戶流量。

**註冊 Lambda 整合的請求**
+ 使用下列表單將請求傳送至 CodePipeline 服務團隊。

  ```
  This issue will track the onboarding of [Name] in CodePipeline.
  
  
  [Contact engineer] will be the primary point of contact for this integration.
  
  Name of the action type as you want it to appear to customers: Example.com Testing
  
  Initial onboard checklist:
  
  1. Attach an action type definition file in JSON format. This includes the schema for the action type
  
  2. A list of test accounts for the allowlist which can access the new action type [{account, account_name}]
  
  3. The Lambda function ARN
  
  4. List of AWS 區域 where your action will be available
  
  5. Will this be available as a public action?
  ```

**註冊任務工作者整合的請求**
+ 使用下列表單將請求傳送至 CodePipeline 服務團隊。

  ```
  This issue will track the onboarding of [Name] in CodePipeline.
  
  [Contact engineer] will be the primary point of contact for this integration.
  
  
  Name of the action type as you want it to appear to customers: Example.com Testing
  
  Initial onboard checklist:
  
  1. Attach an action type definition file in JSON format. This includes the schema for the action type.
  
  2. A list of test accounts for the allowlist which can access the new action type [{account, account_name}]
  
  3. URL information:
  Website URL: https://www.example.com/%TestThirdPartyName%/%TestVersionNumber%
  
  Example URL pattern where customers will be able to review their configuration information for the action: https://www.example.com/%TestThirdPartyName%/%customer-ID%/%CustomerActionConfiguration%
  
  Example runtime URL pattern: https://www.example.com/%TestThirdPartyName%/%customer-ID%/%TestRunId%
  
  4. List of AWS 區域 where your action will be available
  
  5. Will this be available as a public action?
  ```

### 步驟 4：啟用您的新整合
<a name="action-types-activate"></a>

當您準備好公開使用新的整合時，請聯絡 CodePipeline 服務團隊。

## 將可用的動作類型新增至管道 （主控台）
<a name="action-types-in-pipelines"></a>

您可以將動作類型新增至管道，以便進行測試。您可以透過建立新的管道或編輯現有的管道來執行此操作。

**注意**  
如果您的動作類型是來源、建置或部署類別動作，您可以透過建立管道來新增它。如果您的動作類型位於測試類別中，您必須編輯現有的管道來新增它。

**從 CodePipeline 主控台將動作類型新增至現有管道**

1. 登入 AWS 管理主控台 並開啟 CodePipeline 主控台，網址為 https：//[http://console.aws.amazon.com/codesuite/codepipeline/home](https://console.aws.amazon.com/codesuite/codepipeline/home)。

1. 在管道清單中，選擇您要新增動作類型的管道。

1. 在管道的摘要檢視頁面上，選擇**編輯**。

1. 選擇 以編輯階段。在您要新增動作類型的階段中，選擇**新增動作群組**。隨即顯示**編輯動作**頁面。

1. 在**編輯動作**頁面上的動作**名稱**中，輸入動作的名稱。這是針對管道中的階段顯示的名稱。

1. 在**動作提供者**中，從清單中選擇動作類型。

   請注意，清單中的值是以動作類型定義檔案中`provider`指定的 為基礎。

1. 在**輸入成品**中，以下列格式輸入成品名稱：

   `Artifactname::FileName`

   請注意，允許的最小和最大數量是根據動作類型定義檔案中`inputArtifactDetails`指定的 來定義。

1. 選擇**連線至 <Action\$1Name>**。

   瀏覽器視窗會開啟並連線至您為動作類型建立的網站。

1. 以客戶身分登入您的網站，並完成客戶使用您的動作類型所採取的步驟。您的步驟會根據您的動作類別、網站和組態而有所不同，但通常包含將客戶傳回編輯動作頁面的**完成動作**。

1. 在 CodePipeline **編輯動作**頁面中，會顯示動作的其他組態欄位。顯示的欄位是您在動作定義檔案中指定的組態屬性。在為您的動作類型自訂的欄位中輸入資訊。

   例如，如果動作定義檔案指定名為 的屬性`Host`，則具有標籤**主機**的欄位會顯示在動作的**編輯動作**頁面上。

1. 在**輸出成品**中，以下列格式輸入成品名稱：

   `Artifactname::FileName`

   請注意，允許的最小和最大數量是根據動作類型定義檔案中`outputArtifactDetails`指定的 來定義。

1. 選擇**完成**以返回管道詳細資訊頁面。
**注意**  
您的客戶可以選擇使用 CLI 將動作類型新增至其管道。

1. 若要測試您的動作，請將變更遞交至管道來源階段中指定的來源，或遵循[手動啟動管道](https://docs.aws.amazon.com/codepipeline/latest/userguide/how-to-manually-start.html)中的步驟。

若要使用動作類型建立管道，請遵循中的步驟[建立管道、階段和動作](pipelines-create.md)，並從您要測試的任意階段中選擇動作類型。

## 檢視動作類型
<a name="action-types-view-cli"></a>

您可以使用 CLI 來檢視您的動作類型。使用 **get-action-type**命令來檢視使用 整合模型建立的動作類型。

**檢視動作類型**

1. 建立輸入 JSON 檔案並命名檔案 `file.json`。以 JSON 格式新增動作類型 ID，如下列範例所示。

   ```
   {
       "category": "Test",
       "owner": "ThirdParty",
       "provider": "TestProvider",
       "version": "1"
   }
   ```

1. 在終端機視窗或命令列中，執行 **get-action-type**命令。

   ```
   aws codepipeline get-action-type --cli-input-json file://file.json
   ```

   此命令會傳回 動作類型的動作定義輸出。此範例顯示使用 Lambda 整合模型建立的動作類型。

   ```
   {
       "actionType": {
           "executor": {
               "configuration": {
                   "lambdaExecutorConfiguration": {
                       "lambdaFunctionArn": "arn:aws:lambda:us-west-2:<account-id>:function:my-function"
                   }
               },
               "type": "Lambda"
           },
           "id": {
               "category": "Test",
               "owner": "ThirdParty",
               "provider": "TestProvider",
               "version": "1"
           },
           "inputArtifactDetails": {
               "minimumCount": 0,
               "maximumCount": 1
           },
           "outputArtifactDetails": {
               "minimumCount": 0,
               "maximumCount": 1
           },
           "permissions": {
               "allowedAccounts": [
                   "<account-id>"
               ]
           },
           "properties": []
       }
   }
   ```

## 更新動作類型
<a name="action-types-update-cli"></a>

您可以使用 CLI 編輯使用整合模型建立的動作類型。

對於公有動作類型，您無法更新擁有者、無法將選用屬性變更為必要，而且只能新增新的選用屬性。

1. 使用 `get-action-type`命令來取得動作類型的結構。複製 結構。

1. 建立輸入 JSON 檔案並將其命名為 `action.json`。將您在上一個步驟中複製的動作類型結構貼入其中。更新您要變更的任何參數。您也可以新增選用參數。

   如需輸入檔案參數的詳細資訊，請參閱 中的動作定義檔案描述[步驟 2：建立動作類型定義檔案](#action-type-definition-file)。

   下列範例顯示如何更新使用 Lambda 整合模型建立的範例動作類型。此範例會進行下列變更：
   + 將`provider`名稱變更為 `TestProvider1`。
   + 新增任務逾時限制 900 秒。
   + 新增名為 的動作組態屬性`Host`，使用 動作顯示給客戶。

     ```
     {
         "actionType": {
             "executor": {
                 "configuration": {
                     "lambdaExecutorConfiguration": {
                         "lambdaFunctionArn": "arn:aws:lambda:us-west-2:<account-id>:function:my-function"
                     }
                 },
                 "type": "Lambda",
                 "jobTimeout": 900 
             },
             "id": {
                 "category": "Test",
                 "owner": "ThirdParty",
                 "provider": "TestProvider1",
                 "version": "1"
             },
             "inputArtifactDetails": {
                 "minimumCount": 0,
                 "maximumCount": 1
             },
             "outputArtifactDetails": {
                 "minimumCount": 0,
                 "maximumCount": 1
             },
             "permissions": {
                 "allowedAccounts": [
                     "account-id"
                 ]
             },
             "properties": {
              "description": "Owned build action parameter description",
              "optional": true,
              "noEcho": false,
              "key": true,
              "queryable": false,
              "name": "Host"
              }
         }
     }
     ```

1. 在終端機或命令列，執行 **update-action-type**命令

   ```
   aws codepipeline update-action-type --cli-input-json file://action.json
   ```

   此命令會傳回動作類型輸出，以符合更新後的參數。