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

# Device Shadow MQTT 主題
<a name="device-shadow-mqtt"></a>

Device Shadow 服務會使用預留的 MQTT 主題，讓應用程式與裝置可取得、更新或刪除裝置 (影子) 的狀態資訊。

在影子主題上發佈和訂閱需要主題為基礎的授權。 AWS IoT 有權新增主題到現有的主題結構。因此，我們建議您避免使用萬用字元訂閱影子主題。例如，避免像 一樣訂閱主題篩選條件，`$aws/things/thingName/shadow/#`因為當 AWS IoT 引入新的影子主題時，符合此主題篩選條件的主題數量可能會增加。關於發佈至這些主題的訊息範例，請參閱 [與影子互動](device-shadow-data-flow.md)。

影子可以為已命名或未命名 (典型)。各影子所使用的主題只有在主題字首中有所不同。此表格會顯示每種影子類型所使用的主題字首。


| *ShadowTopicPrefix* 值 | 影子類型 | 
| --- | --- | 
| \$1aws/things/thingName/shadow | 未命名 (經典) 影子 | 
| \$1aws/things/thingName/shadow/name/shadowName | 已命名影子 | 

若要建立完整的主題，請在 `ShadowTopicPrefix` 選取您要參照的影子類型、用對應值取代 `thingName` 及 `shadowName` (如適用) 的影子類型，然後將該類型附加至主題 stub，如下節所示。

下列為用來與影子互動的 MQTT 主題。

**Topics**
+ [/get](#get-pub-sub-topic)
+ [/get/accepted](#get-accepted-pub-sub-topic)
+ [/get/rejected](#get-rejected-pub-sub-topic)
+ [/update](#update-pub-sub-topic)
+ [/update/delta](#update-delta-pub-sub-topic)
+ [/update/accepted](#update-accepted-pub-sub-topic)
+ [/update/documents](#update-documents-pub-sub-topic)
+ [/update/rejected](#update-rejected-pub-sub-topic)
+ [/delete](#delete-pub-sub-topic)
+ [/delete/accepted](#delete-accepted-pub-sub-topic)
+ [/delete/rejected](#delete-rejected-pub-sub-topic)

## /get
<a name="get-pub-sub-topic"></a>

發佈空白訊息至此主題可取得裝置的影子：

```
ShadowTopicPrefix/get
```

AWS IoT 透過發佈至 [/get/accepted](#get-accepted-pub-sub-topic)或 來回應 [/get/rejected](#get-rejected-pub-sub-topic)。

### 範例 政策
<a name="get-policy"></a>

以下為所需政策的範例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Publish"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get"
            ]
        }
    ]
}
```

## /get/accepted
<a name="get-accepted-pub-sub-topic"></a>

AWS IoT 傳回裝置的影子時， 會將回應影子文件發佈至此主題：

```
ShadowTopicPrefix/get/accepted
```

如需詳細資訊，請參閱[回應狀態文件](device-shadow-document.md#device-shadow-example-response-json)。

### 範例 政策
<a name="get-accepted-policy"></a>

以下為所需政策的範例：

****  

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

## /get/rejected
<a name="get-rejected-pub-sub-topic"></a>

AWS IoT 當無法傳回裝置的影子時， 會將錯誤回應文件發佈至此主題：

```
ShadowTopicPrefix/get/rejected
```

如需詳細資訊，請參閱[錯誤回應文件](device-shadow-document.md#device-shadow-example-error-json)。

### 範例 政策
<a name="get-rejected-policy"></a>

以下為所需政策的範例：

****  

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

## /update
<a name="update-pub-sub-topic"></a>

對此主題發佈要求狀態文件，以更新裝置的影子：

```
ShadowTopicPrefix/update
```

訊息內文包含[部分請求狀態文件](device-shadow-document.md#device-shadow-example-request-json)。

嘗試更新裝置狀態的用戶端會發送一個 JSON 請求狀態文件，其 `desired` 屬性如下：

```
{
  "state": {
    "desired": {
      "color": "red",
      "power": "on"
    }
  }
}
```

更新其影子的裝置將發送一個 JSON 請求狀態文件與該 `reported` 屬性，例如：

```
{
  "state": {
    "reported": {
      "color": "red",
      "power": "on"
    }
  }
}
```

AWS IoT 透過發佈至 [/update/accepted](#update-accepted-pub-sub-topic)或 來回應 [/update/rejected](#update-rejected-pub-sub-topic)。

### 範例 政策
<a name="update-policy"></a>

以下為所需政策的範例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Publish"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update"
            ]
        }
    ]
}
```

## /update/delta
<a name="update-delta-pub-sub-topic"></a>

AWS IoT 當回應狀態文件接受裝置影子的變更，且回應狀態文件包含 `desired`和 `reported` 狀態的不同值時，會將回應狀態文件發佈至此主題：

```
ShadowTopicPrefix/update/delta
```

訊息緩衝區包含 [/delta response state document](device-shadow-document.md#device-shadow-example-response-json-delta)。

### 訊息內文詳細資料
<a name="update-delta-rules"></a>
+ 發佈於 `update/delta` 的訊息，僅包括 `desired` 和 `reported` 部分之間不同的所需屬性。這些屬性全都會包含在其中，無論這些屬性是否原本就包含於目前的更新訊息中或是已經存放於 AWS IoT。在 `desired` 和 `reported` 部分之間沒有差異的屬性則不會包含在內。
+ 如果某個屬性出現在 `reported` 部分，但在 `desired` 部分卻沒有，則此屬性不會包含在內。
+ 如果某個屬性出現在 `desired` 部分，但在 `reported` 部分卻沒有，則此屬性會包含在內。
+ 如果某個屬性在 `reported`部分被刪除，但仍存在於 `desired` 部分，則此屬性會包含在內。

### 範例 政策
<a name="update-delta-policy"></a>

以下為所需政策的範例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/delta"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/delta"
            ]
        }
    ]
}
```

## /update/accepted
<a name="update-accepted-pub-sub-topic"></a>

AWS IoT 接受裝置影子的變更時， 會將回應狀態文件發佈至此主題：

```
ShadowTopicPrefix/update/accepted
```

訊息緩衝區包含 [/accepted response state document](device-shadow-document.md#device-shadow-example-response-json-accepted)。

### 範例 政策
<a name="update-accepted-policy"></a>

以下為所需政策的範例：

****  

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

## /update/documents
<a name="update-documents-pub-sub-topic"></a>

AWS IoT 每當成功執行影子更新時， 就會發佈狀態文件至此主題：

```
ShadowTopicPrefix/update/documents
```

訊息內文包含 [/documents response state document](device-shadow-document.md#device-shadow-example-response-json-documents)。

### 範例 政策
<a name="update-documents-policy"></a>

以下為所需政策的範例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Subscribe"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/documents"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iot:Receive"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/documents"
            ]
        }
    ]
}
```

## /update/rejected
<a name="update-rejected-pub-sub-topic"></a>

AWS IoT 當拒絕裝置影子的變更時， 會將錯誤回應文件發佈至此主題：

```
ShadowTopicPrefix/update/rejected
```

訊息內文包含 [錯誤回應文件](device-shadow-document.md#device-shadow-example-error-json)。

### 範例 政策
<a name="update-rejected-policy"></a>

以下為所需政策的範例：

****  

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

## /delete
<a name="delete-pub-sub-topic"></a>

若要刪除裝置的影子，發佈空白訊息即可刪除主題：

```
ShadowTopicPrefix/delete
```

訊息的內容會被忽略。

請注意，刪除影子並不會將其版本號碼重設為 0。

AWS IoT 透過發佈至 [/delete/accepted](#delete-accepted-pub-sub-topic)或 來回應 [/delete/rejected](#delete-rejected-pub-sub-topic)。

### 範例 政策
<a name="delete-policy"></a>

以下為所需政策的範例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:Publish"
            ],
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete"
            ]
        }
    ]
}
```

## /delete/accepted
<a name="delete-accepted-pub-sub-topic"></a>

AWS IoT 刪除裝置的影子時， 會將訊息發佈至此主題：

```
ShadowTopicPrefix/delete/accepted
```

### 範例 政策
<a name="delete-accepted-policy"></a>

以下為所需政策的範例：

****  

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

## /delete/rejected
<a name="delete-rejected-pub-sub-topic"></a>

AWS IoT 當無法刪除裝置的影子時， 會將錯誤回應文件發佈至此主題：

```
ShadowTopicPrefix/delete/rejected
```

訊息內文包含 [錯誤回應文件](device-shadow-document.md#device-shadow-example-error-json)。

### 範例 政策
<a name="delete-rejected-policy"></a>

以下為所需政策的範例：

****  

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