本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 位置
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 允许执行此规则操作的角色。
## 参数
使用此操作创建 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`
允许访问 Amazon Location Service 域的 IAM 角色。有关更多信息，请参阅 [要求](#location-rule-action-requirements)。
`timestamp`
对位置数据进行采样的时间。默认值是处理 MQTT 消息的时间。
`timestamp` 值由以下两个值组成：
+ `value`：返回长纪元时间值的表达式。您可以使用 [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) 函数从消息负载中传递的日期或时间值创建有效的时间戳。支持[替换模板](iot-substitution-templates.md)：是。
+ `unit`：（可选）`value` 中描述的表达式生成的时间戳值的精度。有效值：`SECONDS` \$1 `MILLISECONDS` \$1`MICROSECONDS` \$1 `NANOSECONDS`。默认值为 `MILLISECONDS`。仅支持[替换模板](iot-substitution-templates.md)：API 且 AWS CLI 仅支持。
`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 开发人员指南》](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html) 中的*什么是 Amazon Location Service？*。