创建跟踪器创建未经身份验证的身份池使用设备位置更新跟踪器获取设备的位置记录列出您的设备位置

开始使用 Amazon 位置进行追踪

本部分将指导您构建用于捕获设备位置的跟踪应用程序。

主题

创建跟踪器
对您的请求进行身份验证
使用设备位置更新跟踪器
通过跟踪器获取设备的位置记录
列出您的设备位置

创建跟踪器

创建跟踪器资源以存储和处理来自您设备的位置更新。您可以使用 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 事件。有关更多信息，请参阅教程：将追踪器关联到 Amazon Location 中的地理围栏集合。

您可以为跟踪器资源的所有筛选位置更新启用事件。有关更多信息，请参阅为跟踪器启用更新事件。

注意

如果您希望使用自己的 AWS KMS 客户托管密钥加密数据，则默认情况下将禁用 “边界多边形查询” 功能。这是因为使用此边界多边形查询功能，您的设备位置表示不会使用您的 AWS KMS 托管密钥进行加密。但是，设备的确切位置仍使用您的托管密钥进行加密。

在创建或更新跟踪器时，您可以通过将 KmsKeyEnableGeospatialQueries 参数设置为 true 来选择使用“边界多边形查询”功能。

Console

使用 Amazon Location 控制台创建跟踪器

打开 Amazon Location Service 控制台，网址为https://console.aws.amazon.com/location/。
在左侧导航窗格中，选择跟踪器。
选择创建跟踪器。
填写以下字段：
- 名称——输入唯一名称。例如，ExampleTracker。最多 100 个字符。有效条目包括：字母数字字符、连字符、句号和下划线。
- 描述——输入可选描述。
在位置筛选下，选择最适合您打算如何使用跟踪器资源的选项。如果未设置位置筛选，则默认设置为 TimeBased。有关更多信息，请参阅在 Amazon Location Service 中了解追踪器本指南和PositionFiltering《Amazon Location Service 追踪器API参考》。
（可选）在 Tags (标签) 下，输入标签 Key (键) 和 Value (值)。这会为您的新地理围栏集合添加一个标签。有关更多信息，请参阅标记资源。
（可选）在“客户托管密钥加密”下，您可以选择添加客户托管密钥。这会添加一个对称的客户托管密钥，您可以通过默认 AWS 拥有的加密来创建、拥有和管理该密钥。想要了解更多信息，请参阅加密静态数据。
（可选）在下方 KmsKeyEnableGeospatialQueries，您可以选择启用地理空间查询。这允许您使用边界多边形查询功能，同时使用客户AWSKMS管理的密钥对数据进行加密。

注意
当您使用“边界多边形查询”功能时，您的设备位置表示不会使用您的 AWS KMS 托管密钥进行加密。但是，设备的确切位置仍使用您的托管密钥进行加密。
（可选）在EventBridge 配置下，您可以选择为筛选的职位更新启用 EventBridge 事件。每当该跟踪器中设备的位置更新符合位置筛选评估时，都会发送一个事件。
选择创建跟踪器。

API

使用 Amazon 位置创建追踪器 APIs

使用 Amazon 位置追踪器APIs中的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 "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 管理的密钥对数据进行加密。

有关使用“边界面查询”功能的信息，请参阅列出您的设备位置

注意

当您使用边界多边形查询功能时，您的设备位置表示不会使用您的 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 定价。

创建跟踪链接后，您可以通过选择编辑跟踪链接来编辑描述、位置筛选和EventBridge 配置。

对您的请求进行身份验证

创建跟踪器资源并准备好开始根据地理围栏评估设备位置后，请选择如何对请求进行身份验证：

要探索访问服务的方式，请参阅 Accessing Amazon Location Service。

如果您想通过未经身份验证的请求发布设备位置，则可能需要使用 Amazon Cognito。

示例

以下示例显示了使用 Amazon Cognito 身份池进行授权、使用 AWS JavaScript SDKv3 和亚马逊位置。JavaScript 身份验证助手


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、时间戳和任何相关的元数据。

注意

有关位置筛选的更多信息，请参阅创建跟踪器。

有关地理围栏事件的更多信息，请参阅通过亚马逊对亚马逊定位服务事件做出反应 EventBridge。

使用以下任一方法发送设备更新：

向 AWS IoT Core 资源@@ 发送MQTT更新并将其链接到您的跟踪器资源。
使用亚马逊位置追踪器API AWS CLI、或亚马逊位置信息发送位置APIs更新。您可以使用APIs从 iOS 或 Android 应用程序中调用。AWS SDKs

API

使用 Amazon 位置发送职位更新 APIs

使用 Amazon 位置追踪器APIs中的BatchUpdateDevicePosition操作。

以下示例使用API请求发布的设备位置更新 ExampleDevice 到追踪器 ExampleTracker.


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 地点APIs。

列出您的设备位置

您可以使用或 Amazon 位置查看追踪器的 AWS CLI设备位置APIs列表 ListDevicePositions API。当您调用时 ListDevicePositions API，系统会返回与给定跟踪器关联的所有设备的最新位置列表。默认情况下，这API会在给定跟踪链接的每页结果中返回 100 个最新的设备位置。要仅返回特定区域内的设备，请使用 FilterGeometry 参数创建“边界多边形查询”。这样，当你调用时 ListDevicePositions，只会返回多边形内的设备。

注意

如果您希望使用自己的 AWS KMS 客户托管密钥加密数据，则默认情况下将禁用 “边界多边形查询” 功能。这是因为使用此功能，您的设备位置表示不会使用您的 AWS KMS 托管密钥进行加密。但是，设备的确切位置仍使用您的托管密钥进行加密。

您可以选择加入“边界多边形查询”功能。这是通过在创建或更新跟踪器时将 KmsKeyEnableGeospatialQueries 参数设置为 true 来完成的。

API

使用 Amazon 位置追踪器APIs中的ListDevicePositions操作。

以下示例API请求使用可选参数获取多边形区域中的设备位置列表。FilterGeometry该示例返回 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

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

添加地理围栏

教程：将追踪器关联到地理围栏集合