本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用裝置位置 MQTT 主題解決 AWS IoT Core 裝置位置
<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。如果您的裝置已註冊為 AWS IoT 物件`WirelessDeviceId`，建議您指定 `{{thingName}}`，例如 for LoRaWAN 和 Sidewalk 裝置，以及 。然後，您可以將主題附加到主題 Stub，例如 `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 主題**  

| 主題 | 允許操作 | Description | 
| --- | --- | --- | 
| $aws/device\_location/{{customer\_device\_id}}/get\_position\_estimate | 發布 | 裝置會發佈至此主題，以取得 AWS IoT Core 裝置位置要解析的掃描原始測量資料。 | 
| $aws/device\_location/{{customer\_device\_id}}/get\_position\_estimate/accepted | 訂閱 | AWS IoT Core 裝置位置成功解析裝置位置時，會將位置資訊發佈至此主題。 | 
| $aws/device\_location/{{customer\_device\_id}}/get\_position\_estimate/rejected | 訂閱 | 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 Device Location 成功解析了位置資訊，則訊息承載會傳回相同的`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"
      ]
    }
  ]
}
```