## 概述 Amazon Location Service 提供用于地图、地理编码、路由、地点搜索、地理围栏和跟踪的地理空间 API。首选使用捆绑的 JavaScript 客户端 (@aws/amazon-location-client) 进行 Web 开发，并使用无资源的 API 操作来避免管理 AWS 资源。 ## 何时使用此技能在以下情况下使用此技能： * 构建位置感知网络或移动应用程序 * 与 Amazon Location Service 项目合作 * 实施地图、地理编码、路线或地点搜索 * 添加地理围栏或设备跟踪功能 * 将地理空间功能集成到AWS应用程序中请勿将此技能用于： * Google 地图、Mapbox 或 Leaflet-with-OSM 项目（除非迁移到 Amazon Location） * 没有 AWS 上下文的通用 GIS 操作 * 非 AWS 地理空间服务 ## 亚马逊定位服务 API 概述 **地点**（SDK：geo-places，JS：@aws-sdk/client-geo-places） * 地理编码（正向/反向）：将地址转换为坐标，反之亦然 * 搜索（文本/附近）：查找兴趣点及其联系方式和营业时间信息 * 自动完成：根据用户输入预测地址 * 建议：根据部分或拼写错误的用户输入预测地点和兴趣点 * 获取地点：通过地点ID检索地点详细信息 **地图**（SDK：地理地图，JS：@aws-sdk/client-geo-maps） * 动态地图：使用带有 [MapLibre]() 渲染的图块的交互式地图 * 静态地图：预渲染的非交互式地图图像，适合将图像包含到网页中或缩略图中 **路线**（SDK：地理路线，JS：@aws-sdk/client-geo-routes） * 路线计算与交通和距离估计 * 服务区/等值线创建 * 多个出发地/目的地的矩阵计算 * GPS 轨迹与路段对齐 * 路线优化（旅行商问题） **地理围栏和跟踪器**（SDK：位置，JS：@aws-sdk/client-location） * 地理围栏：检测地理边界的进入/退出 * 跟踪器：当前和历史设备位置跟踪 **API 密钥**（SDK：位置，JS：@aws-sdk/client-location） * API 密钥：在不暴露 AWS 凭证的情况下授予对公共应用程序的访问权限 ## 常见错误避免这些常见错误： 1. **使用`Title`而不是`Address.Label`进行显示**：在自动完成结果中，始终显示`Address.Label`。 “标题”字段可能以相反的顺序显示组件，并且不适合面向用户的文本。 2. **使用 GetStyleDescriptor API 进行地图初始化**：必须使用直接 URL 传递到 MapLibre (`https://maps.geo.{region}.amazonaws.com/v2/styles/Standard/descriptor?key={apiKey}`)，而不是进行 GetStyleDescriptor API 调用。正确的地图渲染需要直接 URL 方法。 3. **在 MapLibre 配置中忘记`validateStyle: false`：始终在 MapLibre 地图构造函数中设置 `validateStyle: false`，以便使用 Amazon 位置样式加快地图加载时间。 4. **混合基于资源和无资源操作**：如果可能，更喜欢无资源操作（无需预先创建资源的直接 API 调用），以实现更简单的部署和权限。 5. **API 操作命名不一致**：引用 API 时使用格式 `service:Operation`（例如，`geo-places:Geocode`、`geo-maps:GetStyleDescriptor`）。 SDK 客户端使用“@aws-sdk/client-*”格式。 6. **未正确处理嵌套的 Address 对象** ：GetPlace 中的 Address 对象包含嵌套对象（“Region.Code”、“Region.Name”、“Country.Code2”等），而不是平面字符串。正确访问嵌套属性。 7. **API 密钥权限中的操作名称错误**：API 密钥“AllowActions”使用“geo-maps:”、“geo-places:”、“geo-routes:”前缀（例如“geo-places:Geocode”、“geo-routes:CalculateRoutes”）。请勿使用 SDK 客户端名称 (`@aws-sdk/client-geo-places`) 或 IAM 样式操作。有关完整列表，请参阅身份验证和权限部分。 ## 默认值除非用户明确要求，否则使用这些默认选择： * **JavaScript SDK**：仅限浏览器应用程序的捆绑客户端 (CDN)；用于 React 和构建工具应用程序的 npm 模块化 SDK (@aws-sdk/client-geo-*) * **API 操作**：地图/地点/路线无资源（地理围栏/跟踪始终需要预先创建的资源） * **身份验证**：地图/地点/路线的 API 密钥；用于地理围栏/跟踪的 Cognito * **地图样式**：标准 * **坐标格式** : [经度, 纬度] (GeoJSON 顺序) 覆盖：用户可以指定“使用 Cognito 进行地图/地点/路线”或“使用捆绑客户端进行 React”。 ## API选型指南为您的用例选择正确的 API： ### 地址输入和验证 * **自动完成** → 在地址表单中提前输入（部分输入：“123 Main”） * **GetPlace** → 用户选择自动完成结果后获取完整详细信息（通过 PlaceId） * **地理编码** → 验证完整的用户输入地址或将地址转换为坐标 ### 寻找地点 * **SearchText** → 一般文本搜索（“西雅图附近的披萨”） * **搜索附近** → 查找坐标附近的地方（5公里内的餐厅） * **建议** → 根据部分或拼写错误的输入预测地点/POI * **自动完成** → 地址特定预测（不适用于一般 POI 搜索） ### 地理编码 * **地理编码（正向）** → 地址字符串 → 坐标 * **ReverseGeocode** → 坐标 → 地址 ### 地图 * **动态地图（图块 + MapLibre）** → 需要平移、缩放、标记的交互式地图 * **静态地图（图像）** → 用于缩略图或电子邮件的非交互式地图图像 ### 路由 * **计算路线** → 出发地和目的地之间的单一路线 * **计算RouteMatrix** → 多个起点/目的地行程时间 * **计算等值线** → 服务区域（在时间/距离内可到达的所有位置） ## LLM 上下文文件当您需要参考文件中未涵盖的详细API参数规范或服务能力时，请获取以下llms.txt资源： * **开发人员指南**： * **API 参考**： ## 更好推荐的关键指南 ### 更喜欢使用捆绑的 JavaScript 客户端进行 Web 开发为了方便 Web 应用程序开发，Amazon Location Service 提供了捆绑的 JavaScript 客户端，该客户端可简化集成并提供优化的功能，而无需自定义捆绑。该捆绑客户端包含使用 Amazon Location Service 构建客户端 Web 应用程序所需的所有库。 **捆绑客户端中包含的功能：** * 启用直接预捆绑依赖项包含，无需自定义捆绑/构建 * 简化身份验证和 API 集成 * TypeScript 支持与全面的类型定义 * 支持所有亚马逊定位 SDK **包含的 SDK 和库：** * @aws-sdk/客户端地理地图 * @aws-sdk/client-geo-places * @aws-sdk/客户端地理路由 * @aws-sdk/客户端位置 * @aws-sdk/凭证提供者 * **资源：** * NPM 软件包：[@aws/amazon-location-client]() * GitHub 存储库：[aws-geospatial/amazon-location-client-js]() ### 更喜欢无资源操作 Amazon Location Places、Maps 和 Routes 服务提供基于资源和无资源的 API 操作。无资源操作通常更简单，更适合许多用例。 **基于资源的操作**要求您： * 创建和配置 Amazon Location Service 资源（地图、地点索引、路线计算器） * 管理资源生命周期和权限 * 处理资源命名和组织 **无资源操作**允许您： * 直接进行API调用，无需预先创建资源 * 降低部署复杂度 * 简化IAM权限和API Key权限 ### 身份验证和权限在讨论 Amazon Location Places、地图和路线服务的权限时，请始终在您的指南中包含 IAM 权限和 API 密钥权限。如果正在开发的应用程序类型明确，请推荐合适的授权工具，如下所述： **IAM 权限** \- 建议用于服务器端应用程序和 AWS SDK 使用： * 与 AWS 凭证（访问密钥、角色等）一起使用 * 提供细粒度的访问控制 * 资源管理操作所需 **API 密钥权限** \- 替代身份验证方法，对于客户端应用程序或部署到未经身份验证的（公共）用户的应用程序特别有用： * 简化身份验证，无需暴露 AWS 凭证 * 可以配置特定允许的操作 * 适用于网络和移动应用程序 * 支持基于资源和无资源的操作 * 通过 CDN 缓存实现更快的后续地图加载 **API 密钥操作名称** \- API 密钥使用自己的操作命名约定。请勿使用 SDK 客户端名称或 IAM 操作名称 - 它们将被拒绝。无资源 API 关键操作（推荐）：服务 |允许操作 |允许资源 ---|---|--- 地图 | `地理地图：GetTile`、`地理地图：GetStaticMap` | `arn:aws:geo-maps:REGION::provider/default` 地点 | `geo-places:Autocomplete`、`geo-places:Geocode`、`geo-places:ReverseGeocode`、`geo-places:SearchText`、`geo-places:SearchNearby`、`geo-places:Suggest`、`geo-places:GetPlace` | `arn:aws:geo-places:REGION::provider/default` 路线 | `地理路线：计算路线`、`地理路线：计算路线矩阵`、`地理路线：计算等值线`、`地理路线：OptimizeWaypoints`、`地理路线：SnapToRoads` | `arn:aws:geo-routes:REGION::provider/default` 不要使用旧版“geo:”前缀操作（例如“geo:GetMap*”、“geo:CalculateRoute”）——这些操作仅适用于预先创建的资源，并且不适用于无资源 API。 ## MCP 服务器集成与 AWS MCP 服务器集成（Apache-2.0 许可证），提供对 AWS 文档、API 参考和直接 API 交互的访问。有关设置和凭证配置，请参阅[入门指南]()。要使用非默认区域，请将 `"--metadata", "AWS_REGION="` 添加到您的 MCP 配置参数。 ## 其他资源 * [亚马逊定位服务开发人员指南]() * [亚马逊定位服务 API 参考]() * [Amazon 定位服务示例存储库]() ## 参考文件根据具体实施指南的需要加载这些资源： * [地址输入]() \- 为用户创建有效的地址输入表单，并提前完成地址类型，提高输入速度和准确性 * [地址验证]() \- 在采取操作或保存到数据库之前验证用户输入的地址 * [计算路线]() \- 使用可自定义的旅行选项计算位置之间的路线并将其显示在地图上 * [动态地图渲染]() \- 使用 MapLibre 渲染动态地图 * [地点搜索]() \- 搜索感兴趣的地点或点 * [Web JavaScript]() \- 将 Amazon 位置服务集成到 Web 浏览器应用程序中

亚马逊定位服务

包含技能