Device Shadow MQTT 主題

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

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

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

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

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

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

/get

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

ShadowTopicPrefix/get

AWS IoT 透過發佈至 /get/accepted或 來回應 /get/rejected。

範例 政策

以下為所需政策的範例：

JSON

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

/get/accepted

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

ShadowTopicPrefix/get/accepted

如需詳細資訊，請參閱回應狀態文件。

範例 政策

以下為所需政策的範例：

JSON

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

/get/rejected

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

ShadowTopicPrefix/get/rejected

如需詳細資訊，請參閱錯誤回應文件。

範例 政策

以下為所需政策的範例：

/update

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

ShadowTopicPrefix/update

訊息內文包含部分請求狀態文件。

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

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

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

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

AWS IoT 透過發佈至 /update/accepted或 來回應 /update/rejected。

範例 政策

以下為所需政策的範例：

JSON

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

/update/delta

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

ShadowTopicPrefix/update/delta

訊息緩衝區包含 /delta response state document。

訊息內文詳細資料

• 發佈於 update/delta 的訊息，僅包括 desired 和 reported 部分之間不同的所需屬性。這些屬性全都會包含在其中，無論這些屬性是否原本就包含於目前的更新訊息中或是已經存放於 AWS IoT。在 desired 和 reported 部分之間沒有差異的屬性則不會包含在內。

• 如果某個屬性出現在 reported 部分，但在 desired 部分卻沒有，則此屬性不會包含在內。

• 如果某個屬性出現在 desired 部分，但在 reported 部分卻沒有，則此屬性會包含在內。

• 如果某個屬性在 reported部分被刪除，但仍存在於 desired 部分，則此屬性會包含在內。

範例 政策

以下為所需政策的範例：

JSON

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

/update/accepted

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

ShadowTopicPrefix/update/accepted

訊息緩衝區包含 /accepted response state document。

範例 政策

以下為所需政策的範例：

JSON

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

/update/documents

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

ShadowTopicPrefix/update/documents

訊息內文包含 /documents response state document。

範例 政策

以下為所需政策的範例：

JSON

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

/update/rejected

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

ShadowTopicPrefix/update/rejected

訊息內文包含 錯誤回應文件。

範例 政策

以下為所需政策的範例：

JSON

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

/delete

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

ShadowTopicPrefix/delete

訊息的內容會被忽略。

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

AWS IoT 會透過發佈至 /delete/accepted或 來回應 /delete/rejected。

範例 政策

以下為所需政策的範例：

JSON

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

/delete/accepted

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

ShadowTopicPrefix/delete/accepted

範例 政策

以下為所需政策的範例：

JSON

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

/delete/rejected

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

ShadowTopicPrefix/delete/rejected

訊息內文包含 錯誤回應文件。

範例 政策

以下為所需政策的範例：

JSON

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