/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 主题，以使设备和应用程序能够获取、更新或删除设备的状态信息（影子）。

要订阅影子主题并向该主题发布消息，需要获得基于主题的授权。Amazon IoT 保留向现有主题结构添加新主题的权利。为此，建议您订阅影子主题时勿使用通配符。例如，请勿在订阅时使用诸如 $aws/things/thingName/shadow/# 的主题筛选条件，因为与该主题筛选条件匹配的主题数量可能会随着 Amazon IoT 引入新的影子主题而增加。要了解针对这些主题发布的消息示例，请查看与影子交互。

影子可以是命名或未命名（经典）的。每个影子使用的主题仅在主题前缀上有所不同。下表显示每种影子类型使用的主题前缀。

`ShadowTopicPrefix` 值	影子类型
`$aws/things/thingName/shadow`	未命名的（经典）影子
`$aws/things/thingName/shadow/name/shadowName`	命名的影子

要创建完整的主题，请为要表示的影子类型选择 ShadowTopicPrefix，将 thingName 和 shadowName（如果适用）替换为相应的值，然后在其后面附加主题存根，如以下几部分中所示。

以下是用于与影子交互的 MQTT 主题。

/get

要获得设备的影子，请在此主题下发布一条空消息：


ShadowTopicPrefix/get

Amazon IoT 通过向 /get/accepted 或 /get/rejected 发布消息来进行响应。

示例 policy

以下是所需策略的示例：


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

/get/accepted

在返回设备的影子时，Amazon IoT 将响应影子文档发布到该主题：


ShadowTopicPrefix/get/accepted

有关更多信息，请参阅响应状态文档。

示例 policy

以下是所需策略的示例：


{
  "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

Amazon IoT 在无法返回设备的影子时向此主题发布错误响应文档：


ShadowTopicPrefix/get/rejected

有关更多信息，请参阅错误响应文档。

示例 policy

以下是所需策略的示例：


{
  "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

消息正文包含部分请求状态文档。

尝试更新设备状态的客户端将发送具有 desired 属性的 JSON 请求状态文档，例如：


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

更新其影子的设备将发送具有 reported 属性的 JSON 请求状态文档，例如：


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

Amazon IoT 通过向 /update/accepted 或 /update/rejected 发布消息来进行响应。

示例 policy

以下是所需策略的示例：


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

/update/delta

在接受设备的影子更改时，Amazon IoT 将响应状态文档发布到该主题，并且请求状态文档包含不同的 desired 和 reported 状态值：


ShadowTopicPrefix/update/delta

消息缓冲区包含一个 /delta 响应状态文档。

消息正文详细信息

发布到 update/delta 的消息仅包括 desired 部分和 reported 部分之间有所不同的预期属性。无论这些属性包含在当前更新消息中还是已存储在 Amazon IoT 中，它将包含所有此类属性。desired 部分和 reported 部分之间相同的属性则不包含在内。
如果某个属性位于 reported 部分，但在 desired 部分没有等效值，则不会包含在内。
如果某个属性位于 desired 部分，但在 reported 部分没有等效值，则将包含在内。
如果某个属性已从 reported 部分删除，但仍存在于 desired 部分，则将包含在内。

示例 policy

以下是所需策略的示例：


{
  "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

Amazon IoT 在接受设备影子的更改时向此主题发布响应状态文档：


ShadowTopicPrefix/update/accepted

消息缓冲区包含一个 /accepted 响应状态文档。

示例 policy

以下是所需策略的示例：


{
  "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

每次影子更新成功执行时，Amazon IoT 都会向该主题发布状态文档：


ShadowTopicPrefix/update/documents

消息正文包含一个 /documents 响应状态文档。

示例 policy

以下是所需策略的示例：


{
  "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

Amazon IoT 在拒绝设备影子的更改时向此主题发布错误响应文档：


ShadowTopicPrefix/update/rejected

消息正文包含一个错误响应文档。

示例 policy

以下是所需策略的示例：


{
  "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。

Amazon IoT 通过向 /delete/accepted 或 /delete/rejected 发布消息来进行响应。

示例 policy

以下是所需策略的示例：


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

/delete/accepted

Amazon IoT 在删除设备的影子时向此主题发布消息：


ShadowTopicPrefix/delete/accepted

示例 policy

以下是所需策略的示例：


{
  "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

Amazon IoT 在无法删除设备的影子时向此主题发布错误响应文档：


ShadowTopicPrefix/delete/rejected

消息正文包含一个错误响应文档。

示例 policy

以下是所需策略的示例：


{
  "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"
      ]
    }
  ]
}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

Device Shadow REST API

Device Shadow 服务文档