本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS Step Functions 叫用動作參考
執行下列 AWS CodePipeline 動作：
+ 從管道啟動 AWS Step Functions 狀態機器執行。
+ 透過動作組態中的屬性或位於管道成品中做為輸入傳遞的檔案，為狀態機器提供初始狀態。
+ 選擇性地設定執行 ID 字首，以識別源自動作的執行。
+ 支援[標準和快速](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-standard-vs-express.html)狀態機器。
**注意**
Step Functions 動作會在 Lambda 上執行，因此具有與 Lambda 函數成品大小配額相同的成品大小配額。如需詳細資訊，請參閱《[Lambda 開發人員指南》中的 Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。
## 動作類型
+ 類別：`Invoke`
+ 擁有者：`AWS`
+ 提供者：`StepFunctions`
+ 版本：`1`
## 組態參數
**StateMachineArn**
必要：是
要叫用之狀態機器的 Amazon Resource Name (ARN)。
**ExecutionNamePrefix**
必要：否
依預設，動作執行 ID 會用作為狀態機執行名稱。如果有提供字首，會與連字號用於動作執行 ID 的前綴，並一起用作為狀態機執行名稱。
```
myPrefix-1624a1d1-3699-43f0-8e1e-6bafd7fde791
```
對於快速狀態機器，名稱應該只包含 0-9、A-Z、a-z、- 和 \$1。
**InputType**
必要：否
+ **Literal (常值)** (預設)：指定此項時，**Input (輸入)** 欄位中的數值會直接傳遞至狀態機輸入。
選取**文字**時**輸入**欄位的範例項目：
```
{"action": "test"}
```
+ **FilePath**：由 **Input (輸入)** 欄位指定的輸入成品中的檔案內容會用作為狀態機器執行的輸入。當 **InputType** 設定為 **FilePath** 時，需要輸入成品。
選取 **FilePath** 時**，輸入**欄位的範例項目：
```
assets/input.json
```
**Input**
必要：有條件
+ **Literal (常值)**：當 **InputType ** 設定為 **Literal (常值)** (預設) 時，此為選用欄位。
如果有提供此項，**input (輸入)** 欄位會直接用作為狀態機器執行的輸入。否則，會使用空的 JSON 物件 `{}` 叫用狀態機器。
+ **FilePath**：當 **InputType** 設定為 **FilePath** 時，需要此欄位。
當 **InputType** 設定為 **FilePath** 時，也需要輸入成品。
在指定的輸入成品中的檔案內容會用作為狀態機器執行的輸入。
## Input artifacts (輸入成品)
+ **成品數量：** `0 to 1`
+ **描述：** 如果 **InputType** 設定為 **FilePath**，則需要此成品，並且會用來取得狀態機器執行的輸入。
## 輸出成品
+ **成品數量：** `0 to 1`
+ **描述：**
+ **標準狀態機器**：如果有提供此項，則會使用狀態機器的輸出填入輸出成品。這是在狀態機器執行成功完成後，從 [Step Functions DescribeExecution API](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeExecution.html) 回應的 `output` 屬性取得。
+ **快速狀態機器**：不支援。
## 輸出變數
此動作會產生輸出變數，並且可供管道中下游動作的動作組態進行參考。
如需詳細資訊，請參閱[變數參考](reference-variables.md)。
**StateMachineArn**
狀態機器的 ARN。
**ExecutionArn**
執行狀態機器的 ARN。僅限標準狀態機器。
## 服務角色許可：`StepFunctions`動作
對於 `StepFunctions`動作，下列是使用 Step Functions 叫用動作建立管道所需的最低許可。
```
{
"Effect": "Allow",
"Action": [
"states:DescribeStateMachine",
"states:DescribeExecution",
"states:StartExecution"
],
"Resource": "resource_ARN"
},
```
## 動作組態範例
### 預設輸入的範例
------
#### [ YAML ]
```
Name: ActionName
ActionTypeId:
Category: Invoke
Owner: AWS
Version: 1
Provider: StepFunctions
OutputArtifacts:
- Name: myOutputArtifact
Configuration:
StateMachineArn: arn:aws:states:us-east-1:111122223333:stateMachine:HelloWorld-StateMachine
ExecutionNamePrefix: my-prefix
```
------
#### [ JSON ]
```
{
"Name": "ActionName",
"ActionTypeId": {
"Category": "Invoke",
"Owner": "AWS",
"Version": 1,
"Provider": "StepFunctions"
},
"OutputArtifacts": [
{
"Name": "myOutputArtifact"
}
],
"Configuration": {
"StateMachineArn": "arn:aws:states:us-east-1:111122223333:stateMachine:HelloWorld-StateMachine",
"ExecutionNamePrefix": "my-prefix"
}
}
```
------
### 常值輸入的範例
------
#### [ YAML ]
```
Name: ActionName
ActionTypeId:
Category: Invoke
Owner: AWS
Version: 1
Provider: StepFunctions
OutputArtifacts:
- Name: myOutputArtifact
Configuration:
StateMachineArn: arn:aws:states:us-east-1:111122223333:stateMachine:HelloWorld-StateMachine
ExecutionNamePrefix: my-prefix
Input: '{"action": "test"}'
```
------
#### [ JSON ]
```
{
"Name": "ActionName",
"ActionTypeId": {
"Category": "Invoke",
"Owner": "AWS",
"Version": 1,
"Provider": "StepFunctions"
},
"OutputArtifacts": [
{
"Name": "myOutputArtifact"
}
],
"Configuration": {
"StateMachineArn": "arn:aws:states:us-east-1:111122223333:stateMachine:HelloWorld-StateMachine",
"ExecutionNamePrefix": "my-prefix",
"Input": "{\"action\": \"test\"}"
}
}
```
------
### 輸入檔案的範例
------
#### [ YAML ]
```
Name: ActionName
InputArtifacts:
- Name: myInputArtifact
ActionTypeId:
Category: Invoke
Owner: AWS
Version: 1
Provider: StepFunctions
OutputArtifacts:
- Name: myOutputArtifact
Configuration:
StateMachineArn: 'arn:aws:states:us-east-1:111122223333:stateMachine:HelloWorld-StateMachine'
ExecutionNamePrefix: my-prefix
InputType: FilePath
Input: assets/input.json
```
------
#### [ JSON ]
```
{
"Name": "ActionName",
"InputArtifacts": [
{
"Name": "myInputArtifact"
}
],
"ActionTypeId": {
"Category": "Invoke",
"Owner": "AWS",
"Version": 1,
"Provider": "StepFunctions"
},
"OutputArtifacts": [
{
"Name": "myOutputArtifact"
}
],
"Configuration": {
"StateMachineArn": "arn:aws:states:us-east-1:111122223333:stateMachine:HelloWorld-StateMachine",
"ExecutionNamePrefix": "my-prefix",
"InputType": "FilePath",
"Input": "assets/input.json"
}
}
```
------
## Behavior (行為)
在發行期間，CodePipeline 會使用動作組態中指定的輸入來執行設定的狀態機器。
當 **InputType** 設定為 **Literal (常值)** 時，**Input (輸入)** 動作組態欄位的內容會用作為狀態機器的輸入。當沒有提供常值輸入時，狀態機器執行會使用空的 JSON 物件 `{}`。如需在不輸入的情況下執行狀態機器執行的詳細資訊，請參閱 [Step Functions StartExecution API](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)。
當 **InputType** 設定為 **FilePath** 時，動作會將輸入成品解壓縮，並使用在 **Input (輸入)** 動作組態欄位中指定的檔案內容做為狀態機器的輸入。指定 **FilePath** 時，**Input (輸入)** 欄位為必要欄位，且必須存在輸入成品；否則，動作會失敗。
成功啟動執行後，行為將分歧為兩種狀態機類型，「標準」**和「快速」**。
### 標準狀態機器
如果標準狀態機器執行成功啟動，CodePipeline 會輪詢 `DescribeExecution` API，直到執行達到結束狀態為止。如果執行成功完成，表示動作成功；否則會失敗。
如果已設定輸出成品，該成品將包含狀態機器的傳回值。這是在狀態機器執行成功完成後，從 [Step Functions DescribeExecution API](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeExecution.html) 回應的 `output` 屬性取得。請注意，此 API 上有強制執行輸出長度限制。
#### 錯誤處理
+ 如果該動作無法啟動狀態機器執行，則動作執行會失敗。
+ 如果在 CodePipeline Step Functions 動作達到逾時 （預設為 7 天） 之前，狀態機器執行無法達到結束狀態，則動作執行會失敗。儘管發生此類失敗，狀態機器可能會繼續執行。如需 Step Functions 中狀態機器執行逾時的詳細資訊，請參閱[標準與快速工作流程。](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-standard-vs-express.html)
**注意**
您可以為具有動作的帳戶要求增加叫用動作逾時的配額。不過，增加配額會套用至該帳戶所有區域中此類型的所有動作。
+ 如果狀態機器執行達到 FAILED、TIMED\$1OUT 或 ABORTED 的終端狀態，則動作執行會失敗。
### 快速狀態機器
如果快速狀態機器執行啟動成功，叫用動作執行會成功完成。
針對快速狀態機器設定的動作考量：
+ 您無法指定輸出成品。
+ 該動作不會等待狀態機器執行完成。
+ 在 CodePipeline 中啟動動作執行後，即使狀態機器執行失敗，動作執行也會成功。
#### 錯誤處理
+ 如果 CodePipeline 無法啟動狀態機器執行，動作執行會失敗。否則，該動作會立即成功。無論狀態機器執行需要多長時間才能完成或其結果，動作都會在 CodePipeline 中成功。
## 另請參閱
以下相關資源可協助您使用此動作。
+ [AWS Step Functions 開發人員指南](https://docs.aws.amazon.com/step-functions/latest/dg/) – 如需狀態機器、執行和狀態機器輸入的相關資訊，請參閱 *AWS Step Functions 開發人員指南*。
+ [教學課程：在管道中使用 AWS Step Functions 叫用動作](tutorials-step-functions.md) – 本教學課程會協助您開始使用範例標準狀態機器，並說明如何透過新增 Step Functions 叫用動作來使用主控台更新管道。