本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Location
Location (`location`) (位置) 動作會將您的地理位置資料傳送至 [Amazon Location Service](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html)。
## 要求
此規則動作具有下列需求：
+ AWS IoT 可以擔任以執行`geo:BatchUpdateDevicePosition`操作的 IAM 角色。如需詳細資訊，請參閱[授予 AWS IoT 規則所需的存取權](iot-create-role.md)。
在 AWS IoT 主控台中，您可以選擇或建立角色，以允許 AWS IoT 執行此規則動作。
## Parameters
當您使用此動作建立 AWS IoT 規則時，您必須指定下列資訊：
`deviceId`
提供位置資料的裝置唯一 ID。如需詳細資訊，請參閱《Amazon Location Service API 參考》**中的 [https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html](https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html)。
支援[替代範本](iot-substitution-templates.md)：是
`latitude`
此字串評估為雙精確度值，該值代表裝置位置的緯度。
支援[替代範本](iot-substitution-templates.md)：是
`longitude`
此字串評估為雙精確度值，該值代表裝置位置的經度。
支援[替代範本](iot-substitution-templates.md)：是
`roleArn`
IAM 角色，允許存取 Amazon Location Service 網域。如需詳細資訊，請參閱[要求](#location-rule-action-requirements)。
`timestamp`
對位置資料進行取樣的時間。預設值是處理 MQTT 訊息的時間。
`timestamp` 值包含以下兩個值：
+ `value`：傳回一個很長的 Epoch 時間值的表達式。您可使用 [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) 函數，從訊息承載中傳遞的日期或時間建立有效的時間戳記。支援[替代範本](iot-substitution-templates.md)：是。
+ `unit`：(選擇性) `value` 中所述運算式產生的 timestamp 值的精確度。有效值：`SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS`。預設值為 `MILLISECONDS`。支援[替代範本](iot-substitution-templates.md)： AWS CLI 僅限 API 和 。
`trackerName`
在已更新位置的 Amazon Location 中的追蹤器資源名稱。如需詳細資訊，請參閱《Amazon Location Service 開發人員指南》**中的[追蹤器](https://docs.aws.amazon.com//location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview)。
僅支援[替代範本](iot-substitution-templates.md)：API 和 AWS CLI
## 範例
下列 JSON 範例定義 AWS IoT 規則中的位置動作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123454962127:role/service-role/ExampleRole",
"trackerName": "MyTracker",
"deviceId": "001",
"sampleTime": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "-12.3456",
"longitude": "65.4321"
}
}
]
}
}
```
下列 JSON 範例使用 AWS IoT 規則中的替代範本定義位置動作。
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123456789012:role/service-role/ExampleRole",
"trackerName": "${TrackerName}",
"deviceId": "${DeviceID}",
"timestamp": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "${get(position, 0)}",
"longitude": "${get(position, 1)}"
}
}
]
}
}
```
下列 MQTT 承載範例顯示上述範例中的替代範本如何存取資料。您可以使用 [https://docs.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html](https://docs.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html) CLI 命令來驗證 MQTT 承載資料是否已在您的位置追蹤器中進行傳送。
```
{
"TrackerName": "mytracker",
"DeviceID": "001",
"position": [
"-12.3456",
"65.4321"
]
}
```
```
aws location get-device-position-history --device-id 001 --tracker-name mytracker
```
```
{
"DevicePositions": [
{
"DeviceId": "001",
"Position": [
-12.3456,
65.4321
],
"ReceivedTime": "2022-11-11T01:31:54.464000+00:00",
"SampleTime": "2022-11-11T01:31:54.308000+00:00"
}
]
}
```
## 另請參閱
+ 在《Amazon Location Service 開發人員指南》**中的[什麼是 Amazon Location Service？](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html)。