本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 开始使用 Amazon Location Service 跟踪器 本节提供了有关创建和使用 Amazon Location 跟踪器的综合指南。跟踪器支持存储、处理和评估设备位置，同时筛选位置更新以减少干扰信息并控制成本。借助高级位置筛选选项、对链接的地理围栏集合的支持，以及与 EventBridge 和 IoT Core 等 AWS 服务的集成，跟踪器可根据您的特定需求提供精确的实时跟踪和地理围栏应用程序。 **Topics** + [创建跟踪器](start-create-tracker.md) + [对您的请求进行身份验证](tracking-identity-pool.md) + [使用设备位置更新跟踪器](send-location-updates.md) + [通过跟踪器获取设备的位置记录](get-location-history.md) + [列出您的设备位置](list-device-positions.md) # 创建跟踪器 创建跟踪器资源以存储和处理来自您设备的位置更新。您可以使用 Amazon Location Service 控制台 AWS CLI、或亚马逊位置 APIs。 存储在您的跟踪器资源中的每个位置更新都可能包括一个位置精度指标，以及最多三个与您要存储的位置或设备相关的元数据字段。元数据以键值对的形式存储，可以存储速度、方向、轮胎压力或发动机温度等信息。 跟踪器在收到的位置更新时对其进行过滤。这可以减少设备路径中的视觉噪音（称为*抖动*），并减少错误的地理围栏进入和退出事件的数量。这还可以减少启动的地理围栏评估的数量，从而帮助管理成本。 跟踪器提供三种位置筛选选项，以帮助管理成本并减少位置更新中的抖动。 + **基于精度**——*与任何提供精度测量的设备一起使用。大多数移动设备都提供此信息。*每次位置测量的准确性受许多环境因素的影响，包括 GPS 卫星接收、场景以及 Wi-Fi 和蓝牙设备的距离。大多数设备，包括大多数移动设备，都可以提供测量精度的估计值以及测量结果。通过 `AccuracyBased` 筛选，如果设备移动小于测量的精度，Amazon Location 将忽略位置更新。例如，如果一个设备两次连续更新的精度范围分别为 5 米和 10 米，则该设备的移动距离小于 15 米时 Amazon Location 忽略第二次更新。Amazon Location 既不会根据地理围栏评估被忽略的更新，也不会存储这些更新。 如果未提供精度，则将其视为零，并且测量结果被视为完全准确。 **注意** 您也可以使用基于精度的筛选来移除所有筛选。如果您选择基于精度的筛选，但将所有精度数据覆盖为零，或者完全省略准确性，那么 Amazon Location 将不会筛选出任何更新。 + **基于距离**——*当您的设备不提供精度测量值，但您仍希望利用筛选功能来减少抖动并管理成本时使用*。`DistanceBased` 筛选忽略设备移动小于 30 米（98.4 英尺）的位置更新。当您使用 `DistanceBased` 位置筛选时，Amazon Location 既不会根据地理围栏评估这些被忽略的更新，也不会存储更新。 大多数移动设备的精度，包括 iOS 和 Android 设备的平均精度，都在 15 米以内。在大多数应用程序中，`DistanceBased` 筛选可以减少在地图上显示设备轨迹时位置不准确的影响，以及设备靠近地理围栏边界时连续多次进入和退出事件的反弹效果。它还可以减少对照链接的地理围栏进行评估或检索设备位置的调用，从而帮助降低应用程序的成本。 + **基于时间**——（默认）*当您的设备非常频繁地发送位置更新（每 30 秒钟超过一次），并且您希望在不存储每个更新的情况下实现近乎实时的地理围栏评估时使用*。在 `TimeBased` 筛选中，每个位置更新根据链接的地理围栏集合进行评估，但并非每个位置更新都会存储。如果更新频率超过 30 秒，则每 30 秒仅为每个唯一的设备 ID 存储一次更新。 **注意** 在决定筛选方法和位置更新的频率时，请注意追踪应用程序的成本。您需要为每次位置更新付费，并根据每个链接的地理围栏集合评估位置更新一次付费。例如，使用基于时间的筛选时，如果您的跟踪链接到两个地理围栏集合，则每次位置更新都将计为一个位置更新请求和两次地理围栏收集评估。如果您报告设备每 5 秒更新一次位置并使用基于时间的筛选，则每台设备将按每小时 720 次位置更新和 1,440 次地理围栏评估计费。 您的计费不受每个集合中地理围栏数量的影响。由于每个地理围栏集合可能包含多达 50,000 个地理围栏，因此您可能需要尽可能将地理围栏合并成更少的集合，以降低地理围栏评估的成本。 默认情况下，每次被跟踪的设备进入或退出关联的地理围栏时，您都会收到 EventBridge 事件。有关更多信息，请参阅 [将跟踪器关联到地理围栏集合](associate-consumer.md)。 您可以为跟踪器资源的所有筛选位置更新启用事件。有关更多信息，请参阅 [为跟踪器启用更新事件](location-events.md#enable-update-events)。 **注意** 如果您希望使用自己的 AWS KMS 客户托管密钥加密数据，则默认情况下将禁用 “边界多边形查询” 功能。这是因为使用此边界多边形查询功能，您的设备位置表示不会使用您的 AWS KMS 托管密钥进行加密。但是，设备的确切位置仍使用您的托管密钥进行加密。 在创建或更新跟踪器时，您可以通过将 `KmsKeyEnableGeospatialQueries` 参数设置为 true 来选择使用“边界多边形查询”功能。 ------ #### [ Console ] **使用 Amazon Location 控制台创建跟踪器** 1. 打开 Amazon Location Service 控制台，网址为[https://console.aws.amazon.com/location/](https://console.aws.amazon.com/location/home)。 1. 在左侧导航窗格中，选择**跟踪器**。 1. 选择**创建跟踪器**。 1. 填写以下字段： + ****名称****——输入唯一名称。例如 *ExampleTracker*。最多 100 个字符。有效条目包括：字母数字字符、连字符、句号和下划线。 + ****描述****——输入可选描述。 1. 在**位置筛选**下，选择最适合您打算如何使用跟踪器资源的选项。如果未设置**位置筛选**，则默认设置为 `TimeBased`。想要了解更多信息，请参阅本指南 [Amazon Location Service 跟踪器](trackers.md) 和 Amazon Location Service Trackers API 参考中的 `[PositionFiltering](https://docs.aws.amazon.com/location/latest/APIReference/API_WaypointTracking_CreateTracker.html#location-WaypointTracking_CreateTracker-request-PositionFiltering)`。 1. （可选）在 **Tags (标签)** 下，输入标签 **Key (键)** 和 **Value (值)**。这会为您的新地理围栏集合添加一个标签。有关更多信息，请参阅 [如何使用标签](manage-resources.md#manage-resources_how-to)。 1. （可选）在“**客户托管密钥加密**”下，您可以选择**添加客户托管密钥**。这会添加一个对称的客户托管密钥，您可以通过默认 AWS 拥有的加密来创建、拥有和管理该密钥。想要了解更多信息，请参阅[加密静态数据](encryption-at-rest.md)。 1. （可选）在下方 **KmsKeyEnableGeospatialQueries**，您可以选择启用**地理空间查询**。这允许您使用边界多边形查询功能，同时使用客户 AWS KMS 托管密钥对数据进行加密。 **注意** 当您使用边界多边形查询功能时，您的设备位置表示不会使用您的 AWS KMS 托管密钥进行加密。但是，设备的确切位置仍使用您的托管密钥进行加密。 1. （可选）在**EventBridge 配置**下，您可以选择为筛选的职位更新启用 EventBridge 事件。每当该跟踪器中设备的位置更新符合位置筛选评估时，都会发送一个事件。 1. 选择**创建跟踪器**。 ------ #### [ API ] **使用 Amazon 位置创建追踪器 APIs** 使用 Amazon 位置追踪器 APIs中的`[CreateTracker](https://docs.aws.amazon.com/location/latest/APIReference/API_WaypointTracking_CreateTracker.html)`操作。 以下示例使用 API 请求创建名为的跟踪器*ExampleTracker*。跟踪器资源与[客户管理的 AWS KMS 密钥相关联，用于加密客户数据](encryption-at-rest.md)，并且不[在中启用位置更新 EventBridge](location-events.md#enable-update-events)。 ``` POST /tracking/v0/trackers Content-type: application/json { "TrackerName": "ExampleTracker", "Description": "string", "KmsKeyEnableGeospatialQueries": false, "EventBridgeEnabled": false, "KmsKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "PositionFiltering": "AccuracyBased", "Tags": { "string" : "string" } } ``` **在 `KmsKeyEnableGeospatialQueries` 启用状态下创建跟踪器** 以下示例将参数 `KmsKeyEnableGeospatialQueries` 设置为 true。这允许您使用边界多边形查询功能，同时使用客户 AWS KMS 管理的密钥对数据进行加密。 有关使用“边界面查询”功能的信息，请参阅 [列出您的设备位置](list-device-positions.md) **注意** 当您使用边界多边形查询功能时，您的设备位置表示不会使用您的 AWS KMS 托管密钥进行加密。但是，设备的确切位置仍使用您的托管密钥进行加密。 ``` POST /tracking/v0/trackers Content-type: application/json { "TrackerName": "ExampleTracker", "Description": "string", "KmsKeyEnableGeospatialQueries": true, "EventBridgeEnabled": false, "KmsKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "PositionFiltering": "AccuracyBased", "Tags": { "string" : "string" } } ``` ------ #### [ AWS CLI ] **使用 AWS CLI 命令创建跟踪器** 使用 `[create-tracker](https://docs.aws.amazon.com/cli/latest/reference/location/create-tracker.html)` 命令。 以下示例使用创建名 AWS CLI 为的跟踪器*ExampleTracker*。跟踪器资源与[客户管理的 AWS KMS 密钥相关联，用于加密客户数据](encryption-at-rest.md)，并且不[在中启用位置更新 EventBridge](location-events.md#enable-update-events)。 ``` aws location \ create-tracker \ --tracker-name "ExampleTracker" \ --position-filtering "AccuracyBased" \ --event-bridge-enabled false \ --kms-key-enable-geospatial-queries false \ --kms-key-id "1234abcd-12ab-34cd-56ef-1234567890ab" ``` **在 `KmsKeyEnableGeospatialQueries` 启用状态下创建跟踪器** 以下示例将参数 `KmsKeyEnableGeospatialQueries` 设置为 true。这允许您使用边界多边形查询功能，同时使用客户 AWS KMS 管理的密钥对数据进行加密。 有关使用“边界面查询”功能的信息，请参阅 [列出您的设备位置](list-device-positions.md) **注意** 当您使用边界多边形查询功能时，您的设备位置表示不会使用您的 AWS KMS 托管密钥进行加密。但是，设备的确切位置仍使用您的托管密钥进行加密。 ``` aws location \ create-tracker \ --tracker-name "ExampleTracker" \ --position-filtering "AccuracyBased" \ --event-bridge-enabled false \ --kms-key-enable-geospatial-queries true \ --kms-key-id "1234abcd-12ab-34cd-56ef-1234567890ab" ``` ------ **注意** 计费取决于您的使用情况。您可能会因为使用其他 AWS 服务而产生费用。想要了解更多信息，请参阅 [Amazon Location Service 定价](https://aws.amazon.com/location/pricing/)。 创建跟踪链接后，您可以通过选择编辑跟踪链接来**编辑****描述**、**位置筛选**和**EventBridge 配置**。 # 对您的请求进行身份验证 创建跟踪器资源并准备好开始根据地理围栏评估设备位置后，请选择如何对请求进行身份验证： + 要探索访问这些服务的方式，请参阅[使用 Amazon Location Service 进行身份验证](access.md)。 + 如果您想通过未经身份验证的请求发布设备位置，则可能需要使用 Amazon Cognito。 **示例**： 以下示例显示了使用 Amazon Cognito 身份池进行授权、使用 [AWS JavaScript SDK v3](https://aws.amazon.com/sdk-for-javascript/) 和 Amazon Location [Web](how-to-auth-helper.md#loc-sdk-auth-web)。 ``` import { LocationClient, BatchUpdateDevicePositionCommand } from "@aws-sdk/client-location"; import { withIdentityPoolId } from "@aws/amazon-location-utilities-auth-helper"; // Unauthenticated identity pool you created const identityPoolId = "us-east-1:1234abcd-5678-9012-abcd-sample-id"; // Create an authentication helper instance using credentials from Cognito const authHelper = await withIdentityPoolId(identityPoolId); const client = new LocationClient({ region: "us-east-1", // The region containing both the identity pool and tracker resource ...authHelper.getLocationClientConfig(), // Provides configuration required to make requests to Amazon Location }); const input = { TrackerName: "ExampleTracker", Updates: [ { DeviceId: "ExampleDevice-1", Position: [-123.4567, 45.6789], SampleTime: new Date("2020-10-02T19:09:07.327Z"), }, { DeviceId: "ExampleDevice-2", Position: [-123.123, 45.123], SampleTime: new Date("2020-10-02T19:10:32Z"), }, ], }; const command = new BatchUpdateDevicePositionCommand(input); // Send device position updates const response = await client.send(command); ``` # 使用设备位置更新跟踪器 要追踪您的设备，您可以将设备位置更新发布到跟踪器。您稍后可以从您的跟踪器资源中检索这些设备位置或设备位置历史记录。 每次位置更新都必须包括设备 ID、时间戳和位置。您可以选择添加其他元数据，包括精度和最多 3 个键值对供您自己使用。 如果您的跟踪器关联到一个或多个地理围栏集合，则系统将根据这些地理围栏对更新进行评估（遵循您为跟踪器指定的过滤规则）。如果设备突破了地理围栏区域（从该区域内部移动到外部，反之亦然），您将在其中收到事件。 EventBridge这些 `ENTER` 或 `EXIT` 事件包括位置更新详细信息，包括设备 ID、时间戳和任何相关的元数据。 **注意** 有关位置筛选的更多信息，请参阅 [创建跟踪器](start-create-tracker.md)。 有关地理围栏事件的更多信息，请参阅 [使用亚马逊对亚马逊定位服务事件做出反应 EventBridge](location-events.md)。 使用以下任一方法发送设备更新： + 向 Io@@ [T Core 资源发送 MQT AWS T 更新](tracking-using-mqtt.md)并将其链接到您的跟踪器资源。 + 使用亚马逊位置追踪器 API AWS CLI、或亚马逊位置来发送位置 APIs更新。您可以使用 APIs 从 iOS 或 Android 应用程序中调用。[AWS SDKs](dev-sdks.md) ------ #### [ API ] **使用 Amazon 位置发送职位更新 APIs** 使用 Amazon 位置追踪器 APIs中的`[BatchUpdateDevicePosition](https://docs.aws.amazon.com/location/latest/APIReference/API_WaypointTracking_BatchUpdateDevicePosition.html)`操作。 以下示例使用 API 请求向跟踪链接发布设备位置更新*ExampleTracker*。*ExampleDevice* ``` POST /tracking/v0/trackers/ExampleTracker/positions Content-type: application/json { "Updates": [ { "DeviceId": "1", "Position": [ -123.12245146162303, 49.27521118043802 ], "SampleTime": "2022-10-24T19:09:07.327Z", "PositionProperties": { "name" : "device1" }, "Accuracy": { "Horizontal": 10 } }, { "DeviceId": "2", "Position": [ -123.1230104928471, 49.27752402723152 ], "SampleTime": "2022-10-02T19:09:07.327Z" }, { "DeviceId": "3", "Position": [ -123.12325592118916, 49.27340530543111 ], "SampleTime": "2022-10-02T19:09:07.327Z" }, { "DeviceId": "4", "Position": [ -123.11958813096311, 49.27774641063121 ], "SampleTime": "2022-10-02T19:09:07.327Z" }, { "DeviceId": "5", "Position": [ -123.1277418058896, 49.2765989015285 ], "SampleTime": "2022-10-02T19:09:07.327Z" }, { "DeviceId": "6", "Position": [ -123.11964267059481, 49.274188155916534 ], "SampleTime": "2022-10-02T19:09:07.327Z" } ] } ``` ------ #### [ AWS CLI ] **使用 AWS CLI 命令发送位置更新** 使用 `[batch-update-device-position](https://docs.aws.amazon.com/cli/latest/reference/location/batch-update-device-position.html)` 命令。 以下示例使用 AWS CLI 向跟踪器发布*ExampleDevice-1*和*ExampleDevice-2*向跟踪器发布设备位置更新*ExampleTracker*。 ``` aws location batch-update-device-position \ --tracker-name ExampleTracker \ --updates '[{"DeviceId":"ExampleDevice-1","Position":[-123.123,47.123],"SampleTime":"2021-11-30T21:47:25.149Z"},{"DeviceId":"ExampleDevice-2","Position":[-123.123,47.123],"SampleTime":"2021-11-30T21:47:25.149Z","Accuracy":{"Horizontal":10.30},"PositionProperties":{"field1":"value1","field2":"value2"}}]' ``` ------ # 通过跟踪器获取设备的位置记录 您的 Amazon Location 跟踪器资源会将所有被追踪设备的位置记录保存 30 天。您可以从跟踪器资源中检索设备位置记录，包括所有关联的元数据。以下示例使用或 AWS CLI Amazon 地点 APIs。 ------ #### [ API ] **使用 Amazon 位置从追踪器获取设备位置记录 APIs** 使用 Amazon 位置追踪器 APIs中的`[GetDevicePositionHistory](https://docs.aws.amazon.com/location/latest/APIReference/API_WaypointTracking_GetDevicePositionHistory.html)`操作。 以下示例使用 API URI 请求*ExampleDevice*从名为的跟踪器获取设备位置历史记录，该跟踪器*ExampleTracker*起始于`19:05:07`（包含），结尾为`19:20:07`（独家）`2020–10–02`。 ``` POST /tracking/v0/trackers/ExampleTracker/devices/ExampleDevice/list-positions Content-type: application/json { "StartTimeInclusive": "2020-10-02T19:05:07.327Z", "EndTimeExclusive": "2020-10-02T19:20:07.327Z" } ``` ------ #### [ AWS CLI ] **使用 AWS CLI 命令从追踪器获取设备位置记录** 使用 `[get-device-position-history](https://docs.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html)` 命令。 以下示例使用*ExampleDevice*从名为 “*ExampleTracker*起始于`19:05:07`（包含）”、“独家” 结束于`19:20:07`（独家）的跟踪器获取设备位置历史记录`2020–10–02`。 AWS CLI ``` aws location \ get-device-position-history \ --device-id "ExampleDevice" \ --start-time-inclusive "2020-10-02T19:05:07.327Z" \ --end-time-exclusive "2020-10-02T19:20:07.327Z" \ --tracker-name "ExampleTracker" ``` ------ # 列出您的设备位置 您可以使用 ListDevicePositions API 或 Amazon 位置查看追踪器的设备位置 APIs列表。 AWS CLI当您调用 ListDevicePositions API 时，系统会返回与给定跟踪器关联的所有设备的最新位置列表。默认情况下，此 API 会在给定跟踪器的每页结果中返回 100 个最新的设备位置。要仅返回特定区域内的设备，请使用 `FilterGeometry` 参数创建“边界多边形查询”。这样，当你调用时 ListDevicePositions，只会返回多边形内的设备。 **注意** 如果您希望使用自己的 AWS KMS 客户托管密钥加密数据，则默认情况下将禁用 “边界多边形查询” 功能。这是因为使用此功能，您的设备位置表示不会使用您的 AWS KMS 托管密钥进行加密。但是，设备的确切位置仍使用您的托管密钥进行加密。 您可以选择加入“边界多边形查询”功能。这是通过在创建或更新跟踪器时将 `KmsKeyEnableGeospatialQueries` 参数设置为 true 来完成的。 ------ #### [ API ] 使用 Amazon 位置追踪器 APIs中的`[ListDevicePositions](https://docs.aws.amazon.com/location/latest/APIReference/API_WaypointTracking_ListDevicePositions.html)`操作。 以下示例是使用可选参数 `[FilterGeometry](https://docs.aws.amazon.com/)` 获取多边形区域中设备位置列表的 API 请求。该示例返回 `Polygon` 数组定义的区域中存在的 3 个设备位置。 ``` POST /tracking/v0/trackers/TrackerName/list-positions HTTP/1.1 Content-type: application/json { "FilterGeometry": { "Polygon": [ [ [ -123.12003339442259, 49.27425121147397 ], [ -123.1176984148229, 49.277063620879744 ], [ -123.12389509145294, 49.277954183760926 ], [ -123.12755921328647, 49.27554025235713 ], [ -123.12330236586217, 49.27211836076236 ], [ -123.12003339442259, 49.27425121147397 ] ] ] }, "MaxResults": 3, "NextToken": "1234-5678-9012" } ``` 以下为 `[ListDevicePositions](https://docs.aws.amazon.com/location/latest/APIReference/API_WaypointTracking_ListDevicePositions.html)` 响应示例： ``` { "Entries": [ { "DeviceId": "1", "SampleTime": "2022-10-24T19:09:07.327Z", "Position": [ -123.12245146162303, 49.27521118043802 ], "Accuracy": { "Horizontal": 10 }, "PositionProperties": { "name": "device1" } }, { "DeviceId": "3", "SampleTime": "2022-10-02T19:09:07.327Z", "Position": [ -123.12325592118916, 49.27340530543111 ] }, { "DeviceId": "2", "SampleTime": "2022-10-02T19:09:07.327Z", "Position": [ -123.1230104928471, 49.27752402723152 ] } ], "NextToken": "1234-5678-9012" } ``` ------ #### [ CLI ] 使用 `[list-trackers](https://docs.aws.amazon.com/cli/latest/reference/location/list-trackers.html)` 命令。 以下示例是 AWS CLI 获取多边形区域中的设备列表的示例。 ``` aws location list-device-positions TODO: add arguments add props for filter geo ``` ------