AWS Step Functions 的 Java SDK 示例：从状态机创建到活动任务编排的完整实战指南

示例工程教程后端【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples点击查看免费下载本篇技术指南聚焦javav2/example_code/stepfunctions目录下的 AWS SDK for Java (v2) 示例代码系统讲解如何运行与测试这些 AWS Step Functions 示例覆盖状态机State Machine与活动Activity的创建、查询、执行、删除以及执行历史检索等核心操作并深入剖析一个模拟聊天机器人交互的完整场景。读完本文你将掌握使用SfnClient编写可运行、可测试的 Step Functions 工作流编排代码的完整方法。AWS Step Functions 与 Java SDK v2 示例概览AWS Step Functions 是一个可视化工作流服务帮助开发者使用 AWS 服务构建分布式应用、自动化流程、编排微服务以及创建数据与机器学习ML管道。它通过Amazon States Language (ASL)定义状态机由 Step Functions 服务负责执行状态间的流转、重试与错误处理。本仓库中的 Java 示例位于 javav2/example_code/stepfunctions使用 AWS SDK for Java v2 提供的SfnClient全限定名software.amazon.awssdk.services.sfn.SfnClient封装了 Step Functions 的核心 API 调用涵盖以下文件CreateStateMachine.java根据 ASL JSON 定义创建状态机DeleteStateMachine.java删除状态机GetExecutionHistory.java检索指定执行的完整事件历史GetFailedExecutions.java列出某个状态机下的执行记录ListActivities.java列出账户中的活动ListStateMachines.java列出账户中的状态机StartExecution.java启动状态机执行scenario/StepFunctionsScenario.java多命令组合的完整场景示例所有示例使用的凭据提供器均为默认凭据提供器default credentials provider即通过环境变量、本地配置文件或 IAM 角色等链式机制自动解析 AWS 凭据无需在代码中硬编码密钥。⚠️ 重要提示运行或测试这些代码可能产生 AWS 账户费用详见 AWS 官方定价页面。建议遵循最小权限原则least privilege仅授予执行任务所需的最低权限并使用独立的测试专用资源进行实验。此外这些代码未在所有 AWS 区域测试请以所用区域的服务可用性为准。代码示例清单入门与单动作调用入门示例Get startedHello AWS Step Functions—— 见 ListStateMachines.java演示listStateMachines命令。单动作示例Single action以下代码摘录演示如何调用单个服务函数功能对应命令源码位置创建活动createActivityStepFunctionsScenario.java创建状态机createStateMachineStepFunctionsScenario.java删除活动deleteActivityStepFunctionsScenario.java删除状态机deleteStateMachineStepFunctionsScenario.java描述执行describeExecutionStepFunctionsScenario.java描述状态机describeStateMachineStepFunctionsScenario.java获取活动任务数据getActivityTaskStepFunctionsScenario.java列出活动listActivitiesListActivities.java列出状态机listStateMachinesListStateMachines.java检索执行历史getExecutionHistoryGetExecutionHistory.java检索执行列表listExecutionsGetFailedExecutions.java发送任务成功响应sendTaskSuccessStepFunctionsScenario.java启动状态机startExecutionStepFunctionsScenario.java说明原 README 中部分链接指向 route53 目录实际上这些场景代码位于stepfunctions/scenario子包本文统一采用仓库内实际路径。场景示例ScenariosGet started with AWS Step Functions—— StepFunctionsScenario.java通过多次调用同一服务内的多个函数完成一个完整业务目标。单动作示例源码解读列出状态机ListStateMachinesListStateMachines.java 是最简单的入门示例其核心逻辑如下Region region Region.US_EAST_1; SfnClient sfnClient SfnClient.builder() .region(region) .build(); listMachines(sfnClient); sfnClient.close(); public static void listMachines(SfnClient sfnClient) { try { ListStateMachinesResponse response sfnClient.listStateMachines(); ListStateMachineListItem machines response.stateMachines(); for (StateMachineListItem machine : machines) { System.out.println(The name of the state machine is: machine.name()); System.out.println(The ARN value is : machine.stateMachineArn()); } } catch (SfnException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } }关键点客户端构建采用链式 Builder 模式显式指定Region.US_EAST_1示例中的区域可依据实际部署环境调整。listStateMachines()返回ListStateMachinesResponse其stateMachines()返回StateMachineListItem列表每一项包含name()与stateMachineArn()两个核心属性。所有示例统一通过捕获SfnException继承自 AWS SDK 运行时异常读取awsErrorDetails().errorMessage()输出错误原因并调用System.exit(1)终止进程。SfnClient使用完毕后需显式调用close()释放底层 HTTP 连接资源。创建状态机CreateStateMachineCreateStateMachine.java 演示如何从 ASL JSON 定义文件创建状态机public static String createMachine(SfnClient sfnClient, String roleARN, String stateMachineName, String jsonFile) { String json getJSONString(jsonFile); try { CreateStateMachineRequest machineRequest CreateStateMachineRequest.builder() .definition(json) .name(stateMachineName) .roleArn(roleARN) .type(StateMachineType.STANDARD) .build(); CreateStateMachineResponse response sfnClient.createStateMachine(machineRequest); return response.stateMachineArn(); } catch (SfnException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } return ; }运行参数main方法校验args.length ! 3时打印用法并退出参数说明jsonFile表示状态机 Amazon States Language 定义的 JSON 文件路径roleARN用于该状态机的 IAM 角色 ARNstateMachineName要创建的状态机名称实现细节使用json-simple库的JSONParser与JSONObject读取并重新序列化 JSON 文件得到String形式的定义。CreateStateMachineRequest的type()指定为StateMachineType.STANDARD标准工作流适用于需要长期运行、有审计事件与回调的场景对应还有EXPRESS类型用于高吞吐、短时运行。返回的stateMachineArn是后续startExecution、describeStateMachine、deleteStateMachine等操作的唯一标识。启动执行StartExecutionStartExecution.java 演示启动状态机执行public static String startWorkflow(SfnClient sfnClient, String stateMachineArn, String jsonFile) { String json getJSONString(jsonFile); UUID uuid UUID.randomUUID(); String uuidValue uuid.toString(); try { StartExecutionRequest executionRequest StartExecutionRequest.builder() .input(json) .stateMachineArn(stateMachineArn) .name(uuidValue) .build(); StartExecutionResponse response sfnClient.startExecution(executionRequest); return response.executionArn(); } catch (SfnException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } return ; }运行参数stateMachineArn jsonFile其中jsonFile为包含传入工作流参数值的 JSON 文件。实现细节执行名称用UUID.randomUUID()生成避免重复执行同名冲突Step Functions 要求同一状态机下的执行名称唯一默认去重窗口为 90 天。执行输入input以 JSON 字符串形式传入状态机首状态即可通过$.参数名引用。返回的executionArn可用于后续describeExecution与getExecutionHistory。列出活动、获取执行历史与失败执行ListActivities.java构造ListActivitiesRequest并设置maxResults(10)限制返回条数遍历ActivityListItem输出activityArn()与name()。GetExecutionHistory.java接收执行 ARN构造GetExecutionHistoryRequest同样设置maxResults(10)遍历返回的HistoryEvent列表并打印type()事件类型如TaskScheduled、TaskSucceeded、ExecutionSucceeded等。GetFailedExecutions.java接收状态机 ARN通过ListExecutionsRequest.builder().stateMachineArn(...)列出该状态机的执行记录逐一输出executionArn()。注意该示例客户端区域设置为Region.US_WEST_2与其余示例US_EAST_1不同跨区域使用时需确认状态机所在区域。DeleteStateMachine.java构造DeleteStateMachineRequest传入状态机 ARN 后调用deleteStateMachine成功后打印确认信息。完整场景ChatSFN 聊天式活动编排StepFunctionsScenario.java 是一个将上述单动作串成完整业务闭环的场景示例模拟了一个聊天机器人ChatSFN工作流状态机执行到某个Task状态时暂停等待外部代码通过Activity拉取任务并回传结果。其执行流程共 7 步创建活动Create an activitycreateActivity基于CreateActivityRequest.builder().name(activityName)创建活动返回activityArn。创建状态机Create a state machine先用 IAM 创建信任策略为states.amazonaws.com的服务角色再读取chat_sfn_state_machine.json并通过 Jackson 将 JSON 中States.GetInput节点的Resource字段改写为刚创建的活动 ARN最后以修改后的定义创建状态机。描述状态机Describe the state machinedescribeStateMachine输出名称、状态、ARN 与角色 ARN然后通过控制台交互询问用户名。启动执行并交互Start execution and interact以{ name : userName }作为输入启动执行随后循环调用getActivityTask拉取活动任务返回taskToken与input打印 ChatSFN 的回复等待用户输入动作再通过sendTaskSuccess将结果回传给 Step Functions。当用户输入done时结束循环。描述执行Describe the executiondescribeExe轮询describeExecution每 2 秒检查一次状态直到SUCCEEDED为止。删除活动Delete the activitydeleteActivity释放活动资源。删除状态机Delete the state machinedeleteMachine调用删除后持续describeStateMachine轮询确认删除完成。场景中的关键方法实现创建 IAM 服务角色信任策略允许 Step Functions 服务代入String polJSON { Version: 2012-10-17, Statement: [ { Sid: , Effect: Allow, Principal: { Service: states.amazonaws.com }, Action: sts:AssumeRole } ] } ;调用iam.createRole时传入roleName、assumeRolePolicyDocument与描述信息返回角色 ARN。注意IamClient使用全局区域Region.AWS_GLOBAL而SfnClient使用Region.US_EAST_1。获取活动任务并发送成功响应Activity 的拉取-回传模式核心public static ListString getActivityTask(SfnClient sfnClient, String actArn) { ListString myList new ArrayList(); GetActivityTaskRequest getActivityTaskRequest GetActivityTaskRequest.builder() .activityArn(actArn) .build(); GetActivityTaskResponse response sfnClient.getActivityTask(getActivityTaskRequest); myList.add(response.taskToken()); myList.add(response.input()); return myList; } public static void sendTaskSuccess(SfnClient sfnClient, String token, String json) { SendTaskSuccessRequest successRequest SendTaskSuccessRequest.builder() .taskToken(token) .output(json) .build(); sfnClient.sendTaskSuccess(successRequest); }getActivityTask返回的taskToken是回传结果的凭证必须原样交给sendTaskSuccessinput是状态机传入该任务的数据。这种模式适合需要人工审批、外部系统介入的长时间运行任务。轮询等待执行完成while (!hasSucceeded) { DescribeExecutionResponse response sfnClient.describeExecution(executionRequest); status response.statusAsString(); if (status.compareTo(RUNNING) 0) { System.out.println(The state machine is still running, lets wait for it to finish.); Thread.sleep(2000); } else if (status.compareTo(SUCCEEDED) 0) { System.out.println(The Step Function workflow has succeeded); hasSucceeded true; } else { System.out.println(The Status is neither running or succeeded); } }通过statusAsString()读取执行状态在RUNNING时休眠 2 秒重试直到SUCCEEDED或进入其他终态。场景运行参数与资源文件场景主方法校验 4 个参数roleName activityName stateMachineName jsonFile分别对应 IAM 角色名、活动名、状态机名以及chat_sfn_state_machine.json的路径。该 ASL 定义文件可从仓库的resources/sample_files目录获取名为chat_sfn_state_machine.json。场景代码通过FileInputStream读取该文件并用 JacksonObjectMapper解析为JsonNode修改States.GetInput.Resource后再序列化为状态机定义字符串——这一步是场景得以把聊天任务绑定到真实 Activity 的关键。环境准备与运行前置条件要运行这些示例需要先配置好 Java 开发环境JDK 与 AWS SDK for Java v2 的依赖管理并确保本机已完成 AWS 凭据与区域配置。项目的 pom.xml 显示Java 版本21java.version21/java.version编译源码与目标均为 21AWS SDK BOMsoftware.amazon.awssdk:bom:2.35.10统一管理sfn、iam、secretsmanager、sso、ssooidc等模块版本JSON 处理json-simple:1.1.1读 ASL 定义与jackson-databind:2.18.9场景中动态改写 JSON测试与日志junit-jupiter:5.11.4、log4j-bom:2.23.1、slf4j-api:2.0.13构建插件maven-compiler-plugin:3.1与maven-surefire-plugin:3.5.2务必小心运行任何会删除或修改 AWS 资源的操作。建议在实验时创建仅用于测试的独立资源避免影响生产环境。测试 Step Functions Java 示例测试方式与输出示例代码通过 JUnit 5 测试类StepFunctionsTest进行验证文件位于src/test/java目录即 StepFunctionsTest.java。可以在 IDE如 IntelliJ IDEA中运行也可以在命令行通过 Maven 的 surefire 插件运行。每个测试运行时会输出成功或失败信息例如Test 1 passedWARNING运行这些 JUnit 测试会操作真实的 AWS 资源可能产生账户费用。从测试源码可以看到其设计测试类标注TestInstance(TestInstance.Lifecycle.PER_METHOD)与TestMethodOrder(MethodOrderer.OrderAnnotation.class)按Order注解顺序执行。BeforeAll中创建SfnClient区域US_EAST_1并从 AWS Secrets Manager 读取test/stepfunctions密钥中的测试参数为角色名、活动名与状态机名追加UUID.randomUUID()后缀避免测试间资源命名冲突。目前包含两个集成测试testListActivities调用ListActivities.listAllActivites与TestHello调用ListStateMachines.listMachines均使用assertDoesNotThrow断言通过后打印Test N passed。Properties 文件config.properties运行 JUnit 测试前必须在resources文件夹下的config.properties文件中定义所需值未定义全部值时测试会失败。该文件位于 config.properties原始模板为jsonFile set jsonFile value jsonFileSM set jsonFileSM value roleARN set roleARN value stateMachineName set stateMachineName value结合 README 说明运行场景测试需要配置以下关键值属性说明roleNameSc为场景测试创建的 IAM 角色名称activityNameSc为场景测试创建的活动名称stateMachineNameSc为场景测试创建的状态机名称补充说明从 StepFunctionsTest.java 的实现看当前测试版本已支持从 AWS Secrets Manager 密钥test/stepfunctions读取测试参数roleNameSC、activityNameSC、stateMachineNameSC配置属性与 Secrets Manager 是两条可选的参数供给路径。状态机定义文件创建状态机所需的 ASL JSON 定义文件位于仓库的resources/sample_files目录。运行场景测试时需要将chat_sfn_state_machine.json放入项目的 resources 文件夹否则测试无法成功。该文件定义了 ChatSFN 工作流的状态结构其中GetInput状态的Resource字段在运行时被替换为动态创建的活动 ARN。日志配置项目资源目录下的 log4j2.xml 配置了 Log4j2 控制台输出定义ConsoleAppender%msg%n格式与AlignedConsoleAppender%m%n格式根 logger 级别为info关联到ConsoleAppender。测试中的Test N passed日志正是经由该日志链路打印到控制台。构建与运行建议以 Maven 为构建工具在javav2/example_code/stepfunctions目录下可执行以下典型操作具体以本机 Maven 配置为准编译mvn compile运行测试mvn test将触发 StepFunctionsTest需先完成凭据、config.properties 或 Secrets Manager 参数配置运行单个示例编译后通过java执行对应主类并传入所需参数例如创建状态机需提供jsonFile roleARN stateMachineName三个参数由于示例均使用默认凭据提供器运行前请确保通过环境变量、~/.aws/credentials或 IAM 角色等方式配置了具备 Step Functionsstates:*、IAM场景中创建角色与 Secrets Manager测试读取密钥权限的凭据。小结本指南完整覆盖了javav2/example_code/stepfunctions下 AWS Step Functions 的 Java SDK v2 示例从单动作的createStateMachine、startExecution、listExecutions、getExecutionHistory到多命令组合的 ChatSFN 场景并给出了环境配置、config.properties参数、JUnit 5 测试方法与 ASL 定义文件的使用要点。读者可以基于这些模式进一步扩展例如将 Activity 模式用于人工审批流将getExecutionHistory用于工作流审计或将状态机定义参数化以实现多环境复用。文中涉及的源码均位于 javav2/example_code/stepfunctions 目录示例版权归 Amazon.com, Inc. 或其关联公司所有代码遵循 Apache-2.0 许可SPDX-License-Identifier: Apache-2.0。赞分享示例工程教程后端【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples点击查看免费下载相关推荐AWS Step Functions Python SDK 示例解析与实战指南AWS Step Functions Python SDK 示例解析与实战指南 概述 AWS Step FunctionsAWS 步骤函数是一项强大的无服务示例工程教程后端AWS Step Functions 结合 AWS SDK for Java 2 构建 ETL 工作流完整实战解析aws-doc-sdk-examplesAWS Step Functions 结合 AWS SDK for Java 2 构建 ETL 工作流完整实战解析aws doc sdk examples示例工程教程后端如何把 VideoLingo 的语音转录切换到 ElevenLabs Speech to Text API如何把 VideoLingo 的语音转录切换到 ElevenLabs Speech to Text API VideoLingo 的语音转录默认走本地 Whi示例工程教程后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考