本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 Step Functions 中使用版本和別名管理持續部署
您可以使用 Step Functions 透過狀態機器*版本*和*別名*來管理工作流程的持續部署。*版本*是您可以執行之狀態機器的編號、不可變快照。*別名*是狀態機器最多兩個版本的指標。
您可以維護狀態機器的多個版本，並在生產工作流程中管理其部署。使用別名，您可以在不同的工作流程版本之間路由流量，並將這些工作流程逐漸部署到生產環境。
此外，您可以使用版本或別名啟動狀態機器執行。如果您在啟動狀態機器執行時未使用版本或別名，Step Functions 會使用狀態機器定義的最新版本。
**狀態機器修訂**
狀態機器可以有一或多個修訂。當您使用 [UpdateStateMachine](https://docs.aws.amazon.com/step-functions/latest/apireference/API_UpdateStateMachine.html) API 動作更新狀態機器時，它會建立新的狀態機器修訂版。*修訂*是狀態機器定義和組態的不可變唯讀快照。您無法從修訂啟動狀態機器執行，而且修訂沒有 ARN。修訂具有 `revisionId`，這是通用的唯一識別符 (UUID)。
**Topics**
+ [版本](concepts-state-machine-version.md)
+ [別名](concepts-state-machine-alias.md)
+ [版本和別名授權](auth-version-alias.md)
+ [將執行與版本或別名建立關聯](execution-alias-version-associate.md)
+ [部署範例](example-alias-version-deployment.md)
+ [逐步部署版本](version-rolling-deployment.md)
# Step Functions 工作流程中的狀態機器版本
*版本*是狀態機器的編號、**不可變**快照。您可以發佈對該狀態機器所做的最新修訂的版本。每個版本都有唯一的 Amazon Resource Name (ARN)，這是狀態機器 ARN 和以冒號 (：) 分隔的版本編號的組合。下列範例顯示狀態機器版本 ARN 的格式。
```
arn:partition:states:region:account-id:stateMachine:myStateMachine:1
```
若要開始使用狀態機器版本，您必須發佈第一個版本。發佈版本之後，您可以使用版本 ARN 叫用 [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) API 動作。您無法編輯版本，但可以更新狀態機器並發佈新版本。您也可以發佈狀態機器的多個版本。
![\[模糊說明圖顯示版本如何成為狀態機器的不可變快照。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/versioning-concept.png)
當您發佈新版本的狀態機器時，Step Functions 會為其指派版本編號。版本編號從 1 開始，並針對每個新版本單調增加。特定狀態機器不會重複使用版本編號。如果您刪除狀態機器的第 10 版，然後發佈新版本，Step Functions 會將它發佈為第 11 版。
對於狀態機器的所有版本，下列屬性相同：
+ 狀態機器的所有版本共用相同類型 [（標準或快速）](choosing-workflow-type.md)。
+ 您無法在版本之間變更狀態機器的名稱或建立日期。
+ 標籤全域套用至狀態機器。您可以使用 [TagResource](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TagResource.html) 和 [UntagResource](https://docs.aws.amazon.com/step-functions/latest/apireference/API_UntagResource.html) API 動作來管理狀態機器的標籤。
狀態機器也包含屬於每個版本 和 一部分的屬性[revision](concepts-cd-aliasing-versioning.md#statemachinerev)，但這些屬性可能會在兩個指定版本或修訂之間有所不同。這些屬性包括[狀態機器定義](https://docs.aws.amazon.com/step-functions/latest/apireference/API_UpdateStateMachine.html#StepFunctions-UpdateStateMachine-request-definition)、[IAM 角色](https://docs.aws.amazon.com/step-functions/latest/apireference/API_UpdateStateMachine.html#StepFunctions-UpdateStateMachine-request-roleArn)、[追蹤組態](https://docs.aws.amazon.com/step-functions/latest/apireference/API_UpdateStateMachine.html#StepFunctions-UpdateStateMachine-request-tracingConfiguration)和[記錄組態](https://docs.aws.amazon.com/step-functions/latest/apireference/API_UpdateStateMachine.html#StepFunctions-UpdateStateMachine-request-loggingConfiguration)。
## 發佈狀態機器版本 （主控台）
您最多可以發佈 1000 個版本的狀態機器。若要請求提高此軟性限制，請使用 中的**支援中心**頁面[AWS 管理主控台](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html)。您可以從主控台手動刪除未使用的版本，或叫用 [DeleteStateMachineVersion](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DeleteStateMachineVersion.html) API 動作。
**發佈狀態機器版本**
1. 開啟 [Step Functions 主控台](https://console.aws.amazon.com/states/home?region=us-east-1#/)，然後選擇現有的狀態機器。
1. 在**狀態機器詳細資訊**頁面上，選擇**編輯**。
1. 視需要編輯狀態機器定義，然後選擇**儲存**。
1. 選擇 **Publish version (發佈版本)**。
1. （選用） 在出現的對話方塊的**描述**欄位中，輸入狀態機器版本的簡短描述。
1. 選擇**發布**。
**注意**
當您發佈新版本的狀態機器時，Step Functions 會為其指派版本編號。版本編號從 1 開始，並針對每個新版本單調增加。特定狀態機器不會重複使用版本編號。如果您刪除狀態機器的第 10 版，然後發佈新版本，Step Functions 會將它發佈為第 11 版。
## 使用 Step Functions API 操作管理版本
Step Functions 提供下列 API 操作來發佈和管理狀態機器版本：
+ [PublishStateMachineVersion](https://docs.aws.amazon.com/step-functions/latest/apireference/API_PublishStateMachineVersion.html) – 從狀態機器[revision](concepts-cd-aliasing-versioning.md#statemachinerev)的目前 發佈版本。
+ [UpdateStateMachine](https://docs.aws.amazon.com/step-functions/latest/apireference/API_UpdateStateMachine.html) – 如果您更新狀態機器並在相同的請求`true`中將 `publish` 參數設定為 ，則會發佈新的狀態機器版本。
+ [CreateStateMachine](https://docs.aws.amazon.com/step-functions/latest/apireference/API_CreateStateMachine.html) – 如果您將 `publish` 參數設定為 ，則會發佈狀態機器的第一個修訂版`true`。
+ [ListStateMachineVersions](https://docs.aws.amazon.com/step-functions/latest/apireference/API_ListStateMachineVersions.html) – 列出指定狀態機器 ARN 的版本。
+ [DescribeStateMachine](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeStateMachine.html) – 傳回 中指定版本 ARN 的狀態機器版本詳細資訊`stateMachineArn`。
+ [DeleteStateMachineVersion](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DeleteStateMachineVersion.html) – 刪除狀態機器版本。
若要使用 從名為 的狀態機器目前修訂版發佈新版本`myStateMachine` AWS Command Line Interface，請使用 `publish-state-machine-version`命令：
```
aws stepfunctions publish-state-machine-version --state-machine-arn arn:aws:states:region:account-id:stateMachine:myStateMachine
```
回應會傳回 `stateMachineVersionArn`。例如，先前的命令會傳回 的回應`arn:aws:states:region:account-id:stateMachine:myStateMachine:1`。
**注意**
當您發佈新版本的狀態機器時，Step Functions 會為其指派版本編號。版本編號從 1 開始，並針對每個新版本單調增加。特定狀態機器不會重複使用版本編號。如果您刪除狀態機器的第 10 版，然後發佈新版本，Step Functions 會將它發佈為第 11 版。
## 從主控台執行狀態機器版本
若要開始使用狀態機器版本，您必須先從目前狀態機器 發佈版本[revision](concepts-cd-aliasing-versioning.md#statemachinerev)。若要發佈版本，請使用 Step Functions 主控台或叫用 [PublishStateMachineVersion](https://docs.aws.amazon.com/step-functions/latest/apireference/API_PublishStateMachineVersion.html) API 動作。您也可以使用名為 的選用參數叫用 [UpdateStateMachineAlias](https://docs.aws.amazon.com/step-functions/latest/apireference/API_UpdateStateMachineAlias.html) API 動作，`publish`以更新狀態機器並發佈其版本。
您可以使用 主控台或叫用 [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) API 動作並提供版本 ARN 來開始執行版本。您也可以使用[別名](concepts-state-machine-alias.md)來啟動版本的執行。根據其[路由組態](concepts-state-machine-alias.md#alias-routing-config)，別名會將流量路由到特定版本。
如果您在不使用版本的情況下啟動狀態機器執行，Step Functions 會使用狀態機器的最新修訂版來執行。如需 Step Functions 如何將執行與版本建立關聯的詳細資訊，請參閱 [將執行與版本或別名建立關聯](execution-alias-version-associate.md)。
**使用狀態機器版本啟動執行**
1. 開啟 [Step Functions 主控台](https://console.aws.amazon.com/states/home?region=us-east-1#/)，然後選擇您已發佈一或多個版本的現有狀態機器。若要了解如何發佈版本，請參閱 [發佈狀態機器版本 （主控台）](#procedure-create-versions)。
1. 在**狀態機器詳細資訊**頁面上，選擇**版本**索引標籤。
1. 在**版本**區段中，執行下列動作：
1. 選取您要啟動執行的版本。
1. 選擇 **Start execution (開始執行)**。
1. （選用） 在**開始執行**對話方塊中，輸入執行的名稱。
1. （選用） ，輸入執行輸入，然後選擇**開始執行**。
# Step Functions 工作流程中的狀態機器別名
*別名*是同一狀態機器最多兩個版本的指標。您可以為狀態機器建立多個別名。每個別名都有唯一的 Amazon Resource Name (ARN)。別名 ARN 是狀態機器的 ARN 和別名名稱的組合，以冒號 (：) 分隔。下列範例顯示狀態機器別名 ARN 的格式。
```
arn:partition:states:region:account-id:stateMachine:myStateMachine:aliasName
```
您可以使用別名，在兩個狀態機器版本的其中一個之間[路由流量](#alias-routing-config)。您也可以建立指向單一版本的別名。別名只能指向狀態機器版本。您無法使用別名指向另一個別名。您也可以更新別名，以指向不同版本的狀態機器。
![\[顯示 80% 的請求傳送至 v1，以及 20% 傳送至 v2 的別名圖表。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/aliases-concept.png)
**Topics**
+ [建立狀態機器別名 （主控台）](#procedure-create-aliases)
+ [使用 APIs 管理別名](#manage-aliases-with-api)
+ [別名路由組態](#alias-routing-config)
+ [使用別名執行狀態機器 （主控台）](#procedure-run-exec-with-alias)
## 建立狀態機器別名 （主控台）
您可以使用 Step Functions 主控台或叫用 [CreateStateMachineAlias](https://docs.aws.amazon.com/step-functions/latest/apireference/API_CreateStateMachineAlias.html) API 動作，為每個狀態機器建立最多 100 個別名。若要請求提高此軟性限制，請使用 中的**支援中心**頁面[AWS 管理主控台](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html)。從主控台或透過叫用 [DeleteStateMachineAlias](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DeleteStateMachineAlias.html) API 動作來刪除未使用的別名。
**建立狀態機器別名**
1. 開啟 [Step Functions 主控台](https://console.aws.amazon.com/states/home?region=us-east-1#/)，然後選擇現有的狀態機器。
1. 在**狀態機器詳細資訊**頁面上，選擇**別名**索引標籤。
1. 選擇**建立新別名**。
1. 在 **Create alias (建立別名)** 頁面，執行下列動作：
1. 輸入**別名名稱**。
1. (選用) 輸入別名的 **Description (描述)**。
1. 若要在別名上設定路由，請參閱[別名路由組態](#alias-routing-config)。
1. 選擇**建立別名**。
## 使用 Step Functions API 操作管理別名
Step Functions 提供下列 API 操作，可用來建立和管理狀態機器別名或取得別名的相關資訊：
+ [CreateStateMachineAlias](https://docs.aws.amazon.com/step-functions/latest/apireference/API_CreateStateMachineAlias.html) – 為狀態機器建立別名。
+ [DescribeStateMachineAlias](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeStateMachineAlias.html) – 傳回狀態機器別名的詳細資訊。
+ [ListStateMachineAliases](https://docs.aws.amazon.com/step-functions/latest/apireference/API_ListStateMachineAliases.html) – 列出指定狀態機器 ARN 的別名。
+ [UpdateStateMachineAlias](https://docs.aws.amazon.com/step-functions/latest/apireference/API_UpdateStateMachineAlias.html) – 透過修改其 `description`或 來更新現有狀態機器別名的組態`routingConfiguration`。
+ [DeleteStateMachineAlias](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DeleteStateMachineAlias.html) – 刪除狀態機器別名。
若要使用 建立名為 的別名`PROD`，指向名為 之狀態機器的第 `myStateMachine` 1 版 AWS Command Line Interface，請使用 `create-state-machine-alias`命令。
```
aws stepfunctions create-state-machine-alias --name PROD --routing-configuration "[{\"stateMachineVersionArn\":\"arn:aws:states:region:account-id:stateMachine:myStateMachine:1\",\"weight\":100}]"
```
## 別名路由組態
您可以使用別名，在狀態機器的兩個版本之間路由執行流量。例如，假設您想要啟動新版本的狀態機器。您可以在別名上設定路由，以降低部署新版本所涉及的風險。透過設定路由，您可以將大部分流量傳送至舊版、經過測試的狀態機器。然後，新版本可以收到較小的百分比，直到您確認可安全地轉傳新版本為止。
若要定義路由組態，請確定您發佈別名指向的兩個狀態機器版本。當您從別名開始執行時，Step Functions 會隨機選擇要從路由組態中指定的版本執行的狀態機器版本。它以您在別名路由組態中指派給每個版本的流量百分比為基礎。
**在別名上設定路由組態**
+ 在**建立別名**頁面的**路由組態**下，執行下列動作：
1. 針對**版本**，選擇別名指向的第一個狀態機器版本。
1. 選取在**兩個版本之間分割流量**核取方塊。
**提示**
若要指向單一版本，請清除**在兩個版本之間分割流量**核取方塊。
1. 針對**版本**，選擇別名必須指向的第二個版本。
1. 在**流量百分比**欄位中，指定要路由至每個版本的流量百分比。例如，輸入 **60**和 **40** 將 60% 的執行流量路由到第一個版本，將 40% 的流量路由到第二個版本。
合併流量百分比必須等於 100%。
## 使用別名執行狀態機器 （主控台）
您可以從主控台或使用別名的 ARN 叫用 [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) API 動作，以使用別名啟動狀態機器執行。Step Functions 接著會執行別名指定的版本。根據預設，如果您在啟動狀態機器執行時未指定版本或別名，Step Functions 會使用最新的修訂版。
**使用別名啟動狀態機器執行**
1. 開啟 [Step Functions 主控台](https://console.aws.amazon.com/states/home?region=us-east-1#/)，然後選擇您為其建立別名的現有狀態機器。如需建立別名的詳細資訊，請參閱 [建立狀態機器別名 （主控台）](#procedure-create-aliases)。
1. 在**狀態機器詳細資訊**頁面上，選擇**別名**索引標籤。
1. 在**別名**區段中，執行下列動作：
1. 選取您要啟動執行的別名。
1. 選擇 **Start execution (開始執行)**。
1. （選用） 在**開始執行**對話方塊中，輸入執行的名稱。
1. 如有必要，請輸入執行輸入，然後選擇**開始執行**。
# Step Functions 工作流程中版本和別名的授權
若要使用版本或別名叫用 Step Functions API 動作，您需要適當的許可。若要授權版本或別名叫用 API 動作，Step Functions 會使用狀態機器的 ARN，而不是使用版本 ARN 或別名 ARN。您也可以縮小特定版本或別名的許可範圍。如需詳細資訊，請參閱[縮小許可範圍](#auth-scope-permission-version-alias)。
您可以使用下列名為 的狀態機器 IAM 政策範例`myStateMachine`，叫用 [CreateStateMachineAlias](https://docs.aws.amazon.com/step-functions/latest/apireference/API_CreateStateMachineAlias.html) API 動作來建立狀態機器別名。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "states:CreateStateMachineAlias",
"Resource": "arn:aws:states:us-east-1:123456789012:stateMachine:myStateMachine"
}
]
}
```
當您設定允許或拒絕使用狀態機器版本或別名存取 API 動作的許可時，請考慮下列事項：
+ 如果您使用 [CreateStateMachine](https://docs.aws.amazon.com/step-functions/latest/apireference/API_CreateStateMachine.html) 和 [UpdateStateMachine](https://docs.aws.amazon.com/step-functions/latest/apireference/API_UpdateStateMachine.html) API 動作的 `publish` 參數來發佈新的狀態機器版本，您也需要 [PublishStateMachineVersion](https://docs.aws.amazon.com/step-functions/latest/apireference/API_PublishStateMachineVersion.html) API 動作的 `ALLOW` 許可。
+ [DeleteStateMachine](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DeleteStateMachine.html) API 動作會刪除與狀態機器相關聯的所有版本和別名。
## 縮小版本或別名的許可範圍
您可以使用限定詞進一步縮小版本或別名所需的授權許可範圍。限定詞是指版本編號或別名名稱。您可以使用 限定詞來限定狀態機器。下列範例是狀態機器 ARN，使用名為 的別名`PROD`做為限定詞。
```
arn:aws:states:region:account-id:stateMachine:myStateMachine:PROD
```
如需合格和不合格 ARNs的詳細資訊，請參閱 [將執行與版本或別名建立關聯](execution-alias-version-associate.md)。
您可以使用 IAM 政策`Condition`陳述式`states:StateMachineQualifier`中名為 的選用內容金鑰來縮小許可範圍。例如，名為 之狀態機器的下列 IAM 政策會`myStateMachine`拒絕使用名為 `PROD`或 版本的別名叫用 [DescribeStateMachine](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeStateMachine.html) API 動作的存取權`1`。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "states:DescribeStateMachine",
"Resource": "arn:aws:states:us-east-1:123456789012:stateMachine:myStateMachine",
"Condition": {
"ForAnyValue:StringEquals": {
"states:StateMachineQualifier": [
"PROD",
"1"
]
}
}
}
]
}
```
下列清單指定 API 動作，您可以在其中使用`StateMachineQualifier`內容索引鍵縮小許可範圍。
+ [CreateStateMachineAlias](https://docs.aws.amazon.com/step-functions/latest/apireference/API_CreateStateMachineAlias.html)
+ [DeleteStateMachineAlias](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DeleteStateMachineAlias.html)
+ [DeleteStateMachineVersion](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DeleteStateMachineVersion.html)
+ [DescribeStateMachine](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeStateMachine.html)
+ [DescribeStateMachineAlias](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeStateMachineAlias.html)
+ [ListExecutions](https://docs.aws.amazon.com/step-functions/latest/apireference/API_ListExecutions.html)
+ [ListStateMachineAliases](https://docs.aws.amazon.com/step-functions/latest/apireference/API_ListStateMachineAliases.html)
+ [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)
+ [StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html)
+ [UpdateStateMachineAlias](https://docs.aws.amazon.com/step-functions/latest/apireference/API_UpdateStateMachineAlias.html)
# Step Functions 如何將執行與版本或別名建立關聯
Step Functions 會根據您用來叫用 [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) API 動作的 Amazon Resource Name (ARN)，將執行與版本或別名建立關聯。Step Functions 會在執行開始時間執行此動作。
您可以使用合格或不合格的 ARN 啟動狀態機器執行。
+ **合格 ARN** – 是指以版本編號或別名名稱結尾的狀態機器 ARN。
下列合格 ARN 範例是指名為 `3`的狀態機器版本`myStateMachine`。
```
arn:aws:states:region:account-id:stateMachine:myStateMachine:3
```
下列合格 ARN 範例是指名為 之狀態機器`PROD`的別名`myStateMachine`。
```
arn:aws:states:region:account-id:stateMachine:myStateMachine:PROD
```
+ **不合格的 ARN** – 是指沒有版本號碼或別名名稱尾碼的狀態機器 ARN。
```
arn:aws:states:region:account-id:stateMachine:myStateMachine
```
例如，如果您的合格 ARN 參考版本 `3`，Step Functions 會將執行與此版本建立關聯。它不會將執行與指向版本 的任何別名建立關聯`3`。
如果您合格的 ARN 參考別名，Step Functions 會將執行與該別名和別名指向的版本建立關聯。執行只能與一個別名建立關聯。
**注意**
如果您使用不合格的 ARN 啟動執行，即使版本使用相同的狀態機器 ，Step Functions 也不會將該執行與版本建立關聯[revision](concepts-cd-aliasing-versioning.md#statemachinerev)。例如，如果第 3 版使用最新的修訂版，但您使用不合格的 ARN 啟動執行，則 Step Functions 不會將該執行與第 3 版建立關聯。
## 檢視從版本或別名開始的執行
Step Functions 提供下列方式，可讓您檢視從版本或別名開始的執行：
### 使用 API 動作
您可以透過叫用 [DescribeExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeExecution.html) 和 [ListExecutions](https://docs.aws.amazon.com/step-functions/latest/apireference/API_ListExecutions.html) API 動作來檢視與版本或別名相關聯的所有執行。這些 API 動作會傳回用來啟動執行的版本或別名的 ARN。這些動作也會傳回其他詳細資訊，包括執行的狀態和 ARN。
您也可以提供狀態機器別名 ARN 或版本 ARN，列出與特定別名或版本相關聯的執行。
下列 [ListExecutions](https://docs.aws.amazon.com/step-functions/latest/apireference/API_ListExecutions.html) API 動作的範例回應顯示用於啟動名為 *myFirstExecution* 之狀態機器執行的別名 ARN。
下列程式碼片段中的*斜體*文字代表資源特定資訊。
```
{
"executions": [
{
"executionArn": "arn:aws:states:region:account-id:execution:myStateMachine:myFirstExecution",
"stateMachineArn": "arn:aws:states:region:account-id:stateMachine:myStateMachine",
"stateMachineAliasArn": "arn:aws:states:region:account-id:stateMachine:myStateMachine:PROD",
"name": "myFirstExecution",
"status": "SUCCEEDED",
"startDate": "2023-04-20T23:07:09.477000+00:00",
"stopDate": "2023-04-20T23:07:09.732000+00:00"
}
]
}
```
### 使用 Step Functions 主控台
您也可以從 [Step Functions 主控台檢視版本或別名啟動的](https://console.aws.amazon.com/states/home?region=us-east-1#/)執行。下列程序說明如何檢視從特定版本開始的執行：
1. 開啟 [Step Functions 主控台](https://console.aws.amazon.com/states/home?region=us-east-1#/)，然後選擇您已發佈[版本](concepts-state-machine-version.md#procedure-create-versions)或建立[別名](concepts-state-machine-alias.md#procedure-create-aliases)的現有狀態機器。此範例說明如何檢視從特定狀態機器版本開始的執行。
1. 選擇**版本**索引標籤，然後從版本清單中選擇**版本**。
**提示**
依屬性或值方塊篩選，以搜尋特定版本。
1. 在*版本詳細資訊頁面上*，您可以看到從所選版本開始的所有進行中和過去狀態機器執行的清單。
下圖顯示*版本詳細資訊*主控台頁面。此頁面列出由名為 之狀態機器第 *4* 版啟動的執行`MathAddDemo`。此清單也會顯示由名為 的別名啟動的執行`PROD`。此別名會將執行流量路由到第 *4* 版。
![\[狀態機器版本詳細資訊主控台頁面的說明性螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/view-version-executions.png)
### 使用 CloudWatch 指標
對於您以 開頭的每個狀態機器執行[Qualified ARN](#qualifiedARN)，Step Functions 會發出其他指標，其名稱和值與目前發出的指標相同。這些額外的指標包含每個版本識別符的維度，以及您啟動執行的別名名稱。透過這些指標，您可以在版本層級監控狀態機器執行，並判斷何時可能需要回復案例。您也可以根據這些指標[建立 Amazon CloudWatch 警示](procedure-cw-metrics.md#monitoring-using-cloudwatch-console-set-alarm)。
Step Functions 會針對您以別名或版本開頭的執行發出下列指標：
+ `ExecutionTime`
+ `ExecutionsAborted`
+ `ExecutionsFailed`
+ `ExecutionsStarted`
+ `ExecutionsSucceeded`
+ `ExecutionsTimedOut `
如果您使用版本 ARN 開始執行，Step Functions 會使用 發佈指標，`StateMachineArn`並使用 `StateMachineArn`和 `Version`維度發佈第二個指標。
如果您使用別名 ARN 開始執行，Step Functions 會發出下列指標：
+ 不合格的 ARN 和版本的兩個指標。
+ 具有 `StateMachineArn`和 `Alias`維度的指標。
# 範例：Step Functions 中的別名和版本部署
下列 Canary 部署技術範例示範如何使用 部署新的狀態機器版本 AWS Command Line Interface。在此範例中，您建立的別名會將 20% 的執行流量路由到新版本。然後，它會將剩餘的 80% 路由到較早的版本。若要使用[別名](concepts-state-machine-alias.md)部署新的狀態機器[版本](concepts-state-machine-version.md)和轉移執行流量，請完成下列步驟：
1.
**從目前的狀態機器修訂版發佈版本。**
使用 AWS CLI 中的 **publish-state-machine-version**命令，從名為 的狀態機器目前修訂版發佈版本 `myStateMachine:`
```
aws stepfunctions publish-state-machine-version --state-machine-arn arn:aws:states:region:account-id:stateMachine:myStateMachine
```
回應會傳回您發佈`stateMachineVersionArn`的 版本。例如 `arn:aws:states:region:account-id:stateMachine:myStateMachine:1`。
1.
**建立指向狀態機器版本的別名。**
使用 **create-state-machine-alias**命令建立名為 的別名`PROD`，指向 第 1 版`myStateMachine`：
```
aws stepfunctions create-state-machine-alias --name PROD --routing-configuration "[{\"stateMachineVersionArn\":\"arn:aws:states:region:account-id:stateMachine:myStateMachine:1\",\"weight\":100}]"
```
1.
**確認別名啟動的執行使用正確的發佈版本。**
在 **start-execution**命令**PROD**中提供別名的 `myStateMachine` ARN，以啟動 的新執行：
```
aws stepfunctions start-execution
--state-machine-arn arn:aws:states:region:account-id:stateMachineAlias:myStateMachine:PROD
--input "{}"
```
如果您在 [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) 請求中提供狀態機器 ARN，它會使用最新的[revision](concepts-cd-aliasing-versioning.md#statemachinerev)狀態機器，而不是別名中指定的版本來啟動執行。
1.
**更新狀態機器定義並發佈新版本。**
更新`myStateMachine`並發佈其新版本。若要這樣做，請使用 **update-state-machine**命令的選用`publish`參數：
```
aws stepfunctions update-state-machine
--state-machine-arn arn:aws:states:region:account-id:stateMachine:myStateMachine
--definition $UPDATED_STATE_MACHINE_DEFINITION
--publish
```
回應`stateMachineVersionArn`會傳回新版本的 。例如 `arn:aws:states:region:account-id:stateMachine:myStateMachine:2`。
1.
**更新別名以指向這兩個版本，並設定別名的[路由組態](concepts-state-machine-alias.md#alias-routing-config)。**
使用 **update-state-machine-alias**命令來更新別名 的路由組態`PROD`。設定別名，使 80% 的執行流量進入第 1 版，其餘 20% 進入第 2 版：
```
aws stepfunctions update-state-machine-alias --state-machine-alias-arn arn:aws:states:region:account-id:stateMachineAlias:myStateMachine:PROD --routing-configuration "[{\"stateMachineVersionArn\":\"arn:aws:states:region:account-id:stateMachine:myStateMachine:1\",\"weight\":80}, {\"stateMachineVersionArn\":\"arn:aws:states:region:account-id:stateMachine:myStateMachine:2\",\"weight\":20}]"
```
1.
**將第 1 版取代為第 2 版。**
驗證新的狀態機器版本是否正常運作後，您可以部署新的狀態機器版本。若要這樣做，請再次更新別名，將 100% 的執行流量指派給新版本。
使用 **update-state-machine-alias**命令將第 2 版別名的路由組態`PROD`設定為 100%：
```
aws stepfunctions update-state-machine-alias --state-machine-alias-arn arn:aws:states:region:account-id:stateMachineAlias:myStateMachine:PROD --routing-configuration "[{\"stateMachineVersionArn\":\"arn:aws:states:region:account-id:stateMachine:myStateMachine:2\",\"weight\":100}]"
```
**提示**
若要復原第 2 版的部署，請編輯別名的路由組態，將 100% 的流量轉移到新部署的版本。
```
aws stepfunctions update-state-machine-alias
--state-machine-alias-arn arn:aws:states:region:account-id:stateMachineAlias:myStateMachine:PROD
--routing-configuration "[{\"stateMachineVersionArn\":\"arn:aws:states:region:account-id:stateMachine:myStateMachine:1\",\"weight\":100}]"
```
您可以使用版本和別名來執行其他類型的部署。例如，您可以執行狀態機器新版本的*滾動部署*。若要這樣做，請逐漸增加指向新版本的別名路由組態中的加權百分比。
您也可以使用版本和別名來執行*藍/綠部署*。若要這樣做，請建立名為 的別名`green`，以執行您狀態機器的目前版本 1。然後，建立另一個執行`blue`新版本的別名，例如 `2`。若要測試新版本，請將執行流量傳送至`blue`別名。當您確信新版本正常運作時，請更新`green`別名以指向新版本。
# 在 Step Functions 中逐步部署狀態機器版本
滾動部署是一種部署策略，可將舊版應用程式慢慢取代為新版應用程式。若要執行狀態機器版本的滾動部署，請逐步將增加的執行流量傳送至新版本。流量和增加速率是您設定的參數。
您可以使用下列其中一個選項來執行版本的滾動部署：
+ [Step Functions 主控台](https://console.aws.amazon.com/states/home?region=us-east-1#/) – 建立指向相同狀態機器兩個版本的別名。對於此別名，您可以設定路由組態，以在兩個版本之間轉移流量。如需使用主控台推出版本的詳細資訊，請參閱 [版本](concepts-state-machine-version.md)和 [別名](concepts-state-machine-alias.md)。
+ **適用於 AWS CLI 和 SDK 的指令碼** – 使用 AWS CLI 或 AWS SDK 建立 shell 指令碼。如需詳細資訊，請參閱下列有關使用 AWS CLI 和 AWS SDK 的章節。
+ **AWS CloudFormation 範本** – 使用 `[AWS::StepFunctions::StateMachineVersion](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html)`和資源`[AWS::StepFunctions::StateMachineAlias](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html)`來發佈多個狀態機器版本，並建立別名以指向其中一個或兩個版本。
## 使用 AWS CLI 部署新的狀態機器版本
本節中的範例指令碼說明如何使用 AWS CLI ，逐步將流量從先前的狀態機器版本轉移到新的狀態機器版本。您可以使用此範例指令碼，或根據您的需求進行更新。
此指令碼顯示使用別名部署新狀態機器版本的 Canary 部署。下列步驟概述指令碼執行的任務：
1. 如果 `publish_revision` 參數設為 true，請將最新版本發佈[revision](concepts-cd-aliasing-versioning.md#statemachinerev)為狀態機器的下一個版本。如果部署成功，此版本會成為新的即時版本。
如果您將 `publish_revision` 參數設定為 false，指令碼會部署狀態機器的最後一個發佈版本。
1. 如果別名尚不存在，請建立別名。如果別名不存在，請將此別名的 100% 流量指向新版本，然後結束指令碼。
1. 更新別名的路由組態，將一小部分的流量從先前版本轉移到新版本。您可以使用 `canary_percentage` 參數設定此 Canary 百分比。
1. 根據預設，每 60 秒監控一次可設定的 CloudWatch 警示。如果這些警示中的任何一項被關閉，請立即將 100% 的流量指向先前的版本來復原部署。
在每個時間間隔之後，以秒為單位，在 中定義`alarm_polling_interval`，繼續監控警示。繼續監控，直到`canary_interval_seconds`超過 中定義的時間間隔為止。
1. 如果在 期間未設定任何警示`canary_interval_seconds`，請將 100% 的流量轉移到新版本。
1. 如果新版本部署成功，請刪除任何早於 `history_max` 參數中指定數字的版本。
```
#!/bin/bash
#
# AWS StepFunctions example showing how to create a canary deployment with a
# State Machine Alias and versions.
#
# Requirements: AWS CLI installed and credentials configured.
#
# A canary deployment deploys the new version alongside the old version, while
# routing only a small fraction of the overall traffic to the new version to
# see if there are any errors. Only once the new version has cleared a testing
# period will it start receiving 100% of traffic.
#
# For a Blue/Green or All at Once style deployment, you can set the
# canary_percentage to 100. The script will immediately shift 100% of traffic
# to the new version, but keep on monitoring the alarms (if any) during the
# canary_interval_seconds time interval. If any alarms raise during this period,
# the script will automatically rollback to the previous version.
#
# Step Functions allows you to keep a maximum of 1000 versions in version history
# for a state machine. This script has a version history deletion mechanism at
# the end, where it will delete any versions older than the limit specified.
#
# For an example that also demonstrates linear (or rolling) deployments, see the following:
# https://github.com/aws-samples/aws-stepfunctions-examples/blob/main/gradual-deploy/sfndeploy.py
set -euo pipefail
# ******************************************************************************
# you can safely change the variables in this block to your values
state_machine_name="my-state-machine"
alias_name="alias-1"
region="us-east-1"
# array of cloudwatch alarms to poll during the test period.
# to disable alarm checking, set alarm_names=()
alarm_names=("alarm1" "alarm name with a space")
# true to publish the current revision as the next version before deploy.
# false to deploy the latest version from the state machine's version history.
publish_revision=true
# true to force routing configuration update even if the current routing
# for the alias does not have a 100% routing config.
# false will abandon deploy attempt if current routing config not 100% to a
# single version.
# Be careful when you combine this flag with publish_revision - if you just
# rerun the script you might deploy the newly published revision from the
# previous run.
force=false
# percentage of traffic to route to the new version during the test period
canary_percentage=10
# how many seconds the canary deployment lasts before full deploy to 100%
canary_interval_seconds=300
# how often to poll the alarms
alarm_polling_interval=60
# how many versions to keep in history. delete versions prior to this.
# set to 0 to disable old version history deletion.
history_max=0
# ******************************************************************************
#######################################
# Update alias routing configuration.
#
# If you don't specify version 2 details, will only create 1 routing entry. In
# this case the routing entry weight must be 100.
#
# Globals:
# alias_arn
# Arguments:
# 1. version 1 arn
# 2. version 1 weight
# 3. version 2 arn (optional)
# 4. version 2 weight (optional)
#######################################
function update_routing() {
if [[ $# -eq 2 ]]; then
local routing_config="[{\"stateMachineVersionArn\": \"$1\", \"weight\":$2}]"
elif [[ $# -eq 4 ]]; then
local routing_config="[{\"stateMachineVersionArn\": \"$1\", \"weight\":$2}, {\"stateMachineVersionArn\": \"$3\", \"weight\":$4}]"
else
echo "You have to call update_routing with either 2 or 4 input arguments." >&2
exit 1
fi
${aws} update-state-machine-alias --state-machine-alias-arn ${alias_arn} --routing-configuration "${routing_config}"
}
# ******************************************************************************
# pre-run validation
if [[ (("${#alarm_names[@]}" -gt 0)) ]]; then
alarm_exists_count=$(aws cloudwatch describe-alarms --alarm-names "${alarm_names[@]}" --alarm-types "CompositeAlarm" "MetricAlarm" --query "length([MetricAlarms, CompositeAlarms][])" --output text)
if [[ (("${#alarm_names[@]}" -ne "${alarm_exists_count}")) ]]; then
echo All of the alarms to monitor do not exist in CloudWatch: $(IFS=,; echo "${alarm_names[*]}") >&2
echo Only the following alarm names exist in CloudWatch:
aws cloudwatch describe-alarms --alarm-names "${alarm_names[@]}" --alarm-types "CompositeAlarm" "MetricAlarm" --query "join(', ', [MetricAlarms, CompositeAlarms][].AlarmName)" --output text
exit 1
fi
fi
if [[ (("${history_max}" -gt 0)) && (("${history_max}" -lt 2)) ]]; then
echo The minimum value for history_max is 2. This is the minimum number of older state machine versions to be able to rollback in the future. >&2
exit 1
fi
# ******************************************************************************
# main block follows
account_id=$(aws sts get-caller-identity --query Account --output text)
sm_arn="arn:aws:states:${region}:${account_id}:stateMachine:${state_machine_name}"
# the aws command we'll be invoking a lot throughout.
aws="aws stepfunctions"
# promote the latest revision to the next version
if [[ "${publish_revision}" = true ]]; then
new_version=$(${aws} publish-state-machine-version --state-machine-arn=$sm_arn --query stateMachineVersionArn --output text)
echo Published the current revision of state machine as the next version with arn: ${new_version}
else
new_version=$(${aws} list-state-machine-versions --state-machine-arn ${sm_arn} --max-results 1 --query "stateMachineVersions[0].stateMachineVersionArn" --output text)
echo "Since publish_revision is false, using the latest version from the state machine's version history: ${new_version}"
fi
# find the alias if it exists
alias_arn_expected="${sm_arn}:${alias_name}"
alias_arn=$(${aws} list-state-machine-aliases --state-machine-arn ${sm_arn} --query "stateMachineAliases[?stateMachineAliasArn==\`${alias_arn_expected}\`].stateMachineAliasArn" --output text)
if [[ "${alias_arn_expected}" == "${alias_arn}" ]]; then
echo Found alias ${alias_arn}
echo Current routing configuration is:
${aws} describe-state-machine-alias --state-machine-alias-arn "${alias_arn}" --query routingConfiguration
else
echo Alias does not exist. Creating alias ${alias_arn_expected} and routing 100% traffic to new version ${new_version}
${aws} create-state-machine-alias --name "${alias_name}" --routing-configuration "[{\"stateMachineVersionArn\": \"${new_version}\", \"weight\":100}]"
echo Done!
exit 0
fi
# find the version to which the alias currently points (the current live version)
old_version=$(${aws} describe-state-machine-alias --state-machine-alias-arn $alias_arn --query "routingConfiguration[?weight==\`100\`].stateMachineVersionArn" --output text)
if [[ -z "${old_version}" ]]; then
if [[ "${force}" = true ]]; then
echo Force setting is true. Will force update to routing config for alias to point 100% to new version.
update_routing "${new_version}" 100
echo Alias ${alias_arn} now pointing 100% to ${new_version}.
echo Done!
exit 0
else
echo Alias ${alias_arn} does not have a routing config entry with 100% of the traffic. This means there might be a deploy in progress, so not starting another deploy at this time. >&2
exit 1
fi
fi
if [[ "${old_version}" == "${new_version}" ]]; then
echo The alias already points to this version. No update necessary.
exit 0
fi
echo Switching ${canary_percentage}% to new version ${new_version}
(( old_weight = 100 - ${canary_percentage} ))
update_routing "${new_version}" ${canary_percentage} "${old_version}" ${old_weight}
echo New version receiving ${canary_percentage}% of traffic.
echo Old version ${old_version} is still receiving ${old_weight}%.
if [[ ${#alarm_names[@]} -eq 0 ]]; then
echo No alarm_names set. Skipping cloudwatch monitoring.
echo Will sleep for ${canary_interval_seconds} seconds before routing 100% to new version.
sleep ${canary_interval_seconds}
echo Canary period complete. Switching 100% of traffic to new version...
else
echo Checking if alarms fire for the next ${canary_interval_seconds} seconds.
(( total_wait = canary_interval_seconds + $(date +%s) ))
now=$(date +%s)
while [[ ((${now} -lt ${total_wait})) ]]; do
alarm_result=$(aws cloudwatch describe-alarms --alarm-names "${alarm_names[@]}" --state-value ALARM --alarm-types "CompositeAlarm" "MetricAlarm" --query "join(', ', [MetricAlarms, CompositeAlarms][].AlarmName)" --output text)
if [[ ! -z "${alarm_result}" ]]; then
echo The following alarms are in ALARM state: ${alarm_result}. Rolling back deploy. >&2
update_routing "${old_version}" 100
echo Rolled back to ${old_version}
exit 1
fi
echo Monitoring alarms...no alarms have triggered.
sleep ${alarm_polling_interval}
now=$(date +%s)
done
echo No alarms detected during canary period. Switching 100% of traffic to new version...
fi
update_routing "${new_version}" 100
echo Version ${new_version} is now receiving 100% of traffic.
if [[ (("${history_max}" -eq 0 ))]]; then
echo Version History deletion is disabled. Remember to prune your history, the default limit is 1000 versions.
echo Done!
exit 0
fi
echo Keep the last ${history_max} versions. Deleting any versions older than that...
# the results are sorted in descending order of the version creation time
version_history=$(${aws} list-state-machine-versions --state-machine-arn ${sm_arn} --max-results 1000 --query "join(\`\"\\n\"\`, stateMachineVersions[].stateMachineVersionArn)" --output text)
counter=0
while read line; do
((counter=${counter} + 1))
if [[ (( ${counter} -gt ${history_max})) ]]; then
echo Deleting old version ${line}
${aws} delete-state-machine-version --state-machine-version-arn ${line}
fi
done <<< "${version_history}"
echo Done!
```
## 使用 AWS SDK 部署新的狀態機器版本
[aws-stepfunctions-examples](https://github.com/aws-samples/aws-stepfunctions-examples/tree/main/gradual-deploy) 中的範例指令碼說明如何使用適用於 Python 的 AWS SDK，逐步將流量從先前版本轉移到新版本的狀態機器。您可以使用此範例指令碼，或根據您的需求進行更新。
指令碼顯示下列部署策略：
+ **Canary** – 以兩個增量轉移流量。
在第一個增量中，一小部分的流量會轉移到新版本，例如 10%。在第二個增量中，在以秒為單位的指定時間間隔結束之前，剩餘的流量會轉移到新版本。只有在指定的時間間隔內沒有設定 CloudWatch 警示時，才會切換到剩餘流量的新版本。
+ **線性或滾動** – 以相等增量將流量轉移到新版本，每個增量之間的秒數相等。
例如，如果您將增量百分比指定為 **20**，並使用 `--interval`的 **600** 秒，則此部署會每 600 秒增加 20% 的流量，直到新版本收到 100% 的流量。
如果設定任何 CloudWatch 警示，此部署會立即轉返新版本。
+ **全部一次或藍/綠** – 立即將 100% 的流量轉移到新版本。如果設定任何 CloudWatch 警示，此部署會監控新版本，並自動將其轉返至先前的版本。
## 使用 AWS CloudFormation 部署新的狀態機器版本
下列 CloudFormation 範本範例會發佈兩個名為 的狀態機器版本`MyStateMachine`。它會建立名為 的別名`PROD`，指向這兩個版本，然後部署版本 `2`。
在此範例中，10% 的流量`2`每五分鐘會轉移到 版本，直到此版本收到 100% 的流量為止。此範例也會示範如何設定CloudWatch警示。如果您設定的任何警示進入 `ALARM` 狀態，部署會失敗並立即轉返。
```
MyStateMachine:
Type: AWS::StepFunctions::StateMachine
Properties:
Type: STANDARD
StateMachineName: MyStateMachine
RoleArn: arn:aws:iam::account-id:role/myIamRole
Definition:
StartAt: PassState
States:
PassState:
Type: Pass
Result: Result
End: true
MyStateMachineVersionA:
Type: AWS::StepFunctions::StateMachineVersion
Properties:
Description: Version 1
StateMachineArn: !Ref MyStateMachine
MyStateMachineVersionB:
Type: AWS::StepFunctions::StateMachineVersion
Properties:
Description: Version 2
StateMachineArn: !Ref MyStateMachine
PROD:
Type: AWS::StepFunctions::StateMachineAlias
Properties:
Name: PROD
Description: The PROD state machine alias taking production traffic.
DeploymentPreference:
StateMachineVersionArn: !Ref MyStateMachineVersionB
Type: LINEAR
Percentage: 10
Interval: 5
Alarms:
# A list of alarms that you want to monitor. If any of these alarms trigger, rollback the deployment immediately by pointing 100 percent of traffic to the previous version.
- !Ref CloudWatchAlarm1
- !Ref CloudWatchAlarm2
```