本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
开启跟踪
本部分将指导您构建用于捕获设备位置的跟踪应用程序。
创建跟踪器
创建跟踪器资源以存储和处理来自您设备的位置更新。您可以使用 Amazon Location Service 控制台、AWS CLI 或 Amazon Location API。
存储在您的跟踪器资源中的每个位置更新都可能包括一个位置精度指标，以及最多三个与您要存储的位置或设备相关的元数据字段。元数据以键值对的形式存储，可以存储速度、方向、轮胎压力或发动机温度等信息。
跟踪器在收到的位置更新时对其进行过滤。这可以减少设备路径中的视觉噪音（称为抖动），并减少错误的地理围栏进入和退出事件的数量。这还可以减少启动的地理围栏评估的数量，从而帮助管理成本。
跟踪器提供三种位置筛选选项，以帮助管理成本并减少位置更新中的抖动。
-
基于精度——与任何提供精度测量的设备一起使用。大多数移动设备都提供此信息。每次位置测量的准确性受许多环境因素的影响，包括 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 事件。有关更多信息，请参阅 将跟踪器关联到地理围栏集合。
您可以为跟踪器资源的所有筛选位置更新启用事件。有关更多信息，请参阅 为跟踪器启用更新事件。
如果您希望使用自己的 AWS KMS 客户托管密钥加密数据，则默认情况下将禁用“边界多边形查询”功能。这是因为使用此“边界多边形查询”功能，您的设备位置的表示不会使用您的 AWS KMS 托管密钥进行加密。但是，设备的确切位置仍使用您的托管密钥进行加密。
在创建或更新跟踪器时，您可以通过将 KmsKeyEnableGeospatialQueries 参数设置为 true 来选择使用“边界多边形查询”功能。
- Console
-
使用 Amazon Location 控制台创建跟踪器
-
打开 Amazon Location Service 控制台：https://console.aws.amazon.com/location/。
-
在左侧导航窗格中，选择跟踪器。
-
选择创建跟踪器。
-
填写以下字段：
-
在位置筛选下，选择最适合您打算如何使用跟踪器资源的选项。如果未设置位置筛选，则默认设置为 TimeBased。想要了解更多信息，请参阅本指南 跟踪器 和 Amazon Location Service Trackers API 参考中的 PositionFiltering。
-
（可选）在 Tags (标签) 下，输入标签 Key (键) 和 Value (值)。这会为您的新地理围栏集合添加一个标签。有关更多信息，请参阅标记资源。
-
（可选）在“客户托管密钥加密”下，您可以选择添加客户托管密钥。这添加了一个您创建、拥有和管理的对称客户托管密钥，该密钥是在默认 AWS 拥有的加密基础上创建、拥有和管理的。想要了解更多信息，请参阅加密静态数据。
-
（可选）在下方 KmsKeyEnableGeospatialQueries，您可以选择启用地理空间查询。这允许您使用“边界多边形查询”功能，同时使用客户的 AWS KMS 托管密钥对数据进行加密。
当您使用“边界多边形查询”功能时，您的设备位置表示不会使用您的 AWS KMS 托管密钥进行加密。但是，设备的确切位置仍使用您的托管密钥进行加密。
-
（可选）在EventBridge 配置下，您可以选择为筛选的职位更新启用 EventBridge 事件。每当该跟踪器中设备的位置更新符合位置筛选评估时，都会发送一个事件。
-
选择创建跟踪器。
- API
-
使用 Amazon Location API 创建跟踪器
使用 Amazon Location 跟踪器 API 中的 CreateTracker 操作。
以下示例使用 API 请求创建名为的跟踪器ExampleTracker。跟踪器资源与客户管理的AWS KMS密钥相关联，用于加密客户数据，并且不在中启用位置更新 EventBridge。
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 托管的密钥对数据进行加密。
有关使用“边界面查询”功能的信息，请参阅
当您使用“边界多边形查询”功能时，您的设备位置表示不会使用您的 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 命令。
以下示例使用创建名AWS CLI为的跟踪器ExampleTracker。跟踪器资源与客户管理的AWS KMS密钥相关联，用于加密客户数据，并且不在中启用位置更新 EventBridge。
aws location \
create-tracker \
--tracker-name "ExampleTrackerAccuracyBased" \
--event-bridge-enabled false \
--kms-key-enable-geospatial-queries false \
--kms-key-id "1234abcd-12ab-34cd-56ef-1234567890ab"
在 KmsKeyEnableGeospatialQueries 启用状态下创建跟踪器
以下示例将参数 KmsKeyEnableGeospatialQueries 设置为 true。这允许您使用“边界多边形查询”功能，同时使用客户 AWS KMS 托管的密钥对数据进行加密。
有关使用“边界面查询”功能的信息，请参阅
当您使用“边界多边形查询”功能时，您的设备位置表示不会使用您的 AWS KMS 托管密钥进行加密。但是，设备的确切位置仍使用您的托管密钥进行加密。
aws location \
create-tracker \
--tracker-name "ExampleTrackerAccuracyBased" \
--event-bridge-enabled false \
--kms-key-enable-geospatial-queries true \
--kms-key-id "1234abcd-12ab-34cd-56ef-1234567890ab"
创建跟踪链接后，您可以通过选择编辑跟踪链接来编辑描述、位置筛选和EventBridge 配置。
对您的请求进行身份验证
创建跟踪器资源并准备好开始根据地理围栏评估设备位置后，请选择如何对请求进行身份验证：
-
要探索访问服务的方式，请参阅 Accessing Amazon Location Service。
-
如果您想通过未经身份验证的请求发布设备位置，则可能需要使用 Amazon Cognito。
示例
以下示例展示了如何使用 Amazon Cognito 身份池进行授权、使用 AW S JavaScript 软件开发工具包 v3 和亚马逊位置。身份验证帮助程序
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、时间戳和任何相关的元数据。
使用以下任一方法发送设备更新：
- API
-
使用 Amazon Location API 发送位置更新
使用 Amazon Location 跟踪器 API 中的 BatchUpdateDevicePosition 操作。
以下示例使用 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 命令。
以下示例使用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 Location API。
- API
-
使用 Amazon Location API 从跟踪器获取设备位置记录
使用 Amazon Location 跟踪器 API 中的 GetDevicePositionHistory 操作。
以下示例使用 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 命令。
以下示例使用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
列出您的设备位置
您可以通过 API 使用或 Amazon Locat AWS CLI ion API 查看追踪器的设备位置列表。 ListDevicePositions 当您调用 ListDevicePositions API 时，系统会返回与给定跟踪器关联的所有设备的最新位置列表。默认情况下，此 API 会在给定跟踪器的每页结果中返回 100 个最新的设备位置。要仅返回特定区域内的设备，请使用 FilterGeometry 参数创建“边界多边形查询”。这样，当你调用时 ListDevicePositions，只会返回多边形内的设备。
如果您希望使用自己的 AWS KMS 客户托管密钥加密数据，则默认情况下将禁用“边界多边形查询”功能。这是因为使用此功能，您的设备位置表示不会使用您的 AWS KMS 托管密钥进行加密。但是，设备的确切位置仍使用您的托管密钥进行加密。
您可以选择加入“边界多边形查询”功能。这是通过在创建或更新跟踪器时将 KmsKeyEnableGeospatialQueries 参数设置为 true 来完成的。
- API
-
使用 Amazon Location 跟踪器 API 中的 ListDevicePositions 操作。
以下示例是使用可选参数 FilterGeometry 获取多边形区域中设备位置列表的 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 响应示例：
{
"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 命令。
以下示例是获取多边形区域中的设备列表的 AWS CLI。
aws location list-device-positions TODO: add arguments add props for filter geo
