本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 開始使用 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、 或 Amazon Location 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 秒，則每個唯一裝置 ID 每 30 秒只會存放一次更新。 **注意** 在決定您的篩選方法和位置更新的頻率時，請注意追蹤應用程式的成本。系統會針對每個位置更新向您收費，並針對每個連結的地理圍欄集合評估位置更新向您收費一次。例如，使用以時間為基礎的篩選時，如果您的追蹤器連結至兩個地理圍欄集合，則每個位置更新都會計為一個位置更新請求和兩個地理圍欄集合評估。如果您要每 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. 開啟位於 https：//[https://console.aws.amazon.com/location/](https://console.aws.amazon.com/location/home) 的 Amazon Location Service 主控台。 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 Location APIs 建立追蹤器** 從 Amazon Location Trackers 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)。 如需地理圍欄事件的詳細資訊，請參閱 [使用 Amazon EventBridge 對 Amazon Location Service 事件做出反應](location-events.md)。 使用下列其中一種方法來傳送裝置更新： + [將 MQTT 更新](tracking-using-mqtt.md)傳送至 AWS IoT Core 資源，並將其連結至您的追蹤器資源。 + 使用 或 Amazon Location API，使用 Amazon Location Trackers APIs AWS CLI傳送位置更新。您可以使用 [AWS SDKs](dev-sdks.md) 從 iOS 或 Android 應用程式呼叫 APIs。 ------ #### [ API ] **使用 Amazon Location APIs 傳送位置更新** 從 Amazon Location Trackers APIs使用 `[BatchUpdateDevicePosition](https://docs.aws.amazon.com/location/latest/APIReference/API_WaypointTracking_BatchUpdateDevicePosition.html)`操作。 下列範例使用 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](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 Location APIs。 ------ #### [ API ] **使用 Amazon Location APIs 從追蹤器取得裝置位置歷史記錄** 從 Amazon Location Trackers APIs使用 `[GetDevicePositionHistory](https://docs.aws.amazon.com/location/latest/APIReference/API_WaypointTracking_GetDevicePositionHistory.html)`操作。 下列範例使用 API URI 請求，從名為 *ExampleTracker* 的追蹤器取得 *ExampleDevice* 的裝置位置歷史記錄，從 `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)` 命令。 下列範例使用 從名為 *ExampleTracker* 的追蹤器 AWS CLI 取得 *ExampleDevice* 的裝置位置歷史記錄，從 `19:05:07`（包含） 開始，並於 `19:20:07`（排除） 結束`2020–10–02`。 ``` 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" ``` ------ # 列出您的裝置位置 您可以使用 AWS CLI或 Amazon Location APIs 搭配 ListDevicePositions API 檢視追蹤器的清單裝置位置。當您呼叫 ListDevicePositions API 時，會傳回與指定追蹤器關聯之所有裝置的最新位置清單。根據預設，此 API 會傳回指定追蹤器每頁結果的 100 個最新裝置位置。若要只傳回特定區域內的裝置，請使用 `FilterGeometry` 參數來建立邊界多邊形查詢。這樣當您呼叫 ListDevicePositions 時，只會傳回多邊形內的裝置。 **注意** 如果您想要使用自己的 AWS KMS 客戶受管金鑰加密資料，則邊界多邊形查詢功能預設為停用。這是因為使用此功能時，不會使用您的 AWS KMS 受管金鑰來加密裝置位置的表示。不過，確切的裝置位置； 仍會使用您的受管金鑰加密。 您可以選擇加入邊界多邊形查詢功能。方法是在建立或更新追蹤器時，將 `KmsKeyEnableGeospatialQueries` 參數設定為 true。 ------ #### [ API ] 從 Amazon Location Trackers APIs使用 `[ListDevicePositions](https://docs.aws.amazon.com/location/latest/APIReference/API_WaypointTracking_ListDevicePositions.html)`操作。 下列範例是使用選用參數 取得多邊形區域中裝置位置清單的 API 請求`[FilterGeometry](https://docs.aws.amazon.com/)`。此範例會傳回`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 ``` ------