Device Shadow MQTT 主題 - AWS IoT Core
/get/get/accepted/get/rejected/update/update/delta/update/accepted/update/documents/update/rejected/delete/delete/accepted/delete/rejected

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

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。

範例 政策

以下為所需政策的範例：

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

/get/accepted

AWS IoT 返回設備的陰影時，將響應陰影文檔發布到此主題：

ShadowTopicPrefix/get/accepted

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

範例 政策

以下為所需政策的範例：

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

/get/rejected

AWS IoT 當無法返回設備的陰影時，將錯誤響應文檔發布到此主題：

ShadowTopicPrefix/get/rejected

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

範例 政策

以下為所需政策的範例：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Subscribe"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/get/rejected"
      ]
    },
    {
      "Action": [
        "iot:Receive"
      ],
      "Resource": [
        "arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/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。

範例 政策

以下為所需政策的範例：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Publish"
      ],
      "Resource": [
        "arn:aws:iot:region:account: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 部分，則此屬性會包含在內。

範例 政策

以下為所需政策的範例：

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

/update/accepted

AWS IoT 當接受設備陰影的更改時，將響應狀態文檔發布到此主題：

ShadowTopicPrefix/update/accepted

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

範例 政策

以下為所需政策的範例：

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

/update/documents

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

ShadowTopicPrefix/update/documents

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

範例 政策

以下為所需政策的範例：

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

/update/rejected

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

ShadowTopicPrefix/update/rejected

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

範例 政策

以下為所需政策的範例：

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

/delete

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

ShadowTopicPrefix/delete

訊息的內容會被忽略。

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

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

範例 政策

以下為所需政策的範例：

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

/delete/accepted

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

ShadowTopicPrefix/delete/accepted

範例 政策

以下為所需政策的範例：

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

/delete/rejected

AWS IoT 當無法刪除設備的陰影時，將錯誤響應文檔發佈到此主題：

ShadowTopicPrefix/delete/rejected

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

範例 政策

以下為所需政策的範例：

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