企业官网建设流程全解析

• 示例工程
• 教程
• 后端

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 调用，凭证提供方式为ProfileCredentialsProvider（AWS 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：通过 BOM（Bill of Materials）统一管理 AWS SDK for Java 2.x 各模块版本，避免版本冲突；
• software.amazon.awssdk:connect：Amazon Connect 服务客户端核心依赖，提供ConnectClient；
• software.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 返回的 JSON；
• org.junit.jupiter:junit-jupiter:5.11.4（test 作用域）：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为 17），maven-surefire-plugin:3.5.2用于运行 JUnit 测试。

单操作示例（Single action）详解

以下 11 个示例均通过ConnectClient调用对应 API，每个类同时包含main方法（命令行入口）与可复用的静态业务方法。

创建 Amazon Connect 实例（CreateInstance）

CreateInstance.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_MANAGED（Connect 托管的用户目录，无需对接企业 AD 即可快速起步）；
• instanceAlias：实例别名，用于标识实例；
• inboundCallsEnabled / outboundCallsEnabled：分别控制是否允许呼入与呼出电话；
• 方法返回response.id()（实例 ID），并打印实例 ARN，供后续 Delete、Describe 等操作使用。

删除 Amazon Connect 实例（DeleteInstance）

DeleteInstance.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."); }

描述指定联系人（DescribeContact）

DescribeContact.java 演示describeContact命令，命令行参数为instanceId与contactId（联系人 ID，形如16417918-7b38-470a-a9a2-bfcfa7cxxxxx）：

DescribeContactRequest 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）。

描述指定实例（DescribeInstance）

DescribeInstance.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 组合使用。

描述指定实例属性（DescribeInstanceAttribute）

DescribeInstanceAttribute.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());

获取联系人属性（GetContactAttributes）

GetContactAttributes.java 演示getContactAttributes命令，命令行参数为instanceId与contactId。联系人属性以键值对（Map<String, String>）形式返回，常用于获取联络流（Contact Flow）中设置的客户上下文数据：

GetContactAttributesRequest attributesRequest = GetContactAttributesRequest.builder() .instanceId(instanceId) .initialContactId(contactId) .build(); GetContactAttributesResponse response = connectClient.getContactAttributes(attributesRequest); Map<String, String> attributeMap = response.attributes(); for (Map.Entry<String, String> entry : attributeMap.entrySet()) System.out.println("Key = " + entry.getKey() + ", Value = " + entry.getValue());

注意：请求参数使用initialContactId（初始联系人 ID）作为查询键。

获取历史指标数据（GetMetricData）

GetMetricData.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 实例（ListInstances）

ListInstances.java 演示listInstances命令，无需命令行参数。通过ListInstancesRequest设置maxResults(10)后调用，遍历instanceSummaryList()打印每个实例的 ID、别名与 ARN：

ListInstancesResponse response = connectClient.listInstances(instancesRequest); List<InstanceSummary> 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()); }

列出实例电话号码（ListPhoneNumbers）

ListPhoneNumbers.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()); }

列出实例用户（ListUsers）

ListUsers.java 演示listUsers命令，命令行参数为instanceId。通过ListUsersRequest指定实例与maxResults(10)，遍历userSummaryList()输出用户名与用户 ID：

ListUsersRequest 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()); }

搜索实例中的队列（SearchQueues）

SearchQueues.java 演示searchQueues命令，命令行参数为instanceId。通过SearchQueuesRequest设置实例与maxResults(10)，遍历response.queues()输出队列名称、描述、ID 与 ARN：

SearchQueuesResponse 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.mainClass=com.example.connect.ListInstances mvn exec:java -Dexec.mainClass=com.example.connect.CreateInstance -Dexec.args="my-instance-alias"

使用 JUnit 5 进行集成测试

测试结构与运行方式

测试文件为 ConnectTest.java，位于src/test/java目录，基于 JUnit 5（junit-jupiter）编写。测试类使用@TestMethodOrder(MethodOrderer.OrderAnnotation.class)结合@Order注解控制执行顺序，并用@Tag("IntegrationTest")标记为集成测试。测试方法按顺序覆盖：

1. testCreateInstance：调用CreateInstance.createConnectInstance创建实例，断言返回的实例 ID 非空；
2. testDescribeInstance：调用DescribeInstance.describeSpecificInstance描述刚创建的实例；
3. testListInstances：调用ListInstances.listAllInstances列出全部实例；
4. testDeleteInstance：调用DeleteInstance.deleteSpecificInstance删除测试实例（先建后删，自包含清理）；
5. testListPhoneNumbers：调用ListPhoneNumbers.getPhoneNumbers，使用targetArn参数查询电话号码；
6. 其余类（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 Manager

README 明确要求先在src/main/resources目录下的config.properties文件中定义测试所需值，该文件包含 4 个必填项：

仓库中 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 凭证。

典型组合流程：从创建到删除一个实例

结合以上示例，可以串起一条完整的实例生命周期操作链路：

1. 使用CreateInstance.createConnectInstance创建实例，获得instanceId；
2. 使用DescribeInstance.describeSpecificInstance轮询等待实例状态变为ACTIVE；
3. 使用ListInstances.listAllInstances确认实例出现在实例列表中；
4. 使用ListPhoneNumbers.getPhoneNumbers（传入targetArn）、ListUsers.getUsers、SearchQueues.searchQueue查看实例下的号码、用户与队列；
5. 实验结束后使用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.x）；
• Amazon Connect 管理员指南：了解联络中心的概念、联络流与运营管理（Amazon Connect Administrator Guide）；
• ConnectClient接口 API 参考：Interface ConnectClient；
• 本模块完整源码：javav2/example_code/connect（含 11 个示例类、pom.xml、config.properties 与 ConnectTest.java 集成测试）。

版权声明：本模块代码遵循 Apache-2.0 许可证（SPDX-License-Identifier: Apache-2.0），Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

• 示例工程
• 教程
• 后端