使用 AWS SDK for Kotlin 操作 AWS Step Functions：示例场景与实战指南

示例工程教程后端【免费下载链接】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-doc-sdk-examples 中kotlin/services/stepfunctions目录的官方示例系统讲解如何用 AWS SDK for Kotlin 调用 AWS Step Functions 的完整操作集从列出状态机Hello 入门、创建/删除活动与状态机、描述执行、获取执行历史、筛选失败执行到结合 IAM 角色、活动任务轮询与sendTaskSuccess回调的端到端聊天模拟器场景。读完本文你将掌握 Step Functions 在 Kotlin 中的客户端初始化方式、分页器Paginator用法、状态机定义文件的动态注入技巧以及 JUnit 5 自动化测试的配置方法可直接运行仓库中的全部示例。Step Functions 与 SDK for Kotlin 示例概览AWS Step Functions 是一个可视化工作流服务帮助开发者使用 AWS 服务构建分布式应用、自动化流程、编排微服务并创建数据处理和机器学习ML管道。本仓库的 Kotlin 示例正是围绕这一核心能力展开官方 READMEkotlin/services/stepfunctions/README.md将其组织为三个层次Get started入门HelloStepFunctions.kt演示listStateMachines命令Single action单动作每个代码片段只调用一个服务函数覆盖createActivity、createStateMachine、deleteActivity、deleteStateMachine、describeExecution、describeStateMachine、getActivityTask、getExecutionHistory、listExecutions、sendTaskSuccess、startExecution共 11 个 APIScenarios场景StepFunctionsScenario.kt通过在同一服务内调用多个函数完成完整任务。所有示例统一使用SfnClient它是 SDK for Kotlin 提供的 Step Functions 服务客户端。源码中可以看到其标准初始化模式如 HelloStepFunctions.ktSfnClient.fromEnvironment { region us-east-1 }.use { sfnClient - // 调用 Step Functions API }fromEnvironment表示从环境变量AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGION等加载凭证与配置use块保证客户端在使用后自动释放底层资源。示例默认使用us-east-1区域运行前请结合 AWS Regional Services 确认该服务在你所在区域可用。Hello 入门列出状态机HelloStepFunctions.kt 是最简示例核心逻辑如下suspend fun listMachines() { SfnClient.fromEnvironment { region us-east-1 }.use { sfnClient - val response sfnClient.listStateMachines(ListStateMachinesRequest {}) response.stateMachines?.forEach { machine - println(The name of the state machine is ${machine.name}) println(The ARN value is ${machine.stateMachineArn}) } } }该示例无命令行参数直接运行即可列出账户中最多十个状态机的名称与 ARN。注意函数是suspend的SDK for Kotlin 的 API 基于 Kotlin 协程实现调用方必须在协程作用域内执行仓库测试中即用runBlocking包裹。单动作示例源码剖析列出活动ListActivities.ktListActivities.kt 使用listActivities接口并设置maxResults 10suspend fun listAllActivites() { val activitiesRequest ListActivitiesRequest { maxResults 10 } SfnClient.fromEnvironment { region us-east-1 }.use { sfnClient - val response sfnClient.listActivities(activitiesRequest) response.activities?.forEach { item - println(The activity ARN is ${item.activityArn}) println(The activity name is ${item.name}) } } }获取执行历史GetExecutionHistory.ktGetExecutionHistory.kt 接收一个执行 ARN 作为命令行参数调用getExecutionHistory拉取执行事件并打印事件类型suspend fun getExeHistory(exeARN: String?) { val historyRequest GetExecutionHistoryRequest { executionArn exeARN maxResults 10 } SfnClient.fromEnvironment { region us-east-1 }.use { sfnClient - val response sfnClient.getExecutionHistory(historyRequest) response.events?.forEach { event - println(The event type is ${event.type}) } } }运行方式GetExecutionHistoryKt exeARN其中exeARN是某次执行的 ARN可从startExecution的返回值获得。筛选失败执行GetFailedExecutions.ktGetFailedExecutions.kt 演示listExecutions与状态过滤的组合通过statusFilter ExecutionStatus.Failed只返回失败的执行记录suspend fun getFailedExes(stateMachineARN: String?) { val executionsRequest ListExecutionsRequest { maxResults 10 stateMachineArn stateMachineARN statusFilter ExecutionStatus.Failed } SfnClient.fromEnvironment { region us-east-1 }.use { sfnClient - val response sfnClient.listExecutions(executionsRequest) response.executions?.forEach { item - println(The Amazon Resource Name (ARN) of the failed execution is ${item.executionArn}.) } } }运行方式GetFailedExecutionsKt stateMachineARNstateMachineARN即状态机的 ARN。这个示例很适合作为工作流失败监控的起点statusFilter还可替换为Running、Succeeded、TimedOut、Aborted等枚举值。核心场景StepFunctionsScenario 端到端实战StepFunctionsScenario.kt 是仓库中最完整的示例源码注释明确列出 9 个步骤覆盖创建 → 交互 → 清理全生命周期使用分页器Paginator列出活动使用分页器列出状态机创建一个活动Activity创建一个状态机描述该状态机启动状态机执行并与之交互描述执行状态删除活动删除状态机。运行参数该场景运行时需要 4 个命令行参数参数含义roleName为状态机创建的 IAM 角色名称activityName要创建的活动名称stateMachineName要创建的状态机名称jsonFilechat_sfn_state_machine.json文件的本地路径动态注入活动 ARN 到状态机定义场景的核心技巧是用 Jackson 读取 chat_sfn_state_machine.json再把GetInput状态中的Resource字段替换为刚创建的活动的 ARN从而让状态机把等待人类输入这一任务回调给该活动// 读取 JSON 定义文件 val stream GetStream() val jsonString stream.getStream(jsonFile) // 将 Resource 节点替换为 activityArn val objectMapper ObjectMapper() val root: JsonNode objectMapper.readTree(jsonString) (root.path(States).path(GetInput) as ObjectNode).put(Resource, activityArn) val stateDefinition objectMapper.writeValueAsString(root)GetStream.kt 负责把本地 JSON 文件读入并序列化为字符串供后续createStateMachine使用。仓库模板文件 chat_sfn_state_machine.json 中的GetInput状态原本的Resource是占位符{{DOC_EXAMPLE_ACTIVITY_ARN}}其TimeoutSeconds设为 300表示活动必须在 300 秒内回调否则任务超时。创建 IAM 角色状态机需要执行角色execution role场景代码用IamClient创建信任策略允许states.amazonaws.com服务代入该角色即sts:AssumeRoleval polJSON { Version: 2012-10-17, Statement: [ { Sid: , Effect: Allow, Principal: { Service: states.amazonaws.com }, Action: sts:AssumeRole } ] } suspend fun createIAMRole(roleNameVal: String?, polJSON: String?): String? { val request CreateRoleRequest { roleName roleNameVal assumeRolePolicyDocument polJSON description Created using the AWS SDK for Kotlin } IamClient.fromEnvironment { region AWS_GLOBAL }.use { iamClient - val response iamClient.createRole(request) return response.role?.arn } }注意 IAM 是全局服务此处区域使用AWS_GLOBAL与 Step Functions 的us-east-1不同。务必按最小权限原则示例仅创建角色本身生产环境还应为其附加恰好满足状态机所需操作的权限策略。创建活动与状态机// 创建活动 suspend fun createActivity(activityName: String): String? { val activityRequest CreateActivityRequest { name activityName } SfnClient.fromEnvironment { region us-east-1 }.use { sfnClient - val response sfnClient.createActivity(activityRequest) return response.activityArn } } // 创建标准类型状态机 suspend fun createMachine(roleARNVal: String?, stateMachineName: String?, jsonVal: String?): String? { val machineRequest CreateStateMachineRequest { definition jsonVal name stateMachineName roleArn roleARNVal type StateMachineType.Standard } ... }type StateMachineType.Standard表示标准工作流适合有状态、需人工介入或长时间运行的流程如需高吞吐、短时执行可改用StateMachineType.Express。启动执行与活动任务轮询这是整个场景最核心的交互部分先用startExecution携带 JSON 输入启动工作流再循环调用getActivityTask轮询活动任务读取状态机下发的消息后由用户在控制台输入回复最后用sendTaskSuccess把用户输入回传给 Step Functionsval runArn startWorkflow(stateMachineArn, executionJson) while (!action) { myList getActivityTask(activityArn) // 1. 获取活动任务token 输入 println(ChatSFN: myList[1]) // 2. 打印状态机发来的消息 val myAction sc.nextLine() // 3. 等待用户输入 if (myAction.compareTo(done) 0) action true val taskJson { \action\ : \$myAction\ } sendTaskSuccess(myList[0], taskJson) // 4. 回调 SendTaskSuccess }其中startWorkflow使用UUID.randomUUID()生成执行名保证并发执行不冲突getActivityTask返回ListString元素 0 是taskToken后续回调必须携带的令牌元素 1 是活动输入 JSON。对照 chat_sfn_state_machine.json 的定义可理解完整闭环Greeting状态用States.Format拼出问候语 →GetInput任务等待活动回调 →Choice根据$.action分发到 Song/Poem/Story/Done 四个分支 → 非 Done 分支再次回到GetInput形成对话循环用户输入done后进入结束状态。这套Activity SendTaskSuccess模式是 Step Functions 实现人工审批、外部系统回调的标准做法。描述与轮询执行状态describeStateMachine打印状态机名称、状态、ARN 与角色 ARNdescribeExe则轮询describeExecution每 2 秒检查一次直到执行状态从Running变为Succeededwhile (!hasSucceeded) { val response sfnClient.describeExecution(executionRequest) status response.status.toString() if (status.compareTo(Running) 0) { println(The state machine is still running, lets wait for it to finish.) Thread.sleep(2000) } else if (status.compareTo(Succeeded) 0) { println(The Step Function workflow has succeeded) hasSucceeded true } else { println(The Status is $status) } }清理资源场景结尾依次调用deleteActivity(activityArn)与deleteMachine(stateMachineArn)删除活动与状态机避免遗留资源持续计费。README 特别提醒运行删除/修改 AWS 资源的操作时要格外小心建议使用独立的测试专用资源进行实验。分页器Paginator的协程流用法场景前两步展示了 SDK for Kotlin 的分页器能力——通过listActivitiesPaginated/listStateMachinesPaginated配合kotlinx.coroutines.flow.transform自动翻页并流式处理结果suspend fun listStatemachinesPagnator() { val machineRequest ListStateMachinesRequest { maxResults 10 } SfnClient.fromEnvironment { region us-east-1 }.use { sfnClient - sfnClient.listStateMachinesPaginated(machineRequest) .transform { it.stateMachines?.forEach { obj - emit(obj) } } .collect { obj - println( The state machine ARN is ${obj.stateMachineArn}) } } }相比手动循环调用listStateMachines并处理nextToken分页器把分页逻辑封装进Flow代码更简洁且天然适配 Kotlin 协程。这与 HelloStepFunctions.kt 中的非分页版本形成了基础 API 与高级 API的对照学习材料。构建配置与运行环境示例项目的构建配置见 build.gradle.kts要点如下Kotlin JVM 插件版本 2.1.0Java 兼容级别 17sourceCompatibility/targetCompatibility均为VERSION_17jvmTarget 17通过BOMaws.sdk.kotlin:bom:1.5.63统一管理 AWS SDK for Kotlin 版本无需为各服务模块单独指定版本依赖模块包括sfnStep Functions、iam、secretsmanager测试读取密钥、OkHttp/CRT HTTP 引擎、JacksonJSON 解析、Gson、kotlinx-coroutines-core、SLF4J 日志测试框架为JUnit Jupiter 5.9.2并集成ktlint-gradle插件做代码风格检查测试任务通过useJUnitPlatform()启用 JUnit Platform。运行前需先按 AWS SDK for Kotlin 开发者指南 完成开发环境与凭证配置AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGION或~/.aws/credentials。运行这些代码可能对您的 AWS 账户产生费用详见 AWS Pricing。JUnit 5 自动化测试StepFunctionsKotlinTest仓库提供测试文件 StepFunctionsKotlinTest.kt基于 JUnit 5 编写可从 IntelliJ 等 IDE 或命令行运行。每跑完一个用例会输出类似Test 1 passed的信息⚠️ 运行这些测试会操作真实 AWS 资源可能产生账户费用。配置属性README 说明运行测试前必须在resources文件夹下的config.properties文件中定义以下值否则测试失败属性含义roleNameSc场景测试要创建的 IAM 角色名称activityNameSc场景测试要创建的活动名称stateMachineNameSc场景测试要创建的状态机名称仓库中的 config.properties 实际列出的键更完整包括jsonFile、jsonFileSM、roleARN、stateMachineName以及上述三个*Sc键均需按实际环境填入。状态机定义文件测试状态机使用 chat_sfn_state_machine.json。按 README 要求需将该项目文件放入你工程即kotlin/services/stepfunctions的resources文件夹中若缺失场景测试将失败。当前测试实现从 Secrets Manager 读取值得注意仓库当前的测试实现StepFunctionsKotlinTest.kt已升级为从 AWS Secrets Manager 读取配置BeforeAll阶段从名为test/stepfunctions的密钥中取 JSON解析出roleNameSC、activityNameSC、stateMachineNameSC与machineFile四个字段并在角色名、活动名、状态机名后追加UUID.randomUUID()以保证测试隔离BeforeAll fun setup() runBlocking { val gson Gson() val json: String getSecretValues() // 从 test/stepfunctions 密钥读取 val values gson.fromJson(json, SecretValues::class.java) roleNameSC values.roleNameSC.toString() UUID.randomUUID() activityNameSC values.activityNameSC.toString() UUID.randomUUID() stateMachineNameSC values.stateMachineNameSC.toString() UUID.randomUUID() jsonFile values.machineFile.toString() }getSecretValues()通过SecretsManagerClient { region us-east-1 }调用getSecretValue读取密钥内容。因此实际跑测试前需要预先在 Secrets Manager 中创建test/stepfunctions密钥并填入上述字段对应仓库中 build.gradle.kts 对secretsmanager模块的依赖。测试用例 1 直接调用场景中的listMachines()函数验证 Hello 逻辑这是源码层面 README 与实现之间最直观的印证。总结与使用建议将 README 与仓库源码对照可得出以下实践要点从 Hello 到场景循序渐进先用 HelloStepFunctions.kt 验证凭证与连通性再通过 ListActivities.kt、GetExecutionHistory.kt、GetFailedExecutions.kt 熟悉单 API最后深入 StepFunctionsScenario.kt 掌握活动回调模式善用分页器与协程列表类 API 优先使用*Paginated变体配合Flow的transform/collect处理大数据量结果状态机定义可编程注入用 Jackson 在运行时替换Resource、参数等节点是构建通用工作流引擎的常见手段权限最小化IAM 角色遵循 least privilege 原则只为状态机授予完成任务所需的最小权限集清理示例务必执行删除步骤测试配置二选一按 README 用config.properties或按当前实现预置 Secrets Manager 密钥test/stepfunctions并在测试环境使用独立资源以避免污染生产账户。所有源码均位于kotlin/services/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 SDK for Kotlin 操作 AWS IoT Core场景化示例代码全解析使用 AWS SDK for Kotlin 操作 AWS IoT Core场景化示例代码全解析 导读 本文基于 AWS 官方代码示例仓库中 kotlin/se示例工程教程后端使用 AWS SDK for Kotlin 操作 Amazon EventBridge从基础示例到完整场景实战使用 AWS SDK for Kotlin 操作 Amazon EventBridge从基础示例到完整场景实战 Amazon EventBridge 是 AW示例工程教程后端使用 AWS SDK for Kotlin 操作 Amazon EC2 Auto Scaling完整场景示例与测试指南使用 AWS SDK for Kotlin 操作 Amazon EC2 Auto Scaling完整场景示例与测试指南 导读 本文基于 aws doc sdk示例工程教程后端上一篇vxrn中的日志管理追踪React Native应用中的问题下一篇GitHub_Trending/gr/grok伦理考量算法泛化研究中的社会责任探讨创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考