示例工程教程后端【免费下载链接】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 ServiceAWS 定位服务是 AWS 提供的一项完全托管的定位服务开发者无需自建地理信息系统即可快速为应用嵌入地图、实现设备实时追踪、地理围栏与地点检索能力。本文以aws-doc-sdk-examples仓库中 Location 基础场景规格说明 为骨架结合 Java 2.x 版示例实现 与 底层操作封装系统讲解一个端到端交互式场景从创建地图、API Key、地理围栏集合、追踪器Tracker、路由计算器到使用更高层的GeoPlacesAsyncClient完成逆地理编码、文本地点搜索与周边地点搜索最后清理资源。读完本文你将掌握 AWS Location Service 的核心 API 调用方式、参数细节与异常处理模式并能照搬这套场景代码快速落地自己的位置类应用。场景概述一条龙的地图 追踪 搜索演练本场景定位为SDK Basics 场景目标是让不熟悉 AWS Location Service 的开发者快速上手。它使用两个客户端LocationAsyncClientSDK for Java 2.x 的定位服务异步客户端承担地图、API Key、地理围栏、追踪器、路由计算器等资源的创建与操作GeoPlacesAsyncClient更高层的 Geo Places 客户端承担逆地理编码、地点文本搜索与周边搜索能力。两个客户端均以异步方式工作返回CompletableFuture场景代码通过.join()阻塞等待结果并在CompletionException中解析具体异常类型。这种设计让开发者可以循序渐进地看到每一步操作的真实结果非常适合教学与入门。场景不需要额外的 AWS 资源不依赖 S3、Lambda 等外部组件运行时只需通过命令行传入 7 个命名参数。从元数据文件 location_metadata.yaml 可以看到该场景在 Java、Kotlin、JavaScript 三种语言中均有对应实现其中 Java 版包含完整的场景主流程与操作封装两个代码片段。场景执行清单规格说明将整个场景拆解为 12 个操作步骤对应完整的资源生命周期创建地图Create a map创建 AWS Location API Key展示地图 URLMap URL创建地理围栏集合Geofence collection向集合中写入地理围栏几何体PutGeofence创建追踪器资源Tracker更新设备位置获取设备最新位置创建路由计算器Route calculator计算西雅图到温哥华的距离使用 GeoPlaces 高层 API 完成检索删除全部 AWS 资源说明本场景代码位于 javav2/example_code/location其配套的独立 API 操作示例与单元测试可分别参考 LocationActions.java 与 LocationTest.java。同主题的 Kotlin 实现位于 kotlin/services/location。运行准备与程序参数前提条件配置 AWS 开发环境与凭证Access Key 等参见 javav2 目录的 README本地安装 JDK 与 MavenJava 2.x 示例通过 Maven 构建注意运行示例会产生 AWS 账户费用建议按最低权限原则配置 IAM 策略且该代码并未在所有 AWS 区域验证过。命令行参数LocationScenario.main要求恰好 7 个命令行参数否则打印使用说明并退出LocationScenario.java#L40-L66Usage: mapName keyName collectionName geoId trackerName calculatorName deviceId参数含义示例值mapName要创建的地图名称AWSMapkeyName要创建的 API Key 名称AWSApiKeycollectionName地理围栏集合名称AWSLocationCollectiongeoId地理围栏或地图的地理标识符geoIdtrackerName追踪器名称geoTrackercalculatorName路由计算器名称AWSRouteCalcdeviceId设备 IDiPhone-112356主流程使用Scanner交互式等待输入每一步都提示Enter c followed by ENTER to continue:后才继续执行便于观察每步输出。异步客户端配置LocationActions采用单例模式创建两个异步客户端LocationActions.java#L67-L111关键配置参数包括底层 HTTP 客户端使用NettyNioAsyncHttpClientmaxConcurrency(100)连接/读/写超时均为 60 秒ClientOverrideConfigurationapiCallTimeout2 分钟、apiCallAttemptTimeout90 秒、retryStrategy(RetryMode.STANDARD)标准重试模式。这套配置为位置类服务常见的慢速网络与大批量并发请求场景提供了合理的兜底是实际项目中可直接复用的异步客户端构建模板。Hello AWS Location Service用分页器初识地理围栏在进入完整场景之前规格说明提供了一个 Hello 入门程序使用listGeofencesPaginator地理围栏列表分页器读取地理围栏信息让不熟悉该服务的用户快速建立感知。该程序对应 HelloLocation.java在 location_metadata.yaml 中登记的服务操作为ListGeofences, ListGeofenceCollections。分页器Paginator是 AWS SDK 中处理结果可能超过单页上限的标准手段开发者无需手工维护NextToken即可流式遍历全部地理围栏数据。核心操作逐步拆解12 步全流程以下按规格说明的 12 个步骤逐项展开每步给出对应的LocationActions底层 API 细节、参数说明与异常处理方式。所有方法的实际代码可在 LocationActions.java 中对应片段找到。第 1 步创建地图createMap调用locationAsyncClient.createMap返回地图 ARN。底层请求需要指定地图名称与地图配置MapConfiguration。在 Java 2.x 实现中LocationScenario通过locationActions.createMap(mapName).join()获取mapArn并打印对应片段 createMap。异常处理捕获ServiceQuotaExceededException—— 表示请求将超过最大配额而被拒绝打印信息后结束程序。这提醒开发者在多租户或大规模上线场景中应提前规划服务配额。第 2 步创建 AWS Location API KeycreateKey调用locationAsyncClient.createKey创建 API Key其用途是在 Web 应用或网站中嵌入地图时将 Key 拼接到地图瓦片 URL 中完成请求鉴权。规格说明强调两点可以将 API Key 限制到指定的 AWS Location 操作例如只允许访问地图不允许地理编码API Key 可以设置过期时间实现临时访问控制。底层实现中请求需要携带ApiKeyRestrictionsAPI Key 限制条件并关联第 1 步创建的地图 ARN见 createKey。异常处理捕获AccessDeniedException—— 权限或访问不足时抛出打印错误信息并终止程序。第 3 步展示地图 URL本步不调用任何 SDK 方法仅演示如何拼接地图瓦片 URL。控制台输出如下格式Embed this URL in your Web app: https://maps.geo.aws.amazon.com/maps/v0/maps/{mapName}/tiles/{z}/{x}/{y}?key{KeyValue}对应 LocationScenario.java#L162即https://maps.geo.aws.amazon.com/maps/v0/maps/ 地图名 /tiles/{z}/{x}/{y}?key{KeyValue}其中{z}/{x}/{y}是瓦片坐标的缩放级别与行列号占位符。关键提醒规格说明原文要得到完整可用的地图 URL还需要拿到 API Key 的键值key value而获取键值无法通过 AWS SDK 完成需要登录 AWS Management Console 的 Location Services 页面查看。这是本场景中唯一需要人工介入的环节。第 4 步创建地理围栏集合createGeofenceCollection地理围栏集合用于管理和存储地理围栏。调用locationAsyncClient.createGeofenceCollection成功返回集合 ARN如arn:aws:geo:us-east-1:...:geofence-collection/AWSLocationCollection200见 createGeofenceCollection。异常处理捕获ConflictException—— 表示发生冲突例如同名资源已存在打印消息后结束程序。第 5 步存储地理围栏几何体putGeofence调用locationAsyncClient.putGeofence向指定集合中写入一个地理围栏。本步的重点是如何构造一个合法的多边形polygon。规格说明明确要求地理围栏多边形必须按**逆时针方向counter-clockwise**定义即多边形的顶点必须按逆时针顺序排列AWS Location 才能正确解释地理围栏并保证位置数据被准确处理。Java 实现putGeofence构造了一个闭合的矩形多边形GeofenceGeometry.builder() .polygon(List.of( List.of( List.of(-122.3381, 47.6101), // 第一个顶点 List.of(-122.3281, 47.6101), List.of(-122.3281, 47.6201), List.of(-122.3381, 47.6201), List.of(-122.3381, 47.6101) // 回到起点闭合多边形 ) ))坐标顺序遵循 AWS 约定每个点先经度longitude后纬度latitude。多边形首尾相连最后一个点回到第一个点构成封闭区域。异常处理捕获ValidationException—— 因多边形非法而抛出如坐标顺序错误、经纬度越界打印消息后结束程序。第 6 步创建追踪器资源createTracker追踪器Tracker用于获取设备的当前与历史位置。调用locationAsyncClient.createTracker底层请求包含三个关键参数createTrackertrackerName追踪器名称description描述信息positionFiltering位置过滤策略可选值为TimeBased、DistanceBased、AccuracyBased示例中使用TimeBased即基于时间戳过滤位置更新。异常处理捕获ConflictException—— 同名追踪器已存在时抛出打印消息后结束程序。第 7 步更新设备位置batchUpdateDevicePosition调用locationAsyncClient.batchUpdateDevicePosition将设备位置写入追踪系统。底层构建DevicePositionUpdate时updateDevicePosition需要deviceId设备唯一标识sampleTime位置采样时间戳Instant.now()position坐标列表同样遵循经度在前、纬度在后的 AWS 约定。deviceId 的格式要求规格说明原文必须是字符串区分大小写长度 1–100 个字符只能包含字母数字字符A-Z、a-z、0-9、下划线_与连字符-发送位置与检索位置时必须使用同一个 ID。异常处理捕获ResourceNotFoundException—— 追踪器或设备资源不存在时抛出打印消息后结束程序。第 8 步获取设备最新位置getDevicePosition调用locationAsyncClient.getDevicePosition获取指定设备最近一次的位置更新getDevicePosition请求只需trackerName与deviceId两个参数响应中的position()即为最新坐标。规格说明中该步骤方法名写作getMatchingJob从源码看实际调用的是getDevicePosition对应元数据中的location_GetDevicePosition。异常处理捕获ResourceNotFoundException—— 设备尚无可查询位置时抛出打印消息后结束程序。第 9 步创建路由计算器createRouteCalculator调用locationAsyncClient.createRouteCalculator创建路由计算器createRouteCalculator请求关键参数calculatorName计算器名称dataSource数据源提供方示例使用Esri备选为Here。异常处理捕获ConflictException—— 同名计算器已存在时抛出打印消息后结束程序。第 10 步计算西雅图到温哥华的距离calculateRoute调用locationAsyncClient.calculateRoute计算两点间路线calcDistanceAsync请求参数完整说明了该 API 的用法calculatorName第 9 步创建的路由计算器名称departurePosition起点坐标示例为西雅图[-122.3321, 47.6062]destinationPosition终点坐标示例为温哥华[-123.1216, 49.2827]travelMode出行方式可选Car、Truck、Walking、Bicycle示例为CardistanceUnit距离单位可选Meters、Kilometers、Miles示例为Kilometers。响应中的response.summary().distance()即为距离数值示例输出为约229.49公里。异常处理捕获ResourceNotFoundException—— 计算器资源不存在时抛出打印消息后结束程序。第 11 步使用 GeoPlaces 高层 API 完成地点检索本步骤切换到GeoPlacesAsyncClient展示三类高层检索能力对应规格说明第 11 节与元数据 geo-places_metadata.yaml 中的geo-places_ReverseGeocode、geo-places_SearchText、geo-places_SearchNearby逆地理编码 reverseGeocode将地理坐标转换为人类可读的地址reverseGeocode。示例使用旧金山坐标37.7749, -122.4194请求中queryPosition依然按[经度, 纬度]顺序传入。运行结果示例FedEx Office, 1967 Market St, San Francisco, CA 94103, United States。文本地点搜索 searchText基于搜索词查找地点searchText。请求参数queryText搜索文本示例为coffee shopbiasPosition搜索偏好中心坐标用于影响结果排序。实现中还演示了二次调用取第一个结果的placeId再通过getPlace获取详细地点信息包括地址与FoodTypes食品类型列表。周边地点搜索 searchNearby查找指定位置附近的场所searchNearBy。请求参数queryPosition中心位置坐标经度、纬度顺序queryRadius搜索半径单位为米示例1000L即 1 公里。响应中的每个resultItems条目包含placeType如POINT_OF_INTEREST、address().label()地址与distance()距中心点的距离示例输出大量距离 2–3 米的结果。异常处理捕获software.amazon.awssdk.services.geoplaces.model.ValidationException—— 检索参数非法时抛出打印消息后结束程序。第 12 步删除 AWS 资源资源清理场景运行到最后或中途发生未预期运行时异常时会进入清理流程LocationScenario.java#L379-L395。交互式询问用户Would you like to delete the AWS Location Services resources? (y/n)输入y后依次删除deleteMap删除地图deleteKey删除 API KeydeleteGeofenceCollectionAsync删除地理围栏集合deleteTracker删除追踪器deleteRouteCalculator删除路由计算器异常处理删除阶段捕获ResourceNotFoundException即资源不存在时给出提示。值得注意场景在主流程try块外部捕获RuntimeException也会触发cleanUp确保即使中途失败也能尽量回收已创建的资源这是避免遗留云端资源产生费用的关键设计。控制台运行输出示例规格说明提供了完整的一次运行输出可帮助开发者对照验证自己的执行结果。以下是关键片段的整理完整文本见 scenarios/basics/location/SPECIFICATION.md 的 Program execution 一节The Map ARN is: arn:aws:geo:us-east-1:814548047983:map/AWSMap200 The API key was successfully created: arn:aws:geo:us-east-1:814548047983:api-key/AWSApiKey200 Embed this URL in your Web app: https://maps.geo.aws.amazon.com/maps/v0/maps/AWSMap200/tiles/{z}/{x}/{y}?key{KeyValue} The geofence collection was successfully created: arn:aws:geo:us-east-1:814548047983:geofence-collection/AWSLocationCollection200 Successfully created geofence: geoId200 Successfully created tracker. ARN: arn:aws:geo:us-east-1:814548047983:tracker/geoTracker200 iPhone-112356 was successfully updated in the location tracking system. Successfully fetched device position: [-122.4194, 37.7749] Route calculator created successfully: arn:aws:geo:us-east-1:814548047983:route-calculator/AWSRouteCalc200 Successfully calculated route. The distance in kilometers is 229.4919562976832逆地理编码与文本搜索输出示例Use latitude 37.7749 and longitude -122.4194 The address is: FedEx Office, 1967 Market St, San Francisco, CA 94103, United States Found Place with id: AQAAAFUARI2OrflhvYzXbmuuOadKpTSJ6ynsZSLcXI2xbU2X2D5PdcHmlQ-jrs-hn-yhF7jOC9hMgrXFP5neo_lK480qGCAO-zdYrsKSBoWVm8DhRNFLF_Eyua-vUTfG9SGbSGJmUfwxSkPKIYRYOnRnocKOT6CsGt_h Detailed Place Information: Name: POINT_OF_INTEREST Address: Cafe Creme, 50 Oak St, San Francisco, CA 94102-6011, United States Food Types: - FoodType(LocalizedNameThai, Idthai, Primarytrue)清理阶段输出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.结束整个场景。SOS 标签Metadata与代码片段索引为了让文档、代码与自动化工具能够互相引用仓库使用 SOSSnippet/Object/Scenario元数据机制登记每个操作。规格说明第 4 节给出了完整对照表按元数据文件分为两组操作元数据文件元数据键createKeylocation_metadata.yamllocation_CreateKeycreateMaplocation_metadata.yamllocation_CreateMapcreateGeofenceCollectionlocation_metadata.yamllocation_CreateGeofenceCollectionputGeofencelocation_metadata.yamllocation_PutGeofencecreateTrackerlocation_metadata.yamllocation_CreateTrackerbatchUpdateDevicePositionlocation_metadata.yamllocation_BatchUpdateDevicePositiongetDevicePositionlocation_metadata.yamllocation_GetDevicePositioncreateRouteCalculatorlocation_metadata.yamllocation_CreateRouteCalculatorcalculateRoutelocation_metadata.yamllocation_CalculateRoutedeleteMaplocation_metadata.yamllocation_DeleteMapdeleteKeylocation_metadata.yamllocation_DeleteKeydeleteGeofenceCollectionlocation_metadata.yamllocation_DeleteGeofenceCollectiondeleteTrackerlocation_metadata.yamllocation_DeleteTrackerdeleteRouteCalculatorlocation_metadata.yamllocation_DeleteRouteCalculatorscenariolocation_metadata.yamllocation_Scenariohellolocation_metadata.yamllocation_HelloreverseGeocodegeo-places_metadata.yamlgeo-places_ReverseGeocodesearchNearbygeo-places_metadata.yamlgeo-places_SearchNearbysearchTextgeo-places_metadata.yamlgeo-places_SearchText在 .doc_gen/metadata/location_metadata.yaml 中可以查到每个元数据键对应的语言实现、代码片段标签snippet_tags与涉及的 service 操作例如location_Scenario登记了 Java/Kotlin/JavaScript 三套实现其中 Java 版包含location.java2.scenario.main场景主流程与location.java2.actions.main操作封装类两个代码片段。开发者可以据此快速跳转到任意操作的实现位置。经验总结与最佳实践回顾整个场景可以提炼出几条对实际项目有直接价值的要点坐标顺序统一为 [经度, 纬度]无论是position、queryPosition、departurePosition还是多边形顶点AWS Location Service 一律采用经度在前、纬度在后的顺序混用会导致位置错误或校验失败。多边形必须逆时针且闭合定义地理围栏时顶点需按逆时针顺序排列并回到起点闭合否则会触发ValidationException。设备 ID 有严格字符约束1–100 个字符、仅限字母数字、下划线与连字符且检索时需复用同一 ID。API Key 键值只能从控制台获取SDK 能创建 Key 并拿到 ARN但无法取回明文键值地图瓦片 URL 拼接需要人工从 AWS Management Console 获取。异常类型即业务语义ServiceQuotaExceededException提示配额不足、ConflictException提示资源重名、AccessDeniedException提示权限不足、ResourceNotFoundException提示资源不存在、ValidationException提示参数非法按异常类型分流处理即可快速定位问题。失败也要清理资源场景在异常路径同样调用cleanUp避免云端遗留资源产生持续费用。异步客户端统一配置超时与重试Netty HTTP 客户端 2 分钟 API 超时 STANDARD 重试策略是这套示例给出的稳健默认配置。如果需要把该场景移植到其他语言可在 kotlin/services/location 与 javascriptv3/example_code/location 中找到同主题的 Kotlin 与 JavaScript 实现两者的操作清单与元数据键完全一致。赞分享示例工程教程后端【免费下载链接】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 Location 服务实战地图、设备追踪、地理围栏与路线计算AWS SDK for Java 2.x 集成 Amazon Location 服务实战地图、设备追踪、地理围栏与路线计算 本篇技术指南围绕当前仓库 java示例工程教程后端使用 AWS SDK for Kotlin 驾驭 Amazon Location地图、地理围栏、设备追踪与路线规划实战指南使用 AWS SDK for Kotlin 驾驭 Amazon Location地图、地理围栏、设备追踪与路线规划实战指南 本指南以 kotlin/servi示例工程教程后端AWS SDK for Java 2.x 的 AWS KMS 基础场景实战指南aws-doc-sdk-examplesAWS SDK for Java 2.x 的 AWS KMS 基础场景实战指南aws doc sdk examples 本篇技术指南以 scenarios/示例工程教程后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考