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

# 了解 Step Functions 中的活動
<a name="concepts-activities"></a>

透過 Step Functions 活動，您可以在狀態機器中設定任務，其中實際工作是由在 Step Functions 外部執行的*工作者*執行。例如，您可以在 Amazon Elastic Compute Cloud (Amazon EC2)、Amazon Elastic Container Service (Amazon ECS) 或甚至行動裝置上執行工作者程式。

## 概觀
<a name="activities-overview"></a>

在 中AWS Step Functions，活動是一種將執行某處 （稱為*活動工作者*) 的程式碼與狀態機器中的特定任務建立關聯的方法。您可以使用 Step Functions 主控台或呼叫 來建立活動`[CreateActivity](https://docs.aws.amazon.com/step-functions/latest/apireference/API_CreateActivity.html)`。這為您的任務狀態提供 Amazon Resource Name (ARN)。使用此 ARN 來輪詢任務狀態，以便在您的活動工作者中使用。

**注意**  
活動並未進行版本控制，應該可與舊版相容。如果您必須對活動進行回溯不相容的變更，請使用唯一名稱在 Step Functions 中*建立新的*活動。

活動工作者可以是在 Amazon EC2 執行個體、 AWS Lambda函數、行動裝置上執行的應用程式：任何可以進行 HTTP 連線的應用程式，在任何地方託管。當 Step Functions 達到活動任務狀態時，工作流程會等待活動工作者輪詢任務。活動工作者會使用 輪詢 Step Functions`[GetActivityTask](https://docs.aws.amazon.com/step-functions/latest/apireference/API_GetActivityTask.html)`，並傳送相關活動的 ARN。 `GetActivityTask`會傳回包含 `input`（任務的 JSON 輸入字串） 和 [https://docs.aws.amazon.com/step-functions/latest/apireference/API_GetActivityTask.html#StepFunctions-GetActivityTask-response-taskToken](https://docs.aws.amazon.com/step-functions/latest/apireference/API_GetActivityTask.html#StepFunctions-GetActivityTask-response-taskToken)（任務的唯一識別符） 的回應。在活動工作者完成其工作之後，就可以使用 `[SendTaskSuccess](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html)` 或 `[SendTaskFailure](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html)` 來提供成功或失敗的報告。這兩個呼叫會使用 `GetActivityTask` 所提供的 `taskToken`，將結果與該任務建立關聯。

### 活動任務的相關 API
<a name="activities-api"></a>

Step Functions 提供 APIs用於建立和列出活動、請求任務，以及根據您的工作者結果管理狀態機器的流程。

以下是與活動相關的 Step Functions APIs：
+ `[CreateActivity](https://docs.aws.amazon.com/step-functions/latest/apireference/API_CreateActivity.html)`
+ `[GetActivityTask](https://docs.aws.amazon.com/step-functions/latest/apireference/API_GetActivityTask.html)`
+ `[ListActivities](https://docs.aws.amazon.com/step-functions/latest/apireference/API_ListActivities.html)`
+ `[SendTaskFailure](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html)`
+ `[SendTaskHeartbeat](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html)`
+ `[SendTaskSuccess](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html)`

**注意**  
透過 `GetActivityTask` 輪詢活動任務，可能會導致某些實作延遲。請參閱 [避免輪詢活動任務時的延遲](sfn-best-practices.md#bp-activity-pollers)。

## 等待活動任務完成
<a name="activities-wait"></a>

在任務定義中設定 `TimeoutSeconds`，以設定狀態等待的時間長度。若要讓任務保持作用中並且等待，請在 `TimeoutSeconds` 中設定的時間內使用 `[SendTaskHeartbeat](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html)`，定期從您的活動工作者傳送活動訊號。透過設定長逾時持續時間並主動傳送活動訊號，Step Functions 中的活動最多可等待一年才能完成執行。

例如，如果您需要一個可等待冗長程序結果的工作流程，請執行下列動作：

1. 使用主控台來建立活動，或藉由呼叫 `[CreateActivity](https://docs.aws.amazon.com/step-functions/latest/apireference/API_CreateActivity.html)` 來建立它。記下活動 ARN。

1. 在狀態機器定義的活動任務狀態中參考該 ARN，並且設定 `TimeoutSeconds`。

1. 使用 `[GetActivityTask](https://docs.aws.amazon.com/step-functions/latest/apireference/API_GetActivityTask.html)`，並且參考該 ARN，以實作可輪詢工作的活動工作者。

1. 在您於狀態機器任務定義的 `HeartbeatSeconds` 中所設定的時間內，定期使用 `[SendTaskHeartbeat](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html)`，讓任務不會逾時。

1. 開始執行您的狀態機器。

1. 啟動您的活動工作者程序。

執行會暫停於活動任務狀態，並等待活動工作者輪詢任務。將 `taskToken` 提供給活動工作者後，工作流程就會等待 `[SendTaskSuccess](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html)` 或 `[SendTaskFailure](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html)` 提供狀態。如果在 `TimeoutSeconds` 中設定的時間前，執行並未收到這些資訊或 `[SendTaskHeartbeat](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html)` 呼叫，則執行會失敗且執行歷史記錄中會包含 `ExecutionTimedOut` 事件。

## 範例：Ruby 中的活動工作者
<a name="example-ruby-activity-worker"></a>

下列活動工作者程式碼範例實作消費者生產者模式，其中包含可設定的輪詢器和活動工作者執行緒數量。輪詢器執行緒會持續長時間輪詢 Step Functions 中的活動任務。擷取活動任務時，會通過限制的封鎖佇列，讓活動執行緒接收。
+ 如需詳細資訊，請參閱 [適用於 Ruby 的 AWS SDK API 參考](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/)。
+ 如要下載此程式碼和相關資源，請參閱 GitHub 上的 [step-functions-ruby-activity-worker](https://github.com/aws-samples/step-functions-ruby-activity-worker) 儲存庫。

下列程式碼是此範例 Ruby 活動工作者的主要進入點。

```
require_relative '../lib/step_functions/activity'
    credentials = Aws::SharedCredentials.new
    region = 'us-west-2'
    activity_arn = 'ACTIVITY_ARN'

    activity = StepFunctions::Activity.new(
      credentials: credentials,
      region: region,
      activity_arn: activity_arn,
      workers_count: 1,
      pollers_count: 1,
      heartbeat_delay: 30
    )

    # Start method block contains your custom implementation to process the input 
    activity.start do |input|
      { result: :SUCCESS, echo: input['value'] }                    
    end
```

您必須指定活動 ARN 和區域。此程式碼包含您可以設定的預設值，例如執行緒和活動訊號延遲的數量。


| 項目 | Description | 
| --- | --- | 
|  `require_relative`  |  以下範例活動工作者程式碼的相對路徑。  | 
|  `region`  |  AWS活動的區域。  | 
|  `workers_count`  |  您的活動工作者的執行緒數目。對於大多數實作，10 到 20 個執行緒應該就足夠。處理活動所需的時間越長，就可能需要更多執行緒。預估時，以每秒處理的活動數目乘以第 99 個百分位數活動處理延遲 (以秒為單位)。  | 
|  `pollers_count`  |  您的輪詢器的執行緒數目。對於大多數實作，10 到 20 個執行緒應該就足夠。  | 
|  `heartbeat_delay`  |  活動訊號之間的延遲 (以秒為單位)。  | 
| input | 實作您的活動邏輯。 | 

## 後續步驟
<a name="activities-nextsteps"></a>

如要詳細了解建立使用活動工作者的狀態機器，請參閱：
+ [使用 Step Functions 建立活動狀態機器](tutorial-creating-activity-state-machine.md)