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

# AWS::Serverless::StateMachine
<a name="sam-resource-statemachine"></a>

建立 AWS Step Functions 狀態機器，您可以使用它來協調 AWS Lambda 函數和其他 AWS 資源，以形成複雜且強大的工作流程。

如需 Step Functions 的詳細資訊，請參閱《[AWS Step Functions 開發人員指南](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html)》。

**注意**  
當您部署到 時 AWS CloudFormation， 會將您的 AWS SAM 資源 AWS SAM 轉換為 CloudFormation 資源。如需詳細資訊，請參閱[為 產生 CloudFormation 資源 AWS SAM](sam-specification-generated-resources.md)。

## 語法
<a name="sam-resource-statemachine-syntax"></a>

若要在 AWS Serverless Application Model (AWS SAM) 範本中宣告此實體，請使用下列語法。

### YAML
<a name="sam-resource-statemachine-syntax.yaml"></a>

```
Type: AWS::Serverless::StateMachine
Properties:
  AutoPublishAlias: {{String}}
  UseAliasAsEventTarget: {{Boolean}}
  [Definition](#sam-statemachine-definition): {{Map}}
  [DefinitionSubstitutions](#sam-statemachine-definitionsubstitutions): {{Map}}
  [DefinitionUri](#sam-statemachine-definitionuri): {{String | [S3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-definitions3location)}}
  DeploymentPreference: {{[DeploymentPreference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-stepfunctions-statemachinealias-deploymentpreference.html)}}
  [Events](#sam-statemachine-events): {{EventSource}}
  [Logging](#sam-statemachine-logging): {{[LoggingConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-loggingconfiguration)}}
  [Name](#sam-statemachine-name): {{String}}
  [PermissionsBoundary](#sam-statemachine-permissionsboundary): {{String}}
  [Policies](#sam-statemachine-policies): {{String | List | Map}}
  PropagateTags: {{Boolean}}
  [RolePath](#sam-statemachine-rolepath): {{String}}
  [Role](#sam-statemachine-role): {{String}}
  [Tags](#sam-statemachine-tags): {{Map}}
  [Tracing](#sam-statemachine-tracing): {{[TracingConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-tracingconfiguration)}}
  [Type](#sam-statemachine-type): {{String}}
```

## Properties
<a name="sam-resource-statemachine-properties"></a>

 `AutoPublishAlias`   <a name="sam-statemachine-autopublishalias"></a>
狀態機器別名的名稱。若要進一步了解如何使用 Step Functions 狀態機器別名，請參閱《 *AWS Step Functions 開發人員指南*》中的[使用版本和別名管理持續部署](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-cd-aliasing-versioning.html)。  
使用 `DeploymentPreference`設定別名的部署偏好設定。如果您未指定 `DeploymentPreference`， AWS SAM 會設定流量一次轉移到較新的狀態機器版本。  
AWS SAM `Retain` 根據預設， 會將版本的 `DeletionPolicy`和 `UpdateReplacePolicy` 設為 。舊版不會自動刪除。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::StepFunctions::StateMachineAlias` 資源的 ` [ Name](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachinealias.html#cfn-stepfunctions-statemachinealias-name)` 屬性。

 `UseAliasAsEventTarget`   <a name="sam-statemachine-usealiasaseventtarget"></a>
指出是否將使用 `AutoPublishAlias` 屬性建立的別名傳遞至以 [Events](#sam-statemachine-events) 定義的事件來源目標。  
指定 `True`以使用別名做為事件的目標。  
*類型*：布林值  
*必要*：否  
*預設*：`False`  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `Definition`   <a name="sam-statemachine-definition"></a>
狀態機器定義是一個物件，其中物件的格式與您的 AWS SAM 範本檔案格式相符，例如 JSON 或 YAML。狀態機器定義遵循 [Amazon 狀態語言](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html)。  
如需內嵌狀態機器定義的範例，請參閱 [範例](#sam-resource-statemachine--examples)。  
您必須提供 `Definition`或 `DefinitionUri`。  
*類型*：映射  
*必要*：有條件  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `DefinitionSubstitutions`   <a name="sam-statemachine-definitionsubstitutions"></a>
string-to-string映射，指定狀態機器定義中預留位置變數的映射。這可讓您將執行時間取得的值 （例如，從內部函數） 注入狀態機器定義。  
*類型*：映射  
*必要*：否  
*CloudFormation 相容性*：此屬性類似於 `AWS::StepFunctions::StateMachine` 資源的 `[DefinitionSubstitutions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-definitionsubstitutions)` 屬性。如果在內嵌狀態機器定義中指定任何內部函數， 會將項目 AWS SAM 新增至此屬性，以將其插入狀態機器定義。

 `DefinitionUri`   <a name="sam-statemachine-definitionuri"></a>
Amazon Simple Storage Service (Amazon S3) URI 或以 [Amazon States Language](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html) 撰寫之狀態機器定義的本機檔案路徑。  
如果您提供本機檔案路徑，範本必須經過包含 `sam deploy`或 `sam package`命令的工作流程，才能正確轉換定義。若要這樣做，您必須使用 0.52.0 版或更新版本的 AWS SAM CLI。  
您必須提供 `Definition`或 `DefinitionUri`。  
*類型*：字串 \| [S3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-definitions3location)  
*必要*：有條件  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::StepFunctions::StateMachine` 資源的 `[DefinitionS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-definitions3location)` 屬性。

 `DeploymentPreference`   <a name="sam-statemachine-deploymentpreference"></a>
啟用和設定漸進式狀態機器部署的設定。若要進一步了解 Step Functions 逐步部署，請參閱《 *AWS Step Functions 開發人員指南*》中的[使用版本和別名管理持續部署](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-cd-aliasing-versioning.html)。  
在設定此屬性`AutoPublishAlias`之前，請指定 。您的`DeploymentPreference`設定將套用至以 指定的別名`AutoPublishAlias`。  
當您指定 時`DeploymentPreference`， 會自動 AWS SAM 產生`StateMachineVersionArn`子屬性值。  
*類型*：[DeploymentPreference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-stepfunctions-statemachinealias-deploymentpreference.html)  
*必要*：否  
*CloudFormation compatibility*： AWS SAM 產生`StateMachineVersionArn`屬性值並將其連接至 `AWS::StepFunctions::StateMachineAlias` 資源的 `[DeploymentPreference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachinealias.html#cfn-stepfunctions-statemachinealias-deploymentpreference)` 屬性`DeploymentPreference`，並將其傳遞`DeploymentPreference`至 。

 `Events`   <a name="sam-statemachine-events"></a>
指定觸發此狀態機器的事件。事件由類型和一組屬性組成，這些屬性取決於類型。  
*類型*︰[EventSource](sam-property-statemachine-statemachineeventsource.md)  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `Logging`   <a name="sam-statemachine-logging"></a>
定義記錄哪些執行歷史記錄事件及其記錄位置。  
*類型*：[LoggingConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-loggingconfiguration)  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::StepFunctions::StateMachine` 資源的 `[LoggingConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-loggingconfiguration)` 屬性。

 `Name`   <a name="sam-statemachine-name"></a>
狀態機器的名稱。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::StepFunctions::StateMachine` 資源的 `[StateMachineName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-statemachinename)` 屬性。

 `PermissionsBoundary`   <a name="sam-statemachine-permissionsboundary"></a>
用於此狀態機器執行角色的許可界限 ARN。此屬性只有在為您產生角色時才有效。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::IAM::Role` 資源的 `[PermissionsBoundary](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html#cfn-iam-role-permissionsboundary)` 屬性。

 `Policies`   <a name="sam-statemachine-policies"></a>
此狀態機器的許可政策。政策會附加至狀態機器的預設 AWS Identity and Access Management (IAM) 執行角色。  
此屬性接受單一值或值清單。允許數值包括：  
+ [AWS SAM 政策範本](serverless-policy-templates.md).
+ [AWS 受管政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies)或[客戶受管政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#customer-managed-policies)ARN的 。
+ 下列[清單中](https://github.com/aws/serverless-application-model/blob/develop/samtranslator/internal/data/aws_managed_policies.json)受 AWS 管政策的名稱。
+ 在 中格式化YAML為映射的[內嵌 IAM 政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#inline-policies)。
如果您設定 `Role` 屬性，則會忽略此屬性。
*類型*：字串 \| 清單 \| 映射  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

`PropagateTags`  <a name="sam-statemachine-propagatetags"></a>
指出是否要將標籤從 `Tags` 屬性傳遞至您[AWS::Serverless::StateMachine](sam-specification-generated-resources-statemachine.md)產生的資源。指定 `True` 在產生的資源中傳播標籤。  
*類型*：布林值  
*必要*：否  
*預設*：`False`  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `Role`   <a name="sam-statemachine-role"></a>
做為此狀態機器執行角色的 IAM 角色 ARN。  
*類型：*字串  
*必要*：有條件  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::StepFunctions::StateMachine` 資源的 `[ RoleArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-rolearn)` 屬性。

 `RolePath`   <a name="sam-statemachine-rolepath"></a>
狀態機器 IAM 執行角色的路徑。  
為您產生角色時，請使用此屬性。使用 `Role` 屬性指定角色時，請勿使用 。  
*類型：*字串  
*必要*：有條件  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::IAM::Role` 資源的 `[Path](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html#cfn-iam-role-path)` 屬性。

 `Tags`   <a name="sam-statemachine-tags"></a>
string-to-string映射，指定新增至狀態機器和對應執行角色的標籤。如需標籤有效索引鍵和值的資訊，請參閱 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html) 資源的[標籤](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-tags)屬性。  
*類型*：映射  
*必要*：否  
*CloudFormation 相容性*：此屬性類似於 `[Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-tags)` `AWS::StepFunctions::StateMachine` resource. AWS SAM automatically 新增`stateMachine:createdBy:SAM`標籤至此資源，以及為其產生的預設角色。

 `Tracing`   <a name="sam-statemachine-tracing"></a>
選取是否 AWS X-Ray 已啟用狀態機器。如需搭配 Step Functions 使用 X-Ray 的詳細資訊，請參閱《 *AWS Step Functions 開發人員指南*》中的 [AWS X-Ray 和 Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-xray-tracing.html)。  
*類型*：[TracingConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-tracingconfiguration)  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::StepFunctions::StateMachine` 資源的 `[TracingConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-tracingconfiguration)` 屬性。

 `Type`   <a name="sam-statemachine-type"></a>
狀態機器的類型。  
*有效值*：`STANDARD` 或 `EXPRESS`  
*類型：*字串  
*必要*：否  
*預設*：`STANDARD`  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::StepFunctions::StateMachine` 資源的 `[StateMachineType](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-statemachinetype)` 屬性。

## 傳回值
<a name="sam-resource-statemachine-return-values"></a>

### Ref
<a name="sam-resource-statemachine-return-values-ref"></a>

當您將此資源的邏輯 ID 提供給 Ref 內部函數時，Ref 會傳回基礎`AWS::StepFunctions::StateMachine`資源的 Amazon Resource Name (ARN)。

如需使用 `Ref`函數的詳細資訊，請參閱*AWS CloudFormation 《 使用者指南*[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html)》中的 。

### Fn::GetAtt
<a name="sam-resource-statemachine-return-values-fn--getatt"></a>

`Fn::GetAtt` 會傳回此類型之指定屬性的值。以下為可用屬性及傳回值的範例。

如需使用 的詳細資訊`Fn::GetAtt`，請參閱*AWS CloudFormation 《 使用者指南*[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html)》中的 。

`Name`  <a name="Name-fn::getatt"></a>
傳回狀態機器的名稱，例如 `HelloWorld-StateMachine`。

## 範例
<a name="sam-resource-statemachine--examples"></a>

### 狀態機器定義檔案
<a name="sam-resource-statemachine--examples--state-machine-definition-file"></a>

以下是內嵌狀態機器定義的範例，允許 lambda 函數叫用狀態機器。請注意，此範例預期 `Role` 屬性會設定適當的政策以允許呼叫。`my_state_machine.asl.json` 檔案必須以 [Amazon States 語言](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html)撰寫。

在此範例中，`DefinitionSubstitution`項目允許狀態機器在 AWS SAM 範本檔案中包含宣告的資源。

#### YAML
<a name="sam-resource-statemachine--examples--state-machine-definition-file--yaml"></a>

```
MySampleStateMachine:
  Type: AWS::Serverless::StateMachine
  Properties:
    DefinitionUri: statemachine/my_state_machine.asl.json
    Role: arn:aws:iam::123456123456:role/service-role/my-sample-role
    Tracing:
      Enabled: true
    DefinitionSubstitutions:
      MyFunctionArn: !GetAtt MyFunction.Arn
      MyDDBTable: !Ref TransactionTable
```

### 內嵌狀態機器定義
<a name="sam-resource-statemachine--examples--inline-state-machine-definition"></a>

以下是內嵌狀態機器定義的範例。

在此範例中， AWS SAM 範本檔案是以 YAML 撰寫，因此狀態機器定義也以 YAML 表示。若要以 JSON 宣告內嵌狀態機器定義，請以 JSON 撰寫 AWS SAM 範本檔案。

#### YAML
<a name="sam-resource-statemachine--examples--inline-state-machine-definition--yaml"></a>

```
MySampleStateMachine:
  Type: AWS::Serverless::StateMachine
  Properties:
    Definition:
      StartAt: MyLambdaState
      States:
        MyLambdaState:
          Type: Task
          Resource: arn:aws:lambda:us-east-1:123456123456:function:my-sample-lambda-app
          End: true
    Role: arn:aws:iam::123456123456:role/service-role/my-sample-role
    Tracing:
      Enabled: true
```