本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用设备位置解析 AWS IoT Core 设备位置 MQTT 主题
<a name="device-location-reserved-topics"></a>

您可以使用保留的 MQTT 主题通过设备定位功能获取设备的最新位置信息。 AWS IoT Core 

## 设备位置 MQTT 主题的格式
<a name="device-location-topics-format"></a>

 AWS IoT Core 设备定位的保留主题使用以下前缀：

`$aws/device_location/{{{customer_device_id}}}/`

要创建完整的主题，请先将 `{{customer_device_id}}` 替换为用于识别设备的唯一 ID。我们建议您指定`WirelessDeviceId`，例如为 LoRa WAN 和 Sidewalk 设备指定`{{thingName}}`，以及您的设备是否已注册为 AWS IoT 事物。然后在主题后面附加主题存根，如下一节所示的 `get_position_estimate` 或 `get_position_estimate/accepted`。

**注意**  
`{{{customer_device_id}}}` 仅可包含字母、数字和短划线。订阅设备位置主题时，只能使用加号（\+）作为通配符。例如，您可以将 `+` 通配符用于 `{{{customer_device_id}}}` 来获取设备的位置信息。当您订阅主题 `$aws/device_location/{{+}}/get_position_estimate/accepted` 时，系统将发布一条消息，其中包含与任何设备 ID 匹配的设备的位置信息（如果成功解析）。

以下是用于与 AWS IoT Core 设备位置进行交互的保留主题。


**设备位置 MQTT 主题**  

| Topic | 允许的操作 | 说明 | 
| --- | --- | --- | 
|  \$aw {{customer\_device\_id}} s/device\_location/ /get\_position\_  | 发布 |  设备向本主题发布信息，以获取扫描的原始测量数据，以便通过 “ AWS IoT Core 设备位置” 进行解析。  | 
|  \$aw {{customer\_device\_id}} s/device\_location/ /get\_position\_estimat  | Subscribe |  AWS IoT Core 设备定位成功解析设备位置后，会向该主题发布位置信息。  | 
|  \$aw {{customer\_device\_id}} s/device\_location/ /get\_position\_estimat  | Subscribe |  AWS IoT Core 当设备位置无法解析设备位置时，它会将错误信息发布到此主题。  | 

## 设备位置 MQTT 主题的策略
<a name="device-location-topics-policy"></a>

要接收来自设备位置主题的消息，您的设备必须使用允许其连接到 AWS IoT 设备网关并订阅 MQTT 主题的策略。

以下是接收各种主题的消息时需要的策略示例。

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Publish"
            ],
            "Resource": [
                "arn:aws:iot:{{us-east-1}}:123456789012:topic/$aws/device_location/device-123/get_position_estimate"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws:iot:{{us-east-1}}:123456789012:topic/$aws/device_location/device-123/get_position_estimate/accepted",
                "arn:aws:iot:{{us-east-1}}:123456789012:topic/$aws/device_location/device-123/get_position_estimate/rejected"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws:iot:{{us-east-1}}:123456789012:topicfilter/$aws/device_location/device-123/get_position_estimate/accepted",
                "arn:aws:iot:{{us-east-1}}:123456789012:topicfilter/$aws/device_location/device-123/get_position_estimate/rejected"
            ]
        }
    ]
}
```

## 设备位置主题和有效载荷
<a name="device-location-topics-payload"></a>

下面显示了 “ AWS IoT Core 设备位置” 主题、其消息负载的格式以及每个主题的示例策略。

**Topics**
+ [/get\_position\_estimate](#get-position-estimate)
+ [/get\_position\_estimate/accepted](#get-position-estimate-accepted)
+ [/get\_position\_estimate/rejected](#get-position-estimate-rejected)

### /get\_position\_estimate
<a name="get-position-estimate"></a>

向此主题发布一条消息，以获取设备上的原始测量数据，以供 AWS IoT Core 设备位置解析。

```
$aws/device_location/{{customer_device_id}}/get_position_estimate
```

AWS IoT Core “设备位置” 通过发布到[/get\_position\_estimate/accepted](#get-position-estimate-accepted)或来响应[/get\_position\_estimate/rejected](#get-position-estimate-rejected)。

**注意**  
发布到该主题的消息必须是有效的 JSON 有效载荷。如果输入消息不是有效的 JSON 格式，则不会得到任何响应。有关更多信息，请参阅[消息有效载荷](#get-position-estimate-payload)。

#### 消息负载
<a name="get-position-estimate-payload"></a>

消息负载格式遵循与 AWS IoT Wireless API 操作请求正文类似的结构[https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html)。其中包含：
+ 一个可选 `Timestamp` 字符串，对应于解析该位置的日期和时间。`Timestamp` 字符串的最小长度可以为 1，最大长度可以为 10。
+ 一个可选 `MessageId` 字符串，可用于将请求映射到响应。如果您指定此字符串，则发布到 `get_position_estimate/accepted` 或 `get_position_estimate/rejected` 主题的消息将包含此 `MessageId`。`MessageID` 字符串的最小长度可以为 1，最大长度可以为 256。
+ 来自包含以下一种或多种测量类型的设备的测量数据：
  + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_WiFiAccessPoint.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_WiFiAccessPoint.html)
  + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CellTowers.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CellTowers.html)
  + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_Ip.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_Ip.html)
  + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_Gnss.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_Gnss.html)

以下内容显示了示例消息有效载荷示例。

```
{
    "Timestamp": {{"1664313161"}},               
    "MessageId": {{"ABCD1"}},                
    "WiFiAccessPoints":  [                           
        {
            "MacAddress": "{{A0:EC:F9:1E:32:C1}}",                   
            "Rss": {{-66}} 
        }
    ],    
    "Ip":{
        "IpAddress": {{"54.192.168.0"}}                         
    },
    "Gnss":{
      "Payload":{{"8295A614A2029517F4F77C0A7823B161A6FC57E25183D96535E3689783F6CA48"}},
      "CaptureTime":{{1354393948}}
    }
}
```

#### 策略示例
<a name="get-position-estimate-policy"></a>

以下是所需策略的示例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Publish"
            ],
            "Resource": [
                "arn:aws:iot:{{us-east-1}}:123456789012:topic/$aws/device_location/device-123/get_position_estimate"
            ]
        }
    ]
}
```

### /get\_position\_estimate/accepted
<a name="get-position-estimate-accepted"></a>

AWS IoT Core 设备定位在返回设备已解析的位置信息时，会发布对此主题的回复。位置信息以 [GeoJSON 格式](https://geojson.org/)返回。

```
$aws/device_location/{{customer_device_id}}/get_position_estimate/accepted
```

下面显示了消息有效载荷和示例策略。

#### 消息负载
<a name="get-position-estimate-accepted-payload"></a>

以下是 GeoJSON 格式的消息有效载荷示例。如果您在原始测量数据`MessageId`中指定了，并且 AWS IoT Core 设备位置成功解析了位置信息，则消息负载将返回相同`MessageId`的信息。

```
{
    "coordinates": [
        13.37704086303711,
        52.51865005493164
    ],
    "type": "Point",
    "properties": {
        "verticalAccuracy": 707,
        "verticalConfidenceLevel": 0.68,
        "horizontalAccuracy": 389,
        "horizontalConfidenceLevel": 0.68,
        "country": "USA",
        "state": "CA",
        "city": "Sunnyvalue",
        "postalCode": "91234",        
        "timestamp": "2022-11-18T14:03:57.391Z",
        "messageId": "ABCD1"
    }
}
```

#### 策略示例
<a name="get-position-estimate-accepted-policy"></a>

以下是所需策略的示例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws:iot:{{us-east-1}}:123456789012:topicfilter/$aws/device_location/device-123/get_position_estimate/accepted"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws:iot:{{us-east-1}}:123456789012:topic/$aws/device_location/device-123/get_position_estimate/accepted"
            ]
        }
    ]
}
```

### /get\_position\_estimate/rejected
<a name="get-position-estimate-rejected"></a>

AWS IoT Core 当设备位置无法解析设备位置时，它会发布针对此主题的错误响应。

```
$aws/device_location/{{customer_device_id}}/get_position_estimate/rejected
```

下面显示了消息有效载荷和示例策略。有关这些错误的信息，请参阅 [对解析位置时出现的错误进行故障排除](device-location-resolve-solvers.md#location-resolve-troubleshoot)。

#### 消息负载
<a name="get-position-estimate-rejected-payload"></a>

以下是提供错误代码和消息的消息负载示例，这表明了 AWS IoT Core 设备定位未能解析位置信息的原因。如果您`MessageId`在提供原始测量数据时指定了，而 AWS IoT Core 设备位置未能解析位置信息，则消息负载中将返回相同`MessageId`的信息。

```
{
    "errorCode": 500,
    "errorMessage":"Internal server error",
    "messageId": "ABCD1"
}
```

#### 策略示例
<a name="get-position-estimate-rejected-policy"></a>

以下是所需策略的示例：

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Subscribe"
      ],
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/device_location/device-123/get_position_estimate/rejected"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iot:Receive"
      ],
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/device_location/device-123/get_position_estimate/rejected"
      ]
    }
  ]
}
```