示例工程教程后端【免费下载链接】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 官方示例仓库 aws-doc-sdk-examples 中的 Location 基础场景文档 及其 完整规格说明 为核心骨架结合仓库内 JavaSDK for Java 2.x、Kotlin、JavaScriptv3三种语言的真实实现源码完整讲解如何用 AWS SDK 打通 Amazon Location Service 的地图创建、API Key 签发、地理围栏管理、设备位置追踪、路线计算与地点搜索geocoding整条链路。读完本文你将掌握这套 12 步基础场景的程序设计思路、每个 API 的关键参数、异常处理策略以及如何运行与集成测试这套示例。场景概览一条完整的 Amazon Location 基础能力链路Amazon Location Service 是 AWS 提供的全托管位置服务帮助开发者快速为应用集成地图、位置追踪、地理围栏、路线规划与地理编码能力。仓库中的 scenarios/basics/location 目录定义了一个SDK Basics 场景Basics Scenario用一段连续可交互的程序串起该服务 12 项核心操作创建地图map创建 AWS Location API Key展示 Map URL供 Web 应用嵌入创建地理围栏集合geofence collection在集合中存储地理围栏几何多边形创建设备追踪器tracker更新设备位置获取设备最近一次位置创建路线计算器route calculator计算西雅图Seattle与温哥华Vancouver之间的距离使用更高层的GeoPlacesAPI 执行反向地理编码、文本搜索与周边搜索清理全部 AWS 资源该场景在设计上分为两层客户端底层位置操作地图、Key、围栏、追踪、路线使用LocationAsyncClient而第 11 步的地点搜索与地理编码使用更高层的GeoPlacesAsyncClient。规格文档明确说明该基础场景不需要任何额外的辅助资源如 S3 桶或 DynamoDB 表全部资源由程序自身创建并在结束时删除非常适合作为入门 Amazon Location 的起步项目。根据 README 中的 Implementations 一节这一场景在多语言仓库中以 Java、Python、Kotlin 三种语言为目标实现从当前仓库实际代码看Java 与 Kotlin 的实现已经落地见 javav2/example_code/location 与 kotlin/services/location同时 JavaScriptv3也在 javascriptv3/example_code/location 下提供了独立的 action 级示例与集成测试。运行前准备凭证、依赖与命令行参数开发环境与凭证运行任何语言实现前都需要完成 AWS 凭证与开发环境配置设置AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY或采用 SSO / 环境变量方式并确保 IAM 主体具备 Amazon Location Service 相关资源的创建、更新与删除权限。Java 场景入口 LocationScenario.java 的类注释中即提醒读者先行配置环境HelloLocation.java 还指出Hello 示例要求先在控制台创建好一个地理围栏集合。JavaSDK for Java 2.x依赖Java 实现的 Maven 工程位于 javav2/example_code/location/pom.xml其核心依赖包括software.amazon.awssdk:locationAmazon Location Service 主客户端software.amazon.awssdk:geoplaces第 11 步所用 Geo Places 客户端software.amazon.awssdk:netty-nio-client异步 HTTP 客户端Netty NIOsoftware.amazon.awssdk:bom版本2.35.10统一管理 SDK 版本org.junit.jupiter:junit-jupiter5.11.4用于集成测试。工程要求 JDK 17maven.compiler.source/target17。命令行参数Java 与 Kotlin 的场景入口都要求传入7 个命令行参数含义与建议值见 LocationScenario.java 与 LocationScenario.kt参数含义示例值mapName地图资源名称AWSMapkeyNameAPI Key 名称AWSApiKeycollectionName地理围栏集合名称AWSLocationCollectiongeoId地理围栏的唯一标识geoIdtrackerName追踪器名称geoTrackercalculatorName路线计算器名称AWSRouteCalcdeviceId被追踪设备 IDiPhone-112356JavaScript 场景把同样的参数固化在 javascriptv3/example_code/location/scenarios/inputs.json 的inputs对象中各 action 文件通过data.inputs.mapName等方式引用保持多语言命名一致。异步客户端配置Java 实现采用单例模式持有异步客户端其构建参数很有参考价值见 LocationActions.javaNetty HTTP 客户端maxConcurrency100连接/读/写超时均为 60 秒客户端覆盖配置apiCallTimeout2 分钟、apiCallAttemptTimeout90 秒、retryStrategyRetryMode.STANDARD。RetryMode.STANDARD意味着 SDK 会对可重试的瞬时错误节流、连接中断等自动退避重试CompletionException包裹的底层异常由调用方按类型分流处理。Hello Amazon Location用分页器快速入门Hello 示例面向不熟悉 Amazon Location 的开发者其实现HelloLocation.java使用listGeofencesPaginator订阅式分页读取地理围栏信息ListGeofencesRequest geofencesRequest ListGeofencesRequest.builder() .collectionName(collectionName) .build(); ListGeofencesPublisher paginator getClient().listGeofencesPaginator(geofencesRequest); CompletableFutureVoid future paginator.subscribe(response - { if (response.entries().isEmpty()) { logger.info(No Geofences were found in the collection.); } else { response.entries().forEach(geofence - logger.info(Geofence ID: geofence.geofenceId())); } });listGeofencesPaginator返回ListGeofencesPublisher通过subscribe回调逐页处理结果避免手动维护NextToken。运行方式为传入一个集合名称collectionName。规格文档SPECIFICATION.md将这一步定位为Hello AWS Location Service目的是让读者快速上手。Kotlin 侧对应实现位于 HelloLocation.kt。逐步拆解 12 项核心操作以下操作均以 Java 实现 LocationActions.java 为代码依据Kotlin 与 JavaScript 实现一一对应。1. 创建地图调用createMapLocationActions.javaMapConfiguration configuration MapConfiguration.builder() .style(VectorEsriNavigation) .build(); CreateMapRequest mapRequest CreateMapRequest.builder() .mapName(mapName) .configuration(configuration) .description(A map created using the Java V2 API) .build();关键参数style地图样式示例使用VectorEsriNavigationEsri 矢量导航底图description资源描述可在控制台识别资源用途。异常处理捕获ServiceQuotaExceededException表示请求将超出账户配额上限每个 AWS 账户对 map 数量有服务配额打印信息后结束程序LocationScenario.java。成功后返回 Map ARN格式如arn:aws:geo:us-east-1:814548047983:map/AWSMap200。JavaScript 对应实现见 create-map.js同样指定style: VectorEsriNavigation并输出MapArn。2. 创建 AWS Location API Key调用createKeyLocationActions.javaApiKeyRestrictions keyRestrictions ApiKeyRestrictions.builder() .allowActions(geo:GetMap*) .allowResources(mapArn) .build(); CreateKeyRequest request CreateKeyRequest.builder() .keyName(keyName) .restrictions(keyRestrictions) .noExpiry(true) .build();该 Key 用于 Web 应用嵌入地图时放在瓦片 URL 中进行请求鉴权。注意三点设计allowActions(geo:GetMap*)将 Key 的权限限制在取地图类操作例如不允许用它做地理编码allowResources(mapArn)Key 只能访问刚创建的这张地图noExpiry(true)不过期规格文档同时提示 Key可以设置过期时间以实现临时访问控制。异常处理捕获AccessDeniedException提示权限不足后终止程序。成功返回 Key ARN如arn:aws:geo:us-east-1:814548047983:api-key/AWSApiKey200。3. 展示 Map URL此步不调用任何 SDK 方法只是按语法拼接瓦片 URL 并在控制台打印LocationScenario.javahttps://maps.geo.aws.amazon.com/maps/v0/maps/{mapName}/tiles/{z}/{x}/{y}?key{KeyValue}规格文档明确指出要取得真正的 Key Value必须通过 AWS Management Console 的 Location Services 页面查看SDK 无法读取 Key 的明文值。将{mapName}换成资源名、{KeyValue}换成控制台中的 Key Value 后即可把该 URL 嵌入 Web 应用。{z}/{x}/{y}是标准 Web 墨卡托瓦片坐标缩放级别/列/行。4. 创建地理围栏集合调用createGeofenceCollectionLocationActions.javaCreateGeofenceCollectionRequest collectionRequest CreateGeofenceCollectionRequest.builder() .collectionName(collectionName) .description(Created by using the AWS SDK for Java) .build();地理围栏集合用于统一管理、存储多个地理围栏。异常处理捕获ConflictException集合已存在或发生冲突打印信息并结束程序。成功后返回collectionArn如arn:aws:geo:us-east-1:814548047983:geofence-collection/AWSLocationCollection200。5. 存储地理围栏几何多边形构造调用putGeofenceLocationActions.javaGeofenceGeometry geofenceGeometry GeofenceGeometry.builder() .polygon(List.of( List.of( List.of(-122.3381, 47.6101), // First point List.of(-122.3281, 47.6101), List.of(-122.3281, 47.6201), List.of(-122.3381, 47.6201), List.of(-122.3381, 47.6101) // Closing the polygon ) )) .build(); PutGeofenceRequest geofenceRequest PutGeofenceRequest.builder() .collectionName(collectionName) .geofenceId(geoId) .geometry(geofenceGeometry) .build();这一步最能体现地理围栏的几何约束规格文档SPECIFICATION.md特别强调多边形顶点必须按逆时针counter-clockwise方向列出否则服务无法正确解释围栏区域首尾顶点重合以闭合多边形示例中第 1 点与第 5 点坐标相同每个顶点坐标是[经度, 纬度]的有序列表注意是 longitude 在前。异常处理捕获ValidationException多边形非法如自相交、顶点不足或方向错误打印信息并结束程序。成功后返回geoId示例输出Successfully created geofence: geoId200。JavaScript 对应实现 put-geofence.js 中 Polygon 数组与 Java 完全同构同样捕获ValidationException。6. 创建设备追踪器调用createTrackerLocationActions.javaCreateTrackerRequest trackerRequest CreateTrackerRequest.builder() .description(Created using the Java V2 SDK) .trackerName(trackerName) .positionFiltering(TimeBased) // Options: TimeBased, DistanceBased, AccuracyBased .build();追踪器用于获取设备的当前与历史位置。关键参数positionFiltering决定位置更新的过滤策略三档可选TimeBased按时间采样、DistanceBased按移动距离、AccuracyBased按定位精度。异常处理捕获ConflictException同名追踪器已存在。成功后返回 tracker ARN如arn:aws:geo:us-east-1:814548047983:tracker/geoTracker200。7. 更新设备位置调用batchUpdateDevicePositionLocationActions.javaDevicePositionUpdate positionUpdate DevicePositionUpdate.builder() .deviceId(deviceId) .sampleTime(Instant.now()) // Timestamp of position update. .position(Arrays.asList(longitude, latitude)) // AWS requires [longitude, latitude] .build(); BatchUpdateDevicePositionRequest request BatchUpdateDevicePositionRequest.builder() .trackerName(trackerName) .updates(positionUpdate) .build();要点位置更新需携带sampleTime采样时间戳示例用Instant.now()position同样遵循[经度, 纬度]顺序使用BatchUpdateDevicePositionRequest可以一次提交多个设备更新。关于deviceId规格文档SPECIFICATION.md给出明确约束必须是区分大小写的字符串长度 1–100 字符仅允许字母数字A-Z、a-z、0-9、下划线_与连字符-发送与检索位置时必须使用同一个 ID。异常处理捕获ResourceNotFoundException追踪器或设备不存在。示例输出iPhone-112356 was successfully updated in the location tracking system.。8. 获取设备最近一次位置调用getDevicePositionLocationActions.javaGetDevicePositionRequest request GetDevicePositionRequest.builder() .trackerName(trackerName) .deviceId(deviceId) .build();响应中的position字段即为设备最近一次上报的坐标。异常处理捕获ResourceNotFoundException。示例输出Successfully fetched device position: [-122.4194, 37.7749]即旧金山坐标经度在前。9. 创建路线计算器调用createRouteCalculatorLocationActions.javaString dataSource Esri; // or Here CreateRouteCalculatorRequest request CreateRouteCalculatorRequest.builder() .calculatorName(routeCalcName) .dataSource(dataSource) .build();dataSource指定路线数据源可选Esri或Here。异常处理捕获ConflictException同名计算器已存在。成功后返回 calculator ARN如arn:aws:geo:us-east-1:814548047983:route-calculator/AWSRouteCalc200。10. 计算西雅图与温哥华之间的距离调用calculateRouteLocationActions.java// Define coordinates for Seattle, WA and Vancouver, BC. ListDouble departurePosition Arrays.asList(-122.3321, 47.6062); ListDouble arrivePosition Arrays.asList(-123.1216, 49.2827); CalculateRouteRequest request CalculateRouteRequest.builder() .calculatorName(routeCalcName) .departurePosition(departurePosition) .destinationPosition(arrivePosition) .travelMode(Car) // Options: Car, Truck, Walking, Bicycle .distanceUnit(Kilometers) // Options: Meters, Kilometers, Miles .build();要点起点为西雅图[-122.3321, 47.6062]终点为温哥华[-123.1216, 49.2827]依然遵循经度在前travelMode可选Car、Truck、Walking、BicycledistanceUnit可选Meters、Kilometers、Miles。异常处理捕获ResourceNotFoundException。场景输出距离从response.summary().distance()读取LocationScenario.java示例结果为229.4919562976832 公里。11. 使用更高层 GeoPlaces API地理编码与地点搜索第 11 步换用GeoPlacesAsyncClientLocationActions.java 中独立构建完成三个任务反向地理编码reverseGeocodeLocationActions.java把坐标转成可读地址。// AWS expects [longitude, latitude]. ListDouble queryPosition List.of(longitude, latitude); ReverseGeocodeRequest request ReverseGeocodeRequest.builder() .queryPosition(queryPosition) .build();示例以旧金山37.7749, -122.4194为输入输出地址FedEx Office, 1967 Market St, San Francisco, CA 94103, United States。文本地点搜索searchTextLocationActions.java以 coffee shop 为关键词搜索并借助getPlace拉取第一个结果的详情含食品类型 foodTypesSearchTextRequest request SearchTextRequest.builder() .queryText(searchQuery) .biasPosition(queryPosition) .build();biasPosition用于给搜索结果提供位置偏好旧金山附近。示例返回Cafe Creme, 50 Oak St, San Francisco, CA 94102-6011及FoodType(LocalizedNameThai, Idthai, Primarytrue)。周边搜索searchNearbyLocationActions.java以指定坐标为中心、半径 1 公里搜索周边 POI。SearchNearbyRequest request SearchNearbyRequest.builder() .queryPosition(queryPosition) .queryRadius(1000L) // Radius in meters (1000 meters 1 km). .build();输出逐条打印Place Name / Address / Distance示例中 Market St 周边一批 POI 距离均在 2–3 米量级。异常处理三者统一捕获ValidationExceptionGeo Places 命名空间下的校验异常打印后结束程序。12. 清理 AWS 资源场景末尾询问用户Would you like to delete the AWS Location Services resources? (y/n)确认后调用cleanUpLocationScenario.java依次执行五个删除方法deleteMapLocationActions.javadeleteKeyLocationActions.javadeleteGeofenceCollectionAsyncLocationActions.javadeleteTrackerLocationActions.javadeleteRouteCalculatorLocationActions.java每个删除方法均捕获ResourceNotFoundException资源可能已被删除或不存在。值得注意的是场景主流程外层还有一层兜底清理一旦前序任何一步抛出RuntimeExceptionmain的catch块会立即调用cleanUpLocationScenario.java避免异常中断后遗留云上资源造成计费。程序运行输出样例规格文档SPECIFICATION.md给出了完整的控制台输出。整个流程采用按 c 回车继续的交互节奏关键输出片段如下Enter c followed by ENTER to continue: c Continuing with the program... -------------------------------------------------------------------------------- 1. Create a map ... The Map ARN is: arn:aws:geo:us-east-1:814548047983:map/AWSMap200 2. Create an AWS Location API key ... The API key was successfully created: arn:aws:geo:us-east-1:814548047983:api-key/AWSApiKey200 3. Display Map URL ... Embed this URL in your Web app: https://maps.geo.aws.amazon.com/maps/v0/maps/AWSMap200/tiles/{z}/{x}/{y}?key{KeyValue} 5. Store a geofence geometry in a given geofence collection. ... Successfully created geofence: geoId200 8. Retrieve the most recent position update for a specified device.. ... Successfully fetched device position: [-122.4194, 37.7749] 10. Determine the distance between Seattle and Vancouver using the route calculator. ... Successfully calculated route. The distance in kilometers is 229.4919562976832 12. Delete the AWS Location Services resources. Would you like to delete the AWS Location Services resources? (y/n) y The map AWSMap200 was deleted. The key AWSApiKey200 was deleted. The geofence collection AWSLocationCollection200 was deleted. The tracker geoTracker200 was deleted. The route calculator AWSRouteCalc200 was deleted. This concludes the AWS Location Service scenario.异常处理矩阵把 12 步的异常处理汇总如下便于对照实现操作主要异常触发含义处理方式createMapServiceQuotaExceededException将超出账户服务配额打印信息并结束程序createKeyAccessDeniedException权限或访问不足打印错误并终止createGeofenceCollectionConflictException资源冲突如已存在打印信息并结束putGeofenceValidationException多边形非法如未逆时针打印信息并结束createTrackerConflictException同名追踪器冲突打印信息并结束batchUpdateDevicePositionResourceNotFoundException追踪器/设备不存在打印信息并结束getDevicePositionResourceNotFoundException设备不存在打印信息并结束createRouteCalculatorConflictException同名计算器冲突打印信息并结束calculateRouteResourceNotFoundException计算器不存在打印信息并结束GeoPlaces 三操作ValidationException请求参数校验失败打印信息并结束全部删除操作ResourceNotFoundException资源不存在打印信息并结束从源码实现如 LocationActions.java 与 LocationScenario.java可以看到异步链上的异常最终被包装为CompletionException场景层再依据ce.getCause()的类型分流这一模式在整个文件中保持一致。测试与 SOS Tags 元数据Java 侧提供了完整的集成测试 LocationTest.java以Tag(IntegrationTest)Order串行验证各动作依次测试创建地图、创建 Key、创建围栏集合、putGeofence、Hello 分页读取、创建追踪器、更新与读取设备位置、路线计算等并对每个 ARN 断言非空。测试命名如TestMap1、TestKey1与场景运行参数AWSMap等相互独立避免冲突。仓库的文档生成体系SOS Tags把每个动作映射到元数据文件方便自动化生成与校验示例代码。Amazon Location 场景的映射表见 location_metadata.yaml 与 geo-places_metadata.yaml其中 GeoPlaces 的三个操作reverseGeocode、searchText、searchNearby当前仅 Java 实现挂载了 snippet而location_*系列操作则覆盖 Java、Kotlin、JavaScript 三种语言。元数据中的github字段同时印证了各语言实现的目录位置Javajavav2/example_code/locationKotlinkotlin/services/locationJavaScriptjavascriptv3/example_code/location延伸阅读与运行提示本文所述场景的完整规格含全部操作说明与控制台输出见 SPECIFICATION.mdJava 场景的使用说明与各 action 索引见 javav2/example_code/location/README.md运行代码可能产生 AWS 账户费用官方建议遵循最小权限原则least privilege并且该示例并非在全部 AWS 区域经过测试请以你实际使用的区域与配额为准。掌握本场景后你可以基于同一套模式扩展出结合 API Key 的 Web 地图嵌入、基于地理围栏的资产告警、多设备批量位置上报以及将GeoPlaces搜索能力接入应用内的地点推荐等功能。所有实现都以 scenarios/basics/location 目录为起点配合仓库中的多语言源码即可直接运行与二次开发。赞分享示例工程教程后端【免费下载链接】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 Location Service SDK 基础场景实战指南用 AWS SDK for Java 2.x 构建地图、地理围栏、设备追踪与路由计算AWS Location Service SDK 基础场景实战指南用 AWS SDK for Java 2.x 构建地图、地理围栏、设备追踪与路由计算 导读示例工程教程后端AWS SDK for Java 2.x 集成 Amazon Location 服务实战地图、设备追踪、地理围栏与路线计算AWS SDK for Java 2.x 集成 Amazon Location 服务实战地图、设备追踪、地理围栏与路线计算 本篇技术指南围绕当前仓库 java示例工程教程后端使用 AWS SDK for Kotlin 驾驭 Amazon Location地图、地理围栏、设备追踪与路线规划实战指南使用 AWS SDK for Kotlin 驾驭 Amazon Location地图、地理围栏、设备追踪与路线规划实战指南 本指南以 kotlin/servi示例工程教程后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考