示例工程教程后端【免费下载链接】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 仓库中javav2/example_code/opensearch模块系统讲解如何使用 AWS SDK for Java 2.x 的异步客户端完成 Amazon OpenSearch Service 领域的核心管理操作创建/删除/查询/更新域Domain、轮询变更进度、管理标签以及如何运行配套的场景程序与 JUnit 5 集成测试。读完本文你可以直接复用仓库中的 Maven 工程结构与代码片段在自己的项目中接入 OpenSearch 域管理逻辑。一、模块定位管理“域”而不是管理“文档”Amazon OpenSearch 是一套分布式、社区驱动、采用 Apache 2.0 许可的开源搜索与分析套件广泛用于实时应用监控、日志分析和网站搜索等场景。本模块的 READMEjavav2/example_code/opensearch/README.md开篇即说明这些示例展示如何用 AWS SDK for Java 2.x 与 Amazon OpenSearch Service 交互。需要特别明确一个边界场景程序入口 中的启动说明也强调了这一点OpenSearch Service 客户端暴露的 API 聚焦于管理 OpenSearch 域及其配置创建、查询、变更、标签而不是管理域内的数据如索引文档、查询文档。文档级操作通常需要直接对接 OpenSearch REST API或使用 OpenSearch 官方 Java 客户端。也就是说本模块对应的是 OpenSearch Service 的**控制面control plane**操作这决定了全部示例都围绕Domain这一核心资源展开。模块整体由四类文件组成文件作用HelloOpenSearch.java入门示例用ListVersions列出 OpenSearch 支持的引擎版本OpenSearchActions.java八大“单一操作”Single actions实现全部基于CompletableFutureOpenSearchScenario.java端到端场景程序按 9 个步骤走完整域生命周期OpenSearchTest.javaJUnit 5 集成测试按Order顺序驱动真实资源pom.xmlMaven 工程定义锁定 SDK BOM 版本与依赖二、前置条件与运行前提模块 README 将前置条件指向 javav2 总 README归纳如下构建工具需要 Apache Maven 3.0每个服务示例目录自带pom.xml。Java 版本从 pom.xml 可以看到本模块声明java.version为21maven.compiler.source/target同步设为 21因此本机 JDK 需为 21 或更高。AWS 凭据所有 Java v2 示例假设 SDK 通过默认凭据提供者链获取凭据即 AWS 共享配置文件中已配置好 default profileIAM Identity Center SSO 或临时凭据均可。默认 Region若未在 default profile 中指定 RegionSDK 默认使用us-east-1。注意本模块的场景类中客户端是显式固定了区域的见下文第四节。README 中还有三点必须重视的注意事项原样继承运行代码可能产生费用本示例会真实创建 OpenSearch 域含 5 个数据节点 3 个专用主节点运行场景程序或测试都可能在你的 AWS 账户产生账单最小权限原则建议只授予完成任务所需的最小 IAM 权限区域可用性这些代码并非在每一个 AWS Region 都经过测试运行前请确认所在区域是否提供 OpenSearch Service。三、Maven 工程与依赖版本OpenSearch 模块的 pom.xml 展示了该仓库典型的 SDK 2.x 依赖组织方式关键内容如下SDK BOM 统一版本管理pom.xml#L33-L49通过dependencyManagement导入software.amazon.awssdk:bom:2.35.10与log4j-bom:2.23.1各依赖不再单独写版本号服务客户端software.amazon.awssdk:opensearchpom.xml#L64-L66非阻塞 HTTP 客户端netty-nio-clientpom.xml#L67-L70这是异步客户端*AsyncClient的底层依赖同步客户端不需要它SSO 支持sso与ssooidcpom.xml#L71-L78用于凭据链中通过 IAM Identity Center 换取临时凭据日志slf4j-apilog4j-slf4j2-impl示例中统一用LoggerFactory打日志测试junit-jupiter 5.11.4test scope构建插件maven-compiler-pluginJava 21与maven-surefire-plugin 3.5.2。从源码结构看该 pom 未配置maven-shade-plugin因此直接java -cp target/xxx.jar运行前需要先按 javav2 总 README 的说明补充 shade 配置或使用 IDE 运行。四、Hello OpenSearch用 ListVersions 验证环境连通性HelloOpenSearch.java 是最小可运行入口演示了异步客户端的“构建—调用—消费”三步套路public class HelloOpenSearch { public static void main(String[] args) { try { CompletableFutureVoid future listVersionsAsync(); future.join(); System.out.println(Versions listed successfully.); } catch (RuntimeException e) { System.err.println(Error occurred while listing versions: e.getMessage()); } } private static OpenSearchAsyncClient getAsyncClient() { return OpenSearchAsyncClient.builder().build(); } public static CompletableFutureVoid listVersionsAsync() { ListVersionsRequest request ListVersionsRequest.builder() .maxResults(10) .build(); return getAsyncClient().listVersions(request).thenAccept(response - { ListString versionList response.versions(); for (String version : versionList) { System.out.println(Version info: version); } }).exceptionally(ex - { // Handle the exception, or propagate it as a RuntimeException throw new RuntimeException(Failed to list versions, ex); }); } }几个要点ListVersions不依赖任何资源是验证凭据、网络与区域配置是否正确的零风险首调maxResults(10)限制最多返回 10 个引擎版本此处OpenSearchAsyncClient.builder().build()没有显式指定 Region将走默认 Region 解析链与第二节的 us-east-1 默认值一致异步调用返回CompletableFuturemain中用join()阻塞取结果异常通过exceptionally包装为RuntimeException抛出。五、异步客户端的生产级构建方式OpenSearchActions.getAsyncClient() 展示了比 Hello 示例更完整的客户端配置这也是本模块最值得借鉴的部分SdkAsyncHttpClient httpClient NettyNioAsyncHttpClient.builder() .maxConcurrency(100) // 最大并发请求数 .connectionTimeout(Duration.ofSeconds(60)) .readTimeout(Duration.ofSeconds(60)) .writeTimeout(Duration.ofSeconds(60)) .build(); ClientOverrideConfiguration overrideConfig ClientOverrideConfiguration.builder() .apiCallTimeout(Duration.ofMinutes(2)) // 单次 API 调用总超时 .apiCallAttemptTimeout(Duration.ofSeconds(90)) // 单次尝试超时 .retryPolicy(RetryPolicy.builder() .numRetries(3) // 最多重试 3 次 .build()) .build(); openSearchClientAsyncClient OpenSearchAsyncClient.builder() .region(Region.US_EAST_1) // 显式固定区域 .httpClient(httpClient) .overrideConfiguration(overrideConfig) .build();参数含义与影响配置项取值作用maxConcurrency100Netty 客户端允许的最大并发 HTTP 请求connection/read/writeTimeout60 秒连接建立与 I/O 读写超时apiCallTimeout2 分钟含重试在内的一次 API 调用整体时间上限apiCallAttemptTimeout90 秒每一次尝试attempt的时间上限numRetries3SDK 内置重试策略的重试次数可缓解瞬态故障regionUS_EAST_1显式指定区域与 Hello 示例的默认区域形成对照从源码结构看该方法采用静态懒加载单例if (openSearchClientAsyncClient null)避免重复构建客户端——在长生命周期应用中客户端应复用而非按请求创建。六、八大单一操作Single Actions逐条解析README 的 “Single actions” 一节列出了 8 个可独立调用的服务函数全部实现于 OpenSearchActions.java每个方法都包裹在snippet-start/snippet-end注释标记中便于文档引用。下面按资源生命周期顺序逐一说明。6.1 CreateDomain创建域createNewDomainAsync 构建了一个较完整的CreateDomainRequestClusterConfig clusterConfig ClusterConfig.builder() .dedicatedMasterEnabled(true) // 启用专用主节点 .dedicatedMasterCount(3) // 3 个专用主节点 .dedicatedMasterType(t2.small.search) .instanceType(t2.small.search) // 数据节点机型 .instanceCount(5) // 5 个数据节点 .build(); EBSOptions ebsOptions EBSOptions.builder() .ebsEnabled(true) // 启用 EBS 卷 .volumeSize(10) // 每节点 10 GiB .volumeType(VolumeType.GP2) .build(); NodeToNodeEncryptionOptions encryptionOptions NodeToNodeEncryptionOptions.builder() .enabled(true) // 开启节点间加密 .build(); CreateDomainRequest domainRequest CreateDomainRequest.builder() .domainName(domainName) .engineVersion(OpenSearch_1.0) // 引擎版本 .clusterConfig(clusterConfig) .ebsOptions(ebsOptions) .nodeToNodeEncryptionOptions(encryptionOptions) .build();调用后通过handle回调提取domainStatus().domainId()返回。注意CreateDomain是异步生效的操作——API 返回时域仍在创建中因此后续必须配合变更进度轮询6.5 节。6.2 DescribeDomain获取域详情与 ARNdescribeDomainAsync 打印域的 endpoint、ARN 与引擎版本并返回 ARN 字符串——因为标签类 APIAddTags/ListTags都以 ARN 而非域名为定位键场景程序正是靠这一步拿到 ARN 供第 7、8 步使用。6.3 ListDomainNames列出账户下所有域listAllDomainsAsync 使用ListDomainNamesRequest.builder().engineType(OpenSearch)只返回 OpenSearch 引擎类型的域区别于 Elasticsearch 引擎的域结果为一组DomainInfo。6.4 UpdateDomainConfig修改域配置updateSpecificDomainAsync 演示了最常见的横向伸缩操作把instanceCount改为 3从 5 缩减通过UpdateDomainConfigRequest提交。修改同样异步生效需要再次轮询变更状态。6.5 DescribeDomainChangeProgress轮询直到 COMPLETEDdomainChangeProgressAsync 实现了一个带进度展示的轮询循环while (!isCompleted) { DescribeDomainChangeProgressResponse response getAsyncClient() .describeDomainChangeProgress(request) .handle((resp, ex) - { ... }).join(); String state response.changeProgressStatus().statusAsString(); if (COMPLETED.equals(state)) { isCompleted true; } else { // 每 1 秒刷新一次“状态 已耗时 mm:ss”共 5 秒一轮 } }场景程序对该步骤的说明值得保留OpenSearch 域变更从发起到 COMPLETED可能持续数分钟到数小时取决于变更复杂度与服务负载像扩容数据节点、升级引擎版本这类简单变更通常需要 1030 分钟。6.6 AddTags / ListTags按 ARN 管理标签addDomainTagsAsync 给域添加两个标签——serviceOpenSearch与instancesm3.2xlarge通过AddTagsRequest.builder().arn(domainARN).tagList(tagList)提交listDomainTagsAsync 则用ListTagsRequest按 ARN 列出全部标签并逐条打印 key/value。标签用于对域进行分类过滤也可以把同类标签资源的费用归组追踪。6.7 DeleteDomain删除域deleteSpecificDomainAsync 用DeleteDomainRequest.builder().domainName(domainName)发起删除并在whenComplete中对异常统一包装为RuntimeException。删除是不可逆的破坏性操作会移除该域的全部数据与配置务必在测试账户或测试域上执行。七、端到端场景OpenSearchScenario 的 9 步生命周期OpenSearchScenario.java 把上述单一操作串成一个可交互的完整演示对应 README 中 “Learn OpenSearch core operations” 一节描述的 9 项能力。其执行骨架如下创建域域名采用test-domain-毫秒时间戳L60-L61避免命名冲突描述域拿到 ARN 备用列出账户所有域验证新域出现在列表中等待变更完成轮询至创建操作达到 COMPLETED修改域调用updateSpecificDomainAsync调整实例数再次等待变更完成添加标签基于第 2 步的 ARN列出标签确认写入生效删除域清理资源场景结束。工程实现上有两个可复用的设计步骤间人工停顿waitForInputToContinue(scanner)要求用户输入c才继续L43-L57保证教学节奏也方便你在真实账户中观察控制台状态变化异常解包模式由于异步调用会把底层 SDK 异常包装进RuntimeException场景程序统一通过rt.getCause()解包并区分OpenSearchException打印awsErrorDetails().errorMessage()与errorCode()、ResourceNotFoundException与其他异常L76-L92 等这套写法在排查真实 OpenSearch API 报错时很实用。八、集成测试用 JUnit 5 驱动真实资源OpenSearchTest.java 与场景程序覆盖同一组 API但改为测试驱动TestInstance(TestInstance.Lifecycle.PER_METHOD)TestMethodOrder(MethodOrderer.OrderAnnotation.class)每个测试方法共享静态状态域名、ARN并按Order(1..7)严格排序所有测试标注Tag(IntegrationTest)表明它们会真实调用 AWS 服务BeforeAll中用随机数生成testdomain1~9999作为域名L36-L42避免重名冲突7 个测试依次为testHelloListVersions→testCreateDomain→testDescribeDomainTest→testListDomains→testDomainTagTestAddTags→testDomainListTagsTestListTags→testDomainDelTestDeleteDomain每个断言都使用assertDoesNotThrow(() - { ... .join(); })验证异步调用无异常。运行方式见 javav2 总 README 的 Tests 一节在示例目录下执行mvn test测试输出会以Test 1 passed…Test 7 passed的形式逐步提示。再次提醒这些集成测试操作的是真实 AWS 资源并可能产生费用请在可控账户中运行并确认区域支持 OpenSearch Service。九、构建与运行方式按 javav2 总 README 给出的通用流程针对本模块# 1. 进入模块目录 cd javav2/example_code/opensearch # 2. 构建Maven 自动下载 BOM 2.35.10 对应的 opensearch、netty-nio-client 等依赖 mvn package # 3. 运行入门示例示例类全限定名为 com.example.search.HelloOpenSearch java -cp 打包后的JAR com.example.search.HelloOpenSearch # 4. 运行集成测试 mvn test补充两点若希望直接java -cp运行需要把依赖打进 uber JAR可按总 README 说明在 pom 中加入maven-shade-plugin当前本模块 pom.xml 未预置该插件场景类com.example.search.scenario.OpenSearchScenario运行后会在每步等待键盘输入且会真实创建并删除一个 5 节点 3 主节点的域运行前请先评估费用。十、小结与延伸阅读入口本模块以“异步客户端 CompletableFuture”为主线覆盖了一个 OpenSearch 域从创建、就绪、伸缩、打标到销毁的完整控制面生命周期并在 OpenSearchActions.java 中给出了客户端超时、并发与重试的生产级配置范式。仓库中该模块的原始 READMEjavav2/example_code/opensearch/README.md的 “Additional resources” 一节还指向了 OpenSearch User Guide、OpenSearch API Reference 与 SDK for Java 2.x OpenSearch 包参考等官方资料可结合源码继续深入同仓库javav2/usecases下还有更多基于 Java 的多服务教程可对照参考。赞分享示例工程教程后端【免费下载链接】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 实战在 aws-doc-sdk-examples 中运行与测试 Amazon MQ 的 Java 示例AWS SDK for Java 2.x 实战在 aws doc sdk examples 中运行与测试 Amazon MQ 的 Java 示例 本文基于 j示例工程教程后端AWS SDK for Java 2.x 操作 Amazon S3 完全指南AWS SDK for Java 2.x 操作 Amazon S3 完全指南 概述 Amazon Simple Storage Service Amazon S示例工程教程后端AWS Migration Hub Java 示例代码实战基于 AWS SDK for Java 2.x 的配置、API 演示与 JUnit 5 集成测试AWS Migration Hub Java 示例代码实战基于 AWS SDK for Java 2.x 的配置、API 演示与 JUnit 5 集成测试 本示例工程教程后端上一篇5分钟快速上手ENet可靠UDP网络库跨平台开发终极指南下一篇Blender Power Sequencer核心组件解析操作符与工具类架构创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考