本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 探索 Step Functions 中的服務整合模式 對於服務整合，您可以指定各種整合模式，以控制狀態機器與整合 AWS 服務的互動方式： + [請求回應](#connect-default) - 呼叫服務，Step Functions 在收到 HTTP 回應後立即進入下一個狀態。 + [執行任務 (.sync)](#connect-sync) - 呼叫 服務，並讓 Step Functions 等待任務完成。 + [使用任務字符等待回呼](#connect-wait-token) - 使用任務字符呼叫服務，並讓 Step Functions 等待該字符與承載一起傳回。 這些服務整合模式都由您在[任務定義](state-task.md) `"Resource"` 欄位中建立 URI 的方式所控制。 Step Functions 中的 ASL 資源值是符合 [ARN 格式](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html#arns-syntax)的唯一名稱 (URI)，但通常不會識別您帳戶中的實際*資源*。字首「`arn:aws:states:`」會設定 Step Functions 用於整合的命名空間。值`:::`的部分表示空的 `region`和 `account-id` 欄位，因為兩者都是從工作流程執行所在的區域和帳戶推斷而來。 與 的舊版整合 AWS Lambda 是 資源值指定實際 Lambda 函數資源的一個例外。Step Functions 主控台會顯示這些舊版資源，但您無法在當日圖形化 UI 中建立或編輯這類資源，除非您選擇直接編輯 ASL 程式碼。 ## 整合模式支援 標準工作流程和快速工作流程支援相同的**整合**，但不支援相同的**整合模式**。 + **標準工作流程**支援*請求回應*整合。某些服務支援*執行任務 (.sync)* 或*等待回呼 (.waitForTaskToken)*，在某些情況下也支援兩者。如需詳細資訊，請參閱下列最佳化整合資料表。 + **Express Workflows** 僅支援*請求回應*整合。 若要協助決定這兩種類型，請參閱 [在 Step Functions 中選擇工作流程類型](choosing-workflow-type.md)。 **AWS Step Functions 中的 SDK 整合** | 整合式服務 | 請求回應 | 執行任務 - *.sync* | 等待回呼 - *.waitForTaskToken* | | --- | --- | --- | --- | | [超過 200 個服務](supported-services-awssdk.md#supported-services-awssdk-list) | 標準 & Express | 不支援 | 標準 | **Step Functions 中的最佳化整合** | 整合式服務 | 請求回應 | 執行任務 - *.sync* | 等待回呼 - *.waitForTaskToken* | | --- | --- | --- | --- | | [Amazon API Gateway](connect-api-gateway.md) | 標準 & Express | 不支援 | 標準 | | [Amazon Athena](connect-athena.md) | 標準 & Express | 標準 | 不支援 | | [AWS Batch](connect-batch.md) | 標準 & Express | 標準 | 不支援 | | [Amazon Bedrock](connect-bedrock.md) | 標準 & Express | 標準 | 標準 | | [AWS CodeBuild](connect-codebuild.md) | 標準 & Express | 標準 | 不支援 | | [Amazon DynamoDB](connect-ddb.md) | 標準 & Express | 不支援 | 不支援 | | [Amazon ECS/Fargate](connect-ecs.md) | 標準 & Express | 標準 | 標準 | | [Amazon EKS](connect-eks.md) | 標準 & Express | 標準 | 標準 | | [Amazon EMR](connect-emr.md) | 標準 & Express | 標準 | 不支援 | | [Amazon EMR on EKS](connect-emr-eks.md) | 標準 & Express | 標準 | 不支援 | | [Amazon EMR Serverless](connect-emr-serverless.md) | 標準 & Express | 標準 | 不支援 | | [Amazon EventBridge](connect-eventbridge.md) | 標準 & Express | 不支援 | 標準 | | [AWS Glue](connect-glue.md) | 標準 & Express | 標準 | 不支援 | | [AWS Glue DataBrew](connect-databrew.md) | 標準 & Express | 標準 | 不支援 | | [AWS Lambda](connect-lambda.md) | 標準 & Express | 不支援 | 標準 | | [AWS Elemental MediaConvert](connect-mediaconvert.md) | 標準 & Express | 標準 | 不支援 | | [Amazon SageMaker AI](connect-sagemaker.md) | 標準 & Express | 標準 | 不支援 | | [Amazon SNS](connect-sns.md) | 標準 & Express | 不支援 | 標準 | | [Amazon SQS](connect-sqs.md) | 標準 & Express | 不支援 | 標準 | | [AWS Step Functions](connect-stepfunctions.md) | 標準 & Express | 標準 | 標準 | ## 請求回應 當您在任務狀態的`"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:region:123456789012:myTopic", "Message":"Hello from Step Functions!" }, "Next":"NEXT_STATE" } ``` 此範例參考 Amazon SNS 的[發佈](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html) API。此工作流程會在呼叫 `Publish` API 之後繼續進行下一個狀態。 **提示** 若要部署使用請求回應服務整合模式的範例工作流程，請參閱本指南中的入門教學課程或* AWS Step Functions 研討會*中的[請求回應模組](https://catalog.workshops.aws/stepfunctions/integrating-services/1-request-response)中的[整合服務](getting-started.md#step-4-integrate-a-service)。 ## 執行任務 (.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 Resource Name (ARN) 表示 Step Functions 會等待任務完成。呼叫 AWS Batch `submitJob` 之後，工作流程會暫停。當任務完成時，Step Functions 會進入下一個狀態。如需詳細資訊，請參閱 AWS Batch 範例專案：[使用 AWS Batch和 管理批次任務 Amazon SNS](batch-job-notification.md)。 如果使用此 (`.sync`) 服務整合模式的任務中止，且 Step Functions 無法取消任務，您可能會從整合服務產生額外費用。在以下情況下，可以中止任務： + 狀態機器執行會停止。 + 平行狀態的不同分支會失敗，並顯示未攔截的錯誤。 + 映射狀態的反覆運算失敗，並顯示未攔截的錯誤。 Step Functions 會盡最大努力取消任務。例如，如果 Step Functions `states:startExecution.sync`任務中止，它會呼叫 Step Functions `StopExecution` API 動作。不過，Step Functions 可能無法取消任務。原因包括但不限於： + 您的 IAM 執行角色缺少進行對應 API 呼叫的許可。 + 發生暫時性服務中斷。 當您使用`.sync`服務整合模式時，Step Functions 會使用使用指派配額和事件的輪詢來監控任務的狀態。對於相同帳戶中的`.sync`調用，Step Functions 會使用 EventBridge 事件並輪詢您在 `Task` 狀態中指定的 APIs。對於[跨帳戶](concepts-access-cross-acct-resources.md)`.sync`調用，Step Functions 只會使用輪詢。例如，對於 `states:StartExecution.sync`，Step Functions 會在 [DescribeExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeExecution.html) API 上執行輪詢，並使用您指派的配額。 **提示** 若要部署使用 .sync 整合模式的範例工作流程，請參閱* AWS Step Functions 研討會中的*[執行任務 (.sync)](https://catalog.workshops.aws/stepfunctions/integrating-services/2-sync-job)。 若要查看支援等候工作完成的整合服務清單 (`.sync`) 的詳細資訊，請參閱[將 服務與 Step Functions 整合](integrate-optimized.md)。 **注意** 使用 `.sync`或 `.waitForTaskToken` 模式的服務整合需要額外的 IAM 許可。如需詳細資訊，請參閱[Step Functions 如何為整合服務產生 IAM 政策](service-integration-iam-templates.md)。 在某些情況下，您可能會希望 Step Functions 在任務完全完成之前繼續您的工作流程。您可以使用與使用[使用任務字符等待回呼](#connect-wait-token)服務整合模式相同的方式來達成此目標。若要這樣做，請將任務字符傳遞給您的任務，然後使用 [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html)或 [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) API 呼叫傳回任務字符。Step Functions 將使用您在該呼叫中提供的資料來完成任務、停止監控任務，並繼續工作流程。 ## 使用任務字符等待回呼 回呼任務可讓工作流程暫停，直到任務字符傳回。任務可能需要等候人員核准、與第三方進行整合，或者呼叫舊版系統。對於這類任務，您可以暫停 Step Functions，直到工作流程執行達到一年的服務配額 （請參閱 [狀態調節相關的配額](service-quotas.md#service-limits-api-state-throttling))，並等待外部程序或工作流程完成。在這些情況下，Step Functions 可讓您將任務字符傳遞給 AWS SDK 服務整合，以及一些最佳化服務整合。這時任務會暫停等候，直到其收到 [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) 或 [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) 呼叫傳回的任務字符。 如果使用回呼任務字符`Task`的狀態逾時，會產生新的隨機字符。您可以從[內容物件](input-output-contextobject.md#contextobject-access)存取任務權杖。 **注意** 任務字符必須至少包含一個字元，且不得超過 1024 個字元。 若要`.waitForTaskToken`搭配 AWS SDK 整合使用 ，您使用的 API 必須具有參數欄位，才能在其中放置任務字符。 **注意** 您必須從相同 AWS 帳戶中的委託人傳遞任務字符。如果您從不同 AWS 帳戶中的委託人傳送權杖，則權杖將無法運作。 **提示** 若要部署使用回呼任務字符整合模式的範例工作流程，請參閱* AWS Step Functions 研討會*中的[使用任務字符回呼](https://catalog.workshops.aws/stepfunctions/integrating-services/3-callback-token)。 若要查看支援等候任務字符的整合服務清單 (`.waitForTaskToken`) 的詳細資訊，請參閱[將 服務與 Step Functions 整合](integrate-optimized.md)。 **Topics** + [任務字符範例](#connect-wait-example) + [從內容物件取得權杖](#wait-token-contextobject) + [設定活動訊號逾時為正在等候的任務](#wait-token-hearbeat) ### 任務字符範例 在此範例中，Step Functions 工作流程需要與外部微服務整合，才能在核准工作流程中執行點數檢查。Step Functions 會發佈 Amazon SQS 訊息，其中包含任務權杖做為訊息的一部分。外部系統與 Amazon SQS 整合，並從佇列中提取訊息。完成後，它會傳回結果和原始任務字符。Step Functions 接著會繼續其工作流程。 ![\[正在等候任務字符傳回的 SQS 任務\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/wait-for-task-token.png) 參考 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"` 欄位，就能存取該任務字符。初始 `$$.`會指定路徑存取[內容物件](#wait-token-contextobject)，並取得執行中執行中目前任務的任務字符。 完成之後，外部服務會呼叫 [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) 或 [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html)，其中包含 `taskToken`。工作流程只有在此時才會繼續進入下一個狀態。 **注意** 若要避免當程序無法隨著 `SendTaskSuccess` 或 `SendTaskFailure` 傳送任務字符而造成無限期等候的情況，請參閱[設定活動訊號逾時為正在等候的任務](#wait-token-hearbeat)。 ### 從內容物件取得權杖 內容物件是包含執行相關資訊的內部 JSON 物件。正如狀態輸入，它可以在執行期間搭配路徑，從 `"Parameters"` 欄位中存取而得。從任務定義存取時，它會包含有關特定執行的資訊，包括任務字符。 ``` { "Execution": { "Id": "arn:aws:states:region:account-id:execution:stateMachineName:executionName", "Input": { "key": "value" }, "Name": "executionName", "RoleArn": "arn:aws:iam::account-id: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:region:account-id: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" } ``` 如需內容物件的詳細資訊，請參閱本指南[從 Step Functions 中的內容物件存取執行資料](input-output-contextobject.md)中的 [處理輸入和輸出](concepts-input-output-filtering.md)一節。 ### 設定活動訊號逾時為正在等候的任務 正在等候任務字符的任務將會等候，直到執行到達一年的服務配額 (請參閱[狀態調節相關的配額](service-quotas.md#service-limits-api-state-throttling))。為了避免執行發生停滯，您可以設定在狀態機器定義中設定活動訊號逾時間隔。使用 [`HeartbeatSeconds`](state-task.md) 欄位，指定逾時的間隔。 ``` { "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 動作傳回任務字符： + [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) + [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) + [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html) 如果等候任務沒有在 10 分鐘期間內收到有效的任務字符，則此任務就會失敗，且收到名稱 `States.Timeout` 的錯誤。 如需詳細資訊，請參閱回呼任務範例專案：[使用 Amazon SQS、Amazon SNS 和 Lambda 建立回呼模式範例](callback-task-sample-sqs.md)。