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

# 在裝置離線時保留裝置狀態
<a name="iot-shadows-tutorial"></a>

這些教學課程說明如何使用 AWS IoT Device Shadow 服務來存放和更新裝置的狀態資訊。Shadow 文件是一個 JSON 文件，其根據裝置、本機應用程式或服務發佈的訊息，顯示裝置狀態的變化。於本教學課程中，Shadow 文件會顯示燈泡顏色的變化。這些教學課程還會顯示影子如何在裝置與網際網路中斷連線時，儲存此資訊，並在裝置回復連線並請求此資訊時，將最新狀態資訊傳回裝置。

建議您依此處顯示的順序試試這些教學課程，從您需要建立的 AWS IoT 資源和必要的硬體設定開始，這亦可協助您逐步學習概念。這些教學課程示範如何設定和連接 Raspberry Pi 裝置以搭配 使用 AWS IoT。若您並無所需的硬體，您可依照這些教學課程進行調整，以適應您選擇的裝置或[使用 Amazon EC2 建立虛擬裝置](creating-a-virtual-thing.md)。

**教學課程案例概觀**  
這些教學課程的案例為本機應用程式或服務，可變更燈泡的顏色，及將其資料發佈置預留的影子主題。這些教學課程類似於[互動式入門教學課程](interactive-demo.md)中說明的 Device Shadow 功能，並在 Raspberry Pi 裝置實作。本節中的教學課程側重於單一經典影子裝置，同時展現如何容納已命名影子或多個裝置的方法。

下列教學課程將協助您了解如何使用 AWS IoT Device Shadow 服務。
+ 

**[教學課程：準備好 Raspberry Pi 來執行影子應用程式](create-resources-shadow.md)**  
本教學課程說明如何設定 Raspberry Pi 裝置以進行連線 AWS IoT。您也將建立 AWS IoT 政策文件和物件資源、下載憑證，然後將政策連接到該物件資源。此教學課程約需 30 分鐘方能完成。
+ 

**[教學課程：安裝裝置 SDK 並執行 Device Shadows 的範例應用程式](lightbulb-shadow-application.md)**  
本教學課程說明如何安裝必要的工具、軟體和適用於 Python 的 AWS IoT 裝置 SDK，然後執行範例陰影應用程式。本教學課程以 [連接 Raspberry Pi 或其他裝置](connecting-to-existing-device.md) 中提出的概念為基礎，需 20 分鐘才能完成。
+ 

**[教學課程：使用範例應用程式和 MQTT 測試用戶端，與 Device Shadow 互動](interact-lights-device-shadows.md)**  
本教學課程示範如何使用`shadow.py`範例應用程式和**AWS IoT 主控台**來觀察 AWS IoT Device Shadows 與燈泡狀態變更之間的互動。本教學課程也會展示如何將 MQTT 訊息傳送至 Device Shadow 的預留主題。此教學課程約需 45 分鐘方能完成。

**AWS IoT Device Shadow 概觀**  
Device Shadow 是由您在 AWS IoT 登錄檔中建立的[物件資源](iot-thing-management.md)管理之裝置的持久性虛擬表示法。Shadow 文件是個 JSON 或 JavaScript 標記法文件，用來存儲和檢索裝置的目前狀態資訊。您可透過 MQTT 或 HTTP REST API，使用影子來取得及設定裝置的狀態 (無論該裝置是否連線至網際網路)。

Shadow 的文件包含 `state` 屬性，說明裝置狀態的下列層面：
+ `desired`：應用程式會透過更新 `desired` 物件來指定裝置屬性的所需狀態。
+ `reported`：裝置會報告其在 `reported` 物件中的目前狀態。
+ `delta`： AWS IoT 報告 `delta` 物件中所需狀態與報告狀態之間的差異。

以下為 Shadow 狀態文件的範例：

```
{
  "state": {
    "desired": {
      "color": "green"
      },
    "reported": {
      "color": "blue"
      },
    "delta": {
      "color": "green"
      }
   }
}
```

如要更新裝置的 Shadow 文件，您可使用[預留的 MQTT 主題](reserved-topics.md#reserved-topics-shadow)、以 HTTP 支援 `GET`、`UPDATE` 和 `DELETE` 操作的 [Device Shadow REST API](device-shadow-rest-api.md)，以及 [AWS IoT CLI](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/index.html)。

在上一個範例中，假設您想將 `desired` 顏色變更為 `yellow`。如要執行此動作，請傳送請求至 [UpdateThingShadow](device-shadow-rest-api.md#API_UpdateThingShadow) API 或將訊息發佈至[更新](device-shadow-mqtt.md#update-pub-sub-topic)主題 `$aws/things/THING_NAME/shadow/update`。

```
{
  "state": {
    "desired": {
      "color": yellow
    }
  }
}
```

更新只會影響請求中所指定的欄位。成功更新 Device Shadow 後， 會將新`desired`狀態 AWS IoT 發佈至`delta`主題 `$aws/things/THING_NAME/shadow/delta`。於此狀況下，Shadow 文件看起來像這樣：

```
{
  "state": {
    "desired": {
      "color": yellow
    },
    "reported": {
      "color": green
    },
    "delta": {
      "color": yellow
      }
  }
}
```

接著會使用`$aws/things/THING_NAME/shadow/update`具有下列 JSON 訊息`Update`的主題，向 AWS IoT Device Shadow 報告新狀態：

```
{
  "state": {
    "reported": {
      "color": yellow
    }
  }
}
```

若您想要取得目前的狀態資訊，請將請求傳送至 [GetThingShadow](device-shadow-rest-api.md#API_GetThingShadow) API 或將 MQTT 訊息發佈至[取得](device-shadow-mqtt.md#get-pub-sub-topic)主題 `$aws/things/THING_NAME/shadow/get`。

如需使用 Device Shadow 服務的相關資訊，請參閱 [AWS IoT Device Shadow 服務](iot-device-shadows.md)。

如需在裝置、應用程式和服務中使用 Device Shadows 的詳細資訊，請參閱 [在裝置中使用影子](device-shadow-comms-device.md) 和 [在應用程式和服務中使用影子](device-shadow-comms-app.md)。

如需與 AWS IoT 陰影互動的資訊，請參閱 [與影子互動](device-shadow-data-flow.md)。

如需 MQTT 預留主題和 HTTP REST API 的相關資訊，請參閱 [Device Shadow MQTT 主題](device-shadow-mqtt.md) 和 [Device Shadow REST API](device-shadow-rest-api.md)。