服務整合模式 - AWS Step Functions

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

服務整合模式

AWS Step Functions 直接與 Amazon 州語言中的服務整合。您可以使用三種服務整合模式來控制這些 AWS 服務。

  • 呼叫服務,讓 Step Functions 式在取得 HTTP 回應後立即進入下一個狀態。

  • 呼叫服務並讓 Step Functions 等待工作完成。

  • 使用任務令牌調用服務,並讓 Step Functions 等待,直到該令牌與有效負載一起返回。

這些服務整合模式中的每一種都是由您在任務定義"Resource"欄位中建立 URI 的方式所控制。

如需為整合式服務設定 AWS Identity and Access Management (IAM) 的相關資訊,請參閱整合式服務的 IAM 政策

請求回應

當您在工作狀態的"Resource"字串中指定服務,而且提供資源時,Step Functions 會等待 HTTP 回應,然後進入下一個狀態。Step Functions 不會等待工作完成。

以下範例顯示如何發佈 Amazon SNS 主題。

"Send message to SNS":{ "Type":"Task", "Resource":"arn:aws:states:::sns:publish", "Parameters":{ "TopicArn":"arn:aws:sns:us-east-1:123456789012:myTopic", "Message":"Hello from Step Functions!" }, "Next":"NEXT_STATE" }

此範例參考 Amazon SNS 的發佈 API。此工作流程會在呼叫 Publish API 之後繼續進行下一個狀態。

提示

若要將使用要求回應服務整合模式的範例工作流程部署至您的工作流程 AWS 帳戶,請參閱單元 2- AWS Step Functions 研討會的要求回應

執行任務 (.sync)

對於整合式服務 (例如 AWS Batch 和 Amazon ECS),Step Functions 可以等待請求完成,然後再進入下一個狀態。若要讓 Step Functions 式等候,請在任務狀態定義中指定"Resource"欄位,並在資源 URI 後面加上.sync尾碼。

例如,提交 AWS Batch 工作時,請使用狀態機定義中的"Resource"欄位,如此範例所示。

"Manage Batch task": { "Type": "Task", "Resource": "arn:aws:states:::batch:submitJob.sync", "Parameters": { "JobDefinition": "arn:aws:batch:us-east-2:123456789012:job-definition/testJobDefinition", "JobName": "testJob", "JobQueue": "arn:aws:batch:us-east-2:123456789012:job-queue/testQueue" }, "Next": "NEXT_STATE" }

.sync部分附加到資源 Amazon 資源名稱(ARN)表示 Step Functions 等待任務完成。呼叫 AWS Batch submitJob 之後,工作流程會暫停。當工作完成時,Step Functions 進展到下一個狀態。如需詳細資訊,請參閱 AWS Batch 範例專案:管理批次工作 (AWS Batch、Amazon SNS)

如果使用 this (.sync) 服務整合模式的工作中止,而 Step Functions 無法取消工作,則整合式服務可能會產生額外費用。在下列情況下,工作可以中止:

  • 狀態機執行已停止。

  • 平行狀態的不同分支失敗,並顯示未捕獲的錯誤。

  • Map 狀態的迭代失敗,並顯示未捕獲的錯誤。

Step Functions 將盡最大努力取消任務。例如,如果一個 Step Functions states:startExecution.sync 任務被中止,它將調用 Step Functions StopExecution API 動作。但是,Step Functions 可能無法取消工作。這種情況的原因包括但不限於:

  • 您的 IAM 執行角色缺乏進行對應 API 呼叫的權限。

  • 發生暫時性服務中斷。

當您使用.sync服務整合模式時,Step Functions 會使用耗用您指派的配額和事件的輪詢來監視工作的狀態。對於相同帳戶內的.sync呼叫,Step Functions 會使用 EventBridge 事件並輪詢您在狀態中指定的 API。Task對於跨帳戶.sync調用,Step Functions 僅使用輪詢。例如,「Step Functions」會對 DescribeExecutionAPI 執行輪詢states:StartExecution.sync,並使用您指派的配額。

若要查看支援等候工作完成的整合服務清單 (.sync) 的詳細資訊,請參閱Step Functions 的最佳化整合

注意

使用該.sync模式的服務整合需要額外的 IAM 許可。如需詳細資訊,請參閱 整合式服務的 IAM 政策

在某些情況下,您可能希望 Step Functions 在工作完全完成之前繼續您的工作流程。您可以使用與使用等候傳回任務字符的回呼服務整合模式相同的方式來達成此目的。為此,請將任務令牌傳遞給您的工作,然後使用SendTaskSuccessSendTaskFailureAPI 調用將其返回。Step Functions 將使用您在該呼叫中提供的資料來完成工作、停止監視工作,並繼續工作流程。

等候傳回任務字符的回呼

回呼任務可讓工作流程暫停,直到任務字符傳回。任務可能需要等候人員核准、與第三方進行整合,或者呼叫舊版系統。對於這類工作,您可以暫停 Step Functions,直到工作流程執行達到一年的服務配額為止 (請參閱,與狀態節流有關的配額),然後等待外部處理序或工作流程完成。在這些情況下,Step Functions 允許您將任務令牌傳遞給 AWS SDK 服務集成,以及一些優化的服務集成。這時任務會暫停等候,直到其收到 SendTaskSuccessSendTaskFailure 呼叫傳回的任務字符。

如果使用回調任務令牌的Task狀態超時,則會生成新的隨機令牌。您可以從上下文對象訪問任務令牌。

注意

工作權杖必須至少包含一個字元,且不得超過 1024 個字元。

若要.waitForTaskToken搭配 AWS SDK 整合使用,您使用的 API 必須具有可放置工作權杖的參數欄位。

注意

您必須從相同 AWS 帳戶內的主體傳遞工作權杖。如果您從不同 AWS 帳戶中的主體發送令牌,則令牌將不起作用。

提示

要將使用回調任務令牌服務集成模式的示例工作流程部署到您的 AWS 帳戶,請參閱模塊 4-使用 AWS Step Functions 工作坊的任務令牌等待回調

若要查看支援等候任務字符的整合服務清單 (.waitForTaskToken) 的詳細資訊,請參閱Step Functions 的最佳化整合

任務字符範例

在此範例中,「Step Functions」工作流程需要與外部微服務整合,才能在核准工作流程中執行信用檢查。Step Functions 會發佈 Amazon SQS 訊息,其中包含任務權杖做為訊息的一部分。外部系統與 Amazon SQS 整合,並將訊息從佇列中取出。完成後,它將返回結果和原始任務令牌。Step Functions 接著會繼續其工作流程。


            正在等候任務字符傳回的 SQS 任務

參考 Amazon SQS 的任務定義"Resource"欄位.waitForTaskToken會附加在結尾。

"Send message to SQS": { "Type": "Task", "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken", "Parameters": { "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue", "MessageBody": { "Message": "Hello from Step Functions!", "TaskToken.$": "$$.Task.Token" } }, "Next": "NEXT_STATE" }

這告訴 Step Functions 暫停並等待任務令牌。當您使用 .waitForTaskToken 指定資源時,使用包含特殊路徑目標 ($$.Task.Token) 之狀態定義的 "Parameters" 欄位,就能存取該任務字符。最初的 $$. 會指定該路徑要存取內容物件,並取得進行中執行之目前任務的任務字符。

完成之後,外部服務會呼叫 SendTaskSuccessSendTaskFailure,其中包含 taskToken。工作流程只有在此時才會繼續進入下一個狀態。

注意

若要避免當程序無法隨著 SendTaskSuccessSendTaskFailure 傳送任務字符而造成無限期等候的情況,請參閱設定活動訊號逾時為正在等候的任務

取得來自內容物件的字符

內容物件是一種 JSON 物件,其中包含關於執行的資訊。正如狀態輸入,它可以在執行期間搭配路徑,從 "Parameters" 欄位中存取而得。從任務定義存取時,它會包含有關特定執行的資訊,包括任務字符。

{ "Execution": { "Id": "arn:aws:states:us-east-1:123456789012:execution:stateMachineName:executionName", "Input": { "key": "value" }, "Name": "executionName", "RoleArn": "arn:aws:iam::123456789012:role...", "StartTime": "2019-03-26T20:14:13.192Z" }, "State": { "EnteredTime": "2019-03-26T20:14:13.192Z", "Name": "Test", "RetryCount": 3 }, "StateMachine": { "Id": "arn:aws:states:us-east-1:123456789012:stateMachine:stateMachineName", "Name": "name" }, "Task": { "Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W" } }

您可以使用特殊路徑,從任務定義之 "Parameters" 欄位中存取任務字符。若要存取輸入或內容物件,您必須先指定該參數將作為路徑,方法是將 .$ 附加到參數名稱。以下命令會採用 "Parameters" 規格,指定來自輸入和內容物件的節點。

"Parameters": { "Input.$": "$", "TaskToken.$": "$$.Task.Token" },

在這兩種情況下,附加.$到參數名稱告訴 Step Functions 數期望路徑。在第一個案例中,"$" 就是包括整個輸入的路徑。在第二個案例中,$$. 會指定路徑將存取內容物件,而 $$.Task.Token 會將參數設定成正在執行中內容物件的任務字符值。

在 Amazon SQS 範例.waitForTaskToken中,在"Resource"欄位中告知 Step Functions 等待任務權杖傳回。該"TaskToken.$": "$$.Task.Token"參數會將該權杖做為 Amazon SQS 訊息的一部分傳遞。

"Send message to SQS": { "Type": "Task", "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken", "Parameters": { "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue", "MessageBody": { "Message": "Hello from Step Functions!", "TaskToken.$": "$$.Task.Token" } }, "Next": "NEXT_STATE" }

如需詳細資訊,請參閱本指南中輸入和輸出處理一節的內容物件

設定活動訊號逾時為正在等候的任務

正在等候任務字符的任務將會等候,直到執行到達一年的服務配額 (請參閱與狀態節流有關的配額)。為了避免執行發生停滯,您可以設定在狀態機器定義中設定活動訊號逾時間隔。使用 HeartbeatSeconds 欄位,指定逾時的間隔。

{ "StartAt": "Push to SQS", "States": { "Push to SQS": { "Type": "Task", "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken", "HeartbeatSeconds": 600, "Parameters": { "MessageBody": { "myTaskToken.$": "$$.Task.Token" }, "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/push-based-queue" }, "ResultPath": "$.SQS", "End": true } } }

在此狀態機器定義中,任務會將訊息推送至 Amazon SQS,並等待外部程序使用提供的任務權杖回呼。"HeartbeatSeconds": 600 欄位會將活動訊號逾時間隔設定為 10 分鐘。此任務將等候下列其中一個 API 動作傳回任務字符:

如果等候任務沒有在 10 分鐘期間內收到有效的任務字符,則此任務就會失敗,且收到名稱 States.Timeout 的錯誤。

如需詳細資訊,請參閱回呼任務範例專案:回呼模式範例 (Amazon SQS、Amazon SNS、Lambda)