使用 AWS SDK for Java 2.x 操作 Amazon Connect：实例、联系人、队列与历史指标实战指南

发布时间：2026/9/25 5:25:21来源：尧图网络

示例工程教程后端【免费下载链接】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点击查看免费下载Amazon Connect 是 AWS 提供的全渠道云联络中心服务可以在几分钟内搭建联络中心、添加分布各地的客服坐席并与客户展开沟通。本指南围绕 javav2/example_code/connect 目录中的 11 个 Java 代码示例完整讲解如何基于 AWS SDK for Java 2.x 的ConnectClient完成实例创建与删除、实例/联系人信息查询、电话号码与用户列表、队列搜索以及历史指标数据获取等核心操作并配套介绍基于 JUnit 5 的集成测试运行方式与测试参数配置帮助你快速掌握 Amazon Connect 的 Java 编程实战。模块概览与前置准备本模块位于仓库 javav2/example_code/connect 目录采用标准 Maven 工程结构connect/ ├── pom.xml # Maven 构建配置 ├── README.md # 官方使用说明本文依据 └── src/ ├── main/ │ ├── java/com/example/connect/ # 11 个 Connect 操作示例 │ └── resources/config.properties # JUnit 测试所需配置 └── test/java/ConnectTest.java # JUnit 5 集成测试所有示例均基于ConnectClient对象完成 AWS 调用凭证提供方式为ProfileCredentialsProviderAWS SDK for Java 2.x 的标准凭证链之一详见官方 Using credentials 说明。运行代码前需完成 AWS SDK for Java 2.x 开发环境搭建可通过 Apache Maven 或 Gradle 配置构建具体参考官方 Get started with the AWS SDK for Java 2.x。重要提醒运行本模块代码会在你的 AWS 账户中产生费用运行测试同样可能产生费用。建议遵循最低权限原则Least privilege仅授予完成操作所需的最小权限。此外Amazon Connect 并非在所有 AWS 区域均可用需结合 AWS Regional Services 确认目标区域支持情况。Maven 依赖与构建配置pom.xml 声明了核心依赖与构建参数software.amazon.awssdk:bom:2.35.10通过 BOMBill of Materials统一管理 AWS SDK for Java 2.x 各模块版本避免版本冲突software.amazon.awssdk:connectAmazon Connect 服务客户端核心依赖提供ConnectClientsoftware.amazon.awssdk:secretsmanager测试用例通过 Secrets Manager 读取测试参数时使用software.amazon.awssdk:sso与software.amazon.awssdk:ssooidc支持 SSO/OIDC 凭证流程com.google.code.gson:gson:2.10.1测试类用 Gson 解析 Secrets Manager 返回的 JSONorg.junit.jupiter:junit-jupiter:5.11.4test 作用域JUnit 5 测试框架日志依赖log4j-core、log4j-bom:2.23.1、slf4j-api:2.0.13及 log4j-slf4j2 桥接等。构建插件方面maven-compiler-plugin配置了 Java 17 的编译源/目标版本properties中java.version为 21插件内source/target为 17maven-surefire-plugin:3.5.2用于运行 JUnit 测试。单操作示例Single action详解以下 11 个示例均通过ConnectClient调用对应 API每个类同时包含main方法命令行入口与可复用的静态业务方法。创建 Amazon Connect 实例CreateInstanceCreateInstance.java 演示createInstance命令命令行参数为instanceAlias实例名称public static String createConnectInstance(ConnectClient connectClient, String instanceAlias) { CreateInstanceRequest instanceRequest CreateInstanceRequest.builder() .identityManagementType(DirectoryType.CONNECT_MANAGED) .instanceAlias(instanceAlias) .inboundCallsEnabled(true) .outboundCallsEnabled(true) .build(); CreateInstanceResponse response connectClient.createInstance(instanceRequest); System.out.println(The instance ARN is response.arn()); return response.id(); }关键参数说明identityManagementType身份管理方式示例使用DirectoryType.CONNECT_MANAGEDConnect 托管的用户目录无需对接企业 AD 即可快速起步instanceAlias实例别名用于标识实例inboundCallsEnabled / outboundCallsEnabled分别控制是否允许呼入与呼出电话方法返回response.id()实例 ID并打印实例 ARN供后续 Delete、Describe 等操作使用。删除 Amazon Connect 实例DeleteInstanceDeleteInstance.java 演示deleteInstance命令命令行参数为instanceId。该方法属于破坏性操作会删除指定实例及其关联资源README 特别强调在真实账户中运行删除/修改类操作时务必谨慎建议创建独立的仅用于测试的资源来实验public static void deleteSpecificInstance(ConnectClient connectClient, String instanceId) { DeleteInstanceRequest instanceRequest DeleteInstanceRequest.builder() .instanceId(instanceId) .build(); connectClient.deleteInstance(instanceRequest); System.out.println(Instance was successfully deleted.); }描述指定联系人DescribeContactDescribeContact.java 演示describeContact命令命令行参数为instanceId与contactId联系人 ID形如16417918-7b38-470a-a9a2-bfcfa7cxxxxxDescribeContactRequest contactRequest DescribeContactRequest.builder() .contactId(contactId) .instanceId(instanceId) .build(); DescribeContactResponse response connectClient.describeContact(contactRequest); System.out.println(The queue info is response.contact().queueInfo().toString()); System.out.println(The queue id is response.contact().queueInfo().id()); System.out.println(The initiation method is response.contact().initiationMethod().toString());通过response.contact()可获得联系人详情包括其关联队列信息queueInfo与发起方式initiationMethod。描述指定实例DescribeInstanceDescribeInstance.java 演示describeInstance命令命令行参数为instanceId。该示例实现了状态轮询逻辑循环调用describeInstance直到实例状态变为ACTIVE才退出每次轮询间隔 1 秒while (!status) { DescribeInstanceResponse response connectClient.describeInstance(instanceRequest); String instanceStatus response.instance().instanceStatus().toString(); System.out.println(Status is instanceStatus); if (instanceStatus.compareTo(ACTIVE) 0) status true; Thread.sleep(1000); }这一模式在实例创建后需要等待其进入可用状态时非常实用可与 CreateInstance 组合使用。描述指定实例属性DescribeInstanceAttributeDescribeInstanceAttribute.java 演示describeInstanceAttribute命令命令行参数为instanceId查询的实例属性类型通过InstanceAttributeType枚举指定。示例查询USE_CUSTOM_TTS_VOICES是否启用自定义 TTS 语音属性DescribeInstanceAttributeRequest request DescribeInstanceAttributeRequest.builder() .instanceId(instanceId) .attributeType(InstanceAttributeType.USE_CUSTOM_TTS_VOICES) .build(); DescribeInstanceAttributeResponse response connectClient.describeInstanceAttribute(request); System.out.println(The attribute value is response.attribute().attributeType().toString());获取联系人属性GetContactAttributesGetContactAttributes.java 演示getContactAttributes命令命令行参数为instanceId与contactId。联系人属性以键值对MapString, String形式返回常用于获取联络流Contact Flow中设置的客户上下文数据GetContactAttributesRequest attributesRequest GetContactAttributesRequest.builder() .instanceId(instanceId) .initialContactId(contactId) .build(); GetContactAttributesResponse response connectClient.getContactAttributes(attributesRequest); MapString, String attributeMap response.attributes(); for (Map.EntryString, String entry : attributeMap.entrySet()) System.out.println(Key entry.getKey() , Value entry.getValue());注意请求参数使用initialContactId初始联系人 ID作为查询键。获取历史指标数据GetMetricDataGetMetricData.java 演示getMetricData命令命令行参数为instanceId与queueId。该示例展示了构建历史指标查询的完整流程定义阈值Threshold、指定指标HistoricalMetric、过滤条件Filters、时间区间以及分页上限// 1. 定义阈值处理时长 10 秒 Threshold threshold Threshold.builder() .comparison(Comparison.LT) .thresholdValue(10.0) .build(); // 2. 定义指标CONTACTS_HANDLED已处理联系人数量统计方式 SUM HistoricalMetric contactMetric HistoricalMetric.builder() .name(HistoricalMetricName.CONTACTS_HANDLED) .statistic(Statistic.SUM) .threshold(threshold) .unit(Unit.COUNT) .build(); // 3. 过滤条件限定语音渠道指定队列 Filters filter Filters.builder() .channels(Channel.VOICE) .queues(queueId) .build(); // 4. 时间区间解析 09:05:00 AM, Tue 01/03/2023 格式的起止时间 Instant startInstant LocalDateTime.parse(09:05:00 AM, Tue 01/03/2023, formatter).toInstant(ZoneOffset.UTC); Instant endInstant LocalDateTime.parse(10:05:00 AM, Tue 01/03/2023, formatter).toInstant(ZoneOffset.UTC); // 5. 组装请求并调用 GetMetricDataRequest dataRequest GetMetricDataRequest.builder() .instanceId(instanceId) .endTime(endInstant) .startTime(startInstant) .filters(filter) .maxResults(10) .historicalMetrics(contactMetric) .build(); GetMetricDataResponse response connectClient.getMetricData(dataRequest);时间字符串解析采用hh:mm:ss a, EEE M/d/uuuu模式如09:05:00 AM, Tue 01/03/2023转换为 UTC 时间戳后传给请求。返回结果response.metricResults()为HistoricalMetricResult列表每个结果包含collections()指标数据集合可进一步读取metric().statistic().name()等统计信息。列出 Amazon Connect 实例ListInstancesListInstances.java 演示listInstances命令无需命令行参数。通过ListInstancesRequest设置maxResults(10)后调用遍历instanceSummaryList()打印每个实例的 ID、别名与 ARNListInstancesResponse response connectClient.listInstances(instancesRequest); ListInstanceSummary instances response.instanceSummaryList(); for (InstanceSummary instance : instances) { System.out.println(The identifier of the instance is instance.id()); System.out.println(The instance alias of the instance is instance.instanceAlias()); System.out.println(The ARN of the instance is instance.arn()); }列出实例电话号码ListPhoneNumbersListPhoneNumbers.java 演示listPhoneNumbersV2命令命令行参数为targetArn实例 ARN。示例按PhoneNumberType.TOLL_FREE免费电话号码类型过滤并设置maxResults(10)ListPhoneNumbersV2Request numbersV2Request ListPhoneNumbersV2Request.builder() .maxResults(10) .phoneNumberTypes(PhoneNumberType.TOLL_FREE) .targetArn(targetArn) .build(); ListPhoneNumbersV2Response response connectClient.listPhoneNumbersV2(numbersV2Request); for (ListPhoneNumbersSummary num : response.listPhoneNumbersSummaryList()) { System.out.println(Phone number is num.phoneNumber()); System.out.println(Country code is num.phoneNumberCountryCode().toString()); }列出实例用户ListUsersListUsers.java 演示listUsers命令命令行参数为instanceId。通过ListUsersRequest指定实例与maxResults(10)遍历userSummaryList()输出用户名与用户 IDListUsersRequest usersRequest ListUsersRequest.builder() .instanceId(instanceId) .maxResults(10) .build(); ListUsersResponse response connectClient.listUsers(usersRequest); for (UserSummary user : response.userSummaryList()) { System.out.println(The user name of the user is user.username()); System.out.println(The user id is user.id()); }搜索实例中的队列SearchQueuesSearchQueues.java 演示searchQueues命令命令行参数为instanceId。通过SearchQueuesRequest设置实例与maxResults(10)遍历response.queues()输出队列名称、描述、ID 与 ARNSearchQueuesResponse response connectClient.searchQueues(queuesRequest); for (Queue queue : response.queues()) { System.out.println(The queue name is queue.name()); System.out.println(The queue description is queue.description()); System.out.println(The queue id is queue.queueId()); System.out.println(The queue ARN is queue.queueArn()); }示例运行方式所有示例均可直接通过main方法运行运行时传入对应命令行参数各示例的main方法内含usage提示参数缺失时会打印用法并退出。从源码结构看所有示例统一采用Region region Region.US_EAST_1; // CreateInstance 使用 US_WEST_2 ConnectClient connectClient ConnectClient.builder() .region(region) .build();其中 CreateInstance 使用Region.US_WEST_2其余示例使用Region.US_EAST_1。命令行运行示例以 Maven 为例mvn compile mvn exec:java -Dexec.mainClasscom.example.connect.ListInstances mvn exec:java -Dexec.mainClasscom.example.connect.CreateInstance -Dexec.argsmy-instance-alias使用 JUnit 5 进行集成测试测试结构与运行方式测试文件为 ConnectTest.java位于src/test/java目录基于 JUnit 5junit-jupiter编写。测试类使用TestMethodOrder(MethodOrderer.OrderAnnotation.class)结合Order注解控制执行顺序并用Tag(IntegrationTest)标记为集成测试。测试方法按顺序覆盖testCreateInstance调用CreateInstance.createConnectInstance创建实例断言返回的实例 ID 非空testDescribeInstance调用DescribeInstance.describeSpecificInstance描述刚创建的实例testListInstances调用ListInstances.listAllInstances列出全部实例testDeleteInstance调用DeleteInstance.deleteSpecificInstance删除测试实例先建后删自包含清理testListPhoneNumbers调用ListPhoneNumbers.getPhoneNumbers使用targetArn参数查询电话号码其余类DescribeContact、DescribeInstanceAttribute、GetContactAttributes、GetMetricData、ListUsers、SearchQueues同样有对应入口方法可在测试中按需扩展调用。每个测试通过后会在日志中输出类似Test N passed的信息如Test 3 passed。测试可从 IntelliJ 等 Java IDE 直接运行也可在命令行使用 Maven 执行mvn test⚠️ 警告这些 JUnit 测试会操作真实的 Amazon 资源真实创建/删除 Connect 实例运行会产生账户费用。测试前必须先在 config.properties 中定义全部所需参数若未定义完整测试将失败。测试参数来源Properties 文件与 Secrets ManagerREADME 明确要求先在src/main/resources目录下的config.properties文件中定义测试所需值该文件包含 4 个必填项参数说明示例instanceAliasAmazon Connect 实例名称my-connect-instancecontactId联系人 ID16417918-7b38-470a-a9a2-bfcfa7cxxxxxexistingInstanceId已有 Amazon Connect 实例的 IDc13bb6fa-3cf4-45a2-a93e-ebeaf7xxxxxxtargetArnAmazon Connect 实例的 ARNAmazon Resource Namearn:aws:connect:us-east-1:123456789012:instance/xxx仓库中 config.properties 的默认内容为占位符形式需替换为真实值instanceAlias enter value contactId enter value existingInstanceId enter value targetArn enter value从测试源码 ConnectTest.java 可以看到测试参数实际从AWS Secrets Manager读取而不是直接读取本地 properties 文件setUp()方法使用SecretsManagerClient读取名为test/connect的 secret通过 Gson 反序列化为内部类SecretValues再取得instanceAlias、contactId、existingInstanceId、targetArn四个字段。其中instanceAlias还会拼接一个 1~1000 的随机数new Random().nextInt(1000) 1以生成唯一实例别名避免重名冲突int randomValue new Random().nextInt(1000) 1; String json getSecretValues(); SecretValues values gson.fromJson(json, SecretValues.class); instanceAlias values.getInstanceAlias() randomValue; contactId values.getContactId(); existingInstanceId values.getExistingInstanceId(); targetArn values.getTargetArn();也就是说实际测试运行时优先以 Secrets Manager 中test/connect密钥的 JSON 结构为参数来源其字段结构与 config.properties 完全对应。两种方式README 描述的 config.properties 与源码实现的 Secrets Manager均可用于准备测试参数具体取决于你的运行环境与配置方式。测试客户端初始化测试中的ConnectClient使用Region.US_EAST_1构建与SecretsManagerClient使用相同区域connectClient ConnectClient.builder() .region(Region.US_EAST_1) .build();ConnectTest中还引入了EnvironmentVariableCredentialsProvider说明测试环境支持通过环境变量提供 AWS 凭证。典型组合流程从创建到删除一个实例结合以上示例可以串起一条完整的实例生命周期操作链路使用CreateInstance.createConnectInstance创建实例获得instanceId使用DescribeInstance.describeSpecificInstance轮询等待实例状态变为ACTIVE使用ListInstances.listAllInstances确认实例出现在实例列表中使用ListPhoneNumbers.getPhoneNumbers传入targetArn、ListUsers.getUsers、SearchQueues.searchQueue查看实例下的号码、用户与队列实验结束后使用DeleteInstance.deleteSpecificInstance删除实例避免资源持续计费。ConnectTest的测试顺序Test 1 创建 → Test 4 删除即为这一链路的最小闭环验证。常见注意事项区域差异README 明确指出本模块代码未在所有 AWS 区域经过测试。示例代码中 CreateInstance 使用US_WEST_2其余示例使用US_EAST_1在自有账户运行时需确认目标区域已开通 Amazon Connect 服务破坏性操作DeleteInstance会删除整个 Connect 实例及其关联资源务必对测试专用资源操作切勿指向生产实例费用提醒运行示例与 JUnit 测试均会真实调用 AWS API 并产生费用建议结合 AWS 计费页面AWS Pricing评估成本最低权限建议为运行示例/测试的 IAM 身份仅授予 Amazon Connect 相关操作的最小权限集合测试参数完整性无论采用 config.properties 还是 Secrets Manager 方式instanceAlias、contactId、existingInstanceId、targetArn四项缺一不可否则 JUnit 测试将因缺少参数而失败。延伸资源AWS SDK for Java 2.x 开发者指南快速入门与环境配置Get started with the AWS SDK for Java 2.xAmazon Connect 管理员指南了解联络中心的概念、联络流与运营管理Amazon Connect Administrator GuideConnectClient接口 API 参考Interface ConnectClient本模块完整源码javav2/example_code/connect含 11 个示例类、pom.xml、config.properties 与 ConnectTest.java 集成测试。版权声明本模块代码遵循 Apache-2.0 许可证SPDX-License-Identifier: Apache-2.0Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.赞分享示例工程教程后端【免费下载链接】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 Java 2.x 操作 Amazon S3 完全指南AWS SDK for Java 2.x 操作 Amazon S3 完全指南概述 Amazon Simple Storage Service Amazon S示例工程教程后端aws-doc-sdk-examples使用 AWS SDK for Java 2.x 操作 Amazon Timestream 的完整示例与测试指南aws doc sdk examples使用 AWS SDK for Java 2.x 操作 Amazon Timestream 的完整示例与测试指南 Ama示例工程教程后端AWS SDK for Java 2.x 操作 Amazon S3 实战指南基于 aws-doc-sdk-examples 官方示例仓库AWS SDK for Java 2.x 操作 Amazon S3 实战指南基于 aws doc sdk examples 官方示例仓库本篇以 aws do示例工程教程后端上一篇DynSLAM动态环境下的同时定位与映射开源项目下一篇tiny-random-PhiForCausalLM-openmind完整指南5步掌握NPU硬件上的AI模型推理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

网站建设高端定制企业官网