物联网平台提供设备影子功能，用于缓存设备上报的状态数据和应用程序下发的指令信息。设备在线时，可以直接获取物联网平台指令；设备离线后，再次上线可以主动拉取物联网平台指令。本文主要介绍设备影子的应用场景和使用方法。

什么是设备影子

设备影子是一个JSON文档，用于存储设备上报状态数据和应用程序期望状态信息。JSON数据格式的详细说明，请参见设备影子JSON详解。

每个设备有且只有一个设备影子，设备可以通过MQTT获取和设置设备影子来同步状态，该同步可以是影子同步给设备，也可以是设备同步给影子。

与设置设备期望属性值区别

设备影子与设置设备期望属性值功能，都是在物联网平台云端存储期望数据，设备上线后获取对应的期望数据，实现对相应业务逻辑的控制。两功能的应用范围不同，说明如下。

功能项	区别
设置设备期望属性值	应用范围单一，仅设置设备的物模型属性值。使用该功能前，必须为设备定义物模型属性。 若需设置设备物模型属性的期望值，使用该功能即可。使用示例，请参见设置期望属性值控制灯泡状态。
设备影子	应用范围更广，且不依赖物模型属性定义，可设置设备状态等数据。具体应用场景，请参见下文描述。 设备影子的设置说明，请参见设备影子JSON详解。

应用场景

在以下场景中，您可选择使用设备影子功能，获取设备上报数据和应用程序期望数据。

• 应用程序请求获取设备状态。

  场景描述：

  • 设备网络不稳定，设备频繁上下线，无法正常响应应用程序的请求。
  • 设备网络稳定，同时响应多个应用程序的请求，即使响应的结果一样，设备本身处理能力有限，也会无法负载多次请求。

  使用设备影子机制，设备状态变更，只需同步状态给设备影子一次，应用程序请求获取设备状态，不论应用程序请求数量，和设备是否联网在线，都可从设备影子中获取设备当前状态，实现应用程序与设备解耦。

  应用程序获取设备影子中状态的流程图如下，其中数据流转过程，请参见设备主动上报状态。

  

• 应用程序下发指令给设备，变更设备状态。

  场景描述：设备处于下线状态，或设备网络不稳定，设备频繁上下线，应用程序发送控制指令给设备，设备不在线，指令就会发送失败。

  使用设备影子机制，可以将应用程序下发的指令，携带时间戳存储到设备影子中。设备再上线时，获取设备影子中指令，并根据时间戳确定是否执行。

  应用程序更新设备状态的流程图如下，其中数据流转过程，请参见应用程序改变设备状态、设备主动获取影子内容、设备主动删除影子属性。

  

查看与更新设备影子

您需在设备端完成设备影子功能开发，具体内容，请参见设备影子。

完成设备开发和接入后，您可以在物联网平台控制台，查看设备影子信息，更新设备影子状态。

1. 登录物联网平台控制台。
2. 在实例概览页面，找到对应的实例，单击实例进入实例详情页面。

   重要 目前华东2（上海）、华北2（北京）、华南1（深圳）地域开通了企业版实例服务。其他地域，请跳过此步骤。

   

3. 在左侧导航栏，选择设备管理 > 设备。
4. 单击对应设备的查看按钮，进入设备详情页面。
5. 单击设备影子，页面显示设备上报的影子状态。

   

6. 单击更新影子，在“desired”部分，填入期望设备状态。

   设备影子文档格式，请参见设备影子JSON详解。

   设备在线时，设备影子保存期望状态，设备通过订阅Topic直接获得期望状态。

   设备离线时，设备影子缓存期望状态，设备上线后，主动从物联网平台拉取最新期望状态。

 

相关API

GetDeviceShadow：获取设备影子。

UpdateDeviceShadow：更新设备影子。