與影子互動 - AWS IoT Core
通訊協定支援請求和報告狀態更新影子擷取影子文件刪除影子資料

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

與影子互動

本主題說明與 AWS IoT 提供使用影子的三種方法中的每一種相關聯的訊息。這些方法包括下列各項：

UPDATE

建立一個影子，如果它不存在，或者使用訊息正文中提供的狀態訊息更新現有影子的內容。 AWS IoT 會記錄每次更新的時間戳記，以指出上次更新狀態的時間。當影子的狀態變更時， AWS IoT 會將/delta訊息傳送給所有訂閱MQTT者，其狀態desired與 不同reported。接收 /delta 訊息的裝置或應用程式會根據差異執行動作。例如，裝置可以更新其狀態至所需的狀態，或者應用程式可以更新 UI 以反映裝置狀態的改變。

GET

擷取包含影子完整狀態的目前影子文件，包括中繼資料。

DELETE

刪除裝置影子及其內容。

您無法還原已刪除的裝置影子文件，但可以使用已刪除的裝置影子文件的名稱建立新的裝置影子。如果您建立的裝置影子文件名稱與過去 48 小時內刪除的文件名稱相同，則新裝置影子文件的版本號碼會跟隨已刪除影子的版本號碼。如果裝置影子文件已刪除超過 48 小時，則使用相同名稱的新裝置影子文件的版本號碼將會是 0。

通訊協定支援

AWS IoT 支援 MQTT和 RESTAPI協定，HTTPS以與影子互動。 AWS IoT 提供一組預留請求和回應主題，用於MQTT發佈和訂閱動作。裝置和應用程式應先訂閱回應主題，再發佈請求主題，以取得 AWS IoT 處理請求的相關資訊。如需詳細資訊，請參閱 裝置影子MQTT主題 和 裝置影子 REST API。

請求和報告狀態

使用 AWS IoT 和影子設計 IoT 解決方案時，您應該判斷將請求變更的應用程式或裝置，以及將實作這些變更的應用程式或裝置。一般而言，裝置會實作並報告變更回影子，而應用程式和服務會回應並請求影子中的變更。您的解決方案可能不同，但本主題中的範例假設用戶端應用程式或服務請求變更影子中，而裝置會執行變更，並將它們回報給影子。

更新影子

您的應用程式或服務可以使用 UpdateThingShadowAPI或 發佈至/update主題來更新影子的狀態。更新只會影響請求中所指定的欄位。

當用戶端請求狀態變更時更新影子

當用戶端使用MQTT通訊協定請求變更影子的狀態時

  1. 用戶端應具有目前的影子文件，以便識別要變更的屬性。請參閱 /get 動作，了解如何取得目前的影子文件。

  2. 用戶端訂閱這些MQTT主題：

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    • $aws/things/thingName/shadow/name/shadowName/update/documents

  3. 用戶端會發佈 $aws/things/thingName/shadow/name/shadowName/update 請求主題，其中包含所需的影子狀態的狀態文件。只有要變更的屬性需要包含在文件中。這是具有所需狀態的文件的範例。

    {
  "state": {
    "desired": {
      "color": {
        "r": 10
      },
      "engine": "ON"
    }
  }
}

  4. 如果更新請求有效， 會在影子中 AWS IoT 更新所需的狀態，並發佈這些主題的訊息：

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    /update/accepted 訊息包含 /accepted response state document 影子文件，而 /update/delta 訊息包含 /delta response state document 影子文件。

  5. 如果更新請求無效， 會使用描述錯誤的錯誤回應文件影子文件 AWS IoT 發佈具有$aws/things/thingName/shadow/name/shadowName/update/rejected主題的訊息。

當用戶端使用 請求陰影中的狀態變更時 API

  1. 用戶端UpdateThingShadowAPI會使用請求狀態文件狀態文件作為其訊息內文呼叫 。

  2. 如果請求有效， 會 AWS IoT 傳回HTTP成功回應碼和/accepted response state document影子文件作為其回應訊息內文。

    AWS IoT 也會發佈MQTT訊息至$aws/things/thingName/shadow/name/shadowName/update/delta主題，其中包含訂閱該主題的任何裝置或用戶端的/delta response state document影子文件。

  3. 如果請求無效， 會 AWS IoT 傳回HTTP錯誤回應碼 錯誤回應文件作為回應訊息內文。

當裝置收到有關 /update/delta 主題的 /desired 狀態時，它會在裝置中進行所需的變更。然後，它會將訊息傳送至 /update 主題，向影子報告其目前狀態。

當裝置回報其目前狀態時更新影子

當裝置使用MQTT通訊協定向影子報告其目前狀態時

  1. 在更新影子之前，裝置應訂閱這些MQTT主題：

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    • $aws/things/thingName/shadow/name/shadowName/update/documents

  2. 裝置會將訊息發佈至報告目前狀態的 $aws/things/thingName/shadow/name/shadowName/update 主題，例如在此範例中，以報告其目前狀態。

    {
    "state": {
        "reported" : {
            "color" : { "r" : 10 },
            "engine" : "ON"
        }
    }
}

  3. 如果 AWS IoT 接受更新，則會將訊息發佈至具有/accepted response state document影子文件$aws/things/thingName/shadow/name/shadowName/update/accepted的主題。

  4. 如果更新請求無效， 會使用描述錯誤的錯誤回應文件影子文件 AWS IoT 發佈具有$aws/things/thingName/shadow/name/shadowName/update/rejected主題的訊息。

當裝置使用 向影子報告其目前狀態時 API

  1. 裝置UpdateThingShadowAPI會使用請求狀態文件狀態文件作為其訊息內文呼叫 。

  2. 如果請求有效， 會 AWS IoT 更新影子並傳回HTTP成功回應碼，並將/accepted response state document影子文件作為回應訊息內文。

    AWS IoT 也會發佈MQTT訊息至$aws/things/thingName/shadow/name/shadowName/update/delta主題，其中包含訂閱該主題的任何裝置或用戶端的/delta response state document影子文件。

  3. 如果請求無效， 會 AWS IoT 傳回HTTP錯誤回應碼 錯誤回應文件作為回應訊息內文。

樂觀鎖定

您可以使用狀態文件版本，確認您正在更新的裝置影子文件為最新版本。當您提供具有更新請求的版本時，如果目前的狀態文件版本與提供的版本不相符，服務會拒絕具有 HTTP 409 衝突回應碼的請求。衝突回應程式碼也可能發生在修改 API 的任何 上ThingShadow，包括 DeleteThingShadow。

例如：

初始文件：

{
  "state": {
    "desired": {
      "colors": [
        "RED",
        "GREEN",
        "BLUE"
      ]
    }
  },
  "version": 10
}

更新：(版本不符合；系統將拒絕請求)

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 9
}

結果：

{
  "code": 409,
  "message": "Version conflict",
  "clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}

更新：(版本符合；將接受請求)

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 10
}

最終狀態：

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 11
}

擷取影子文件

您可以使用 GetThingShadowAPI或 訂閱並發佈至/get主題來擷取影子文件。這會擷取完整的影子文件，包括 desired 和 reported 狀態之間的任何差異。無論裝置或用戶端正在提出請求，此工作的程序都是相同的。

使用MQTT通訊協定擷取影子文件

  1. 裝置或用戶端應在更新影子之前訂閱這些MQTT主題：

    • $aws/things/thingName/shadow/name/shadowName/get/accepted

    • $aws/things/thingName/shadow/name/shadowName/get/rejected

  2. 裝置或用戶端會將訊息發佈至具有空白訊息內文的 $aws/things/thingName/shadow/name/shadowName/get 主題。

  3. 如果請求成功， 會在訊息內文/accepted response state document中使用 將訊息 AWS IoT 發佈至$aws/things/thingName/shadow/name/shadowName/get/accepted主題。

  4. 如果請求無效， 會將訊息 AWS IoT 發佈到$aws/things/thingName/shadow/name/shadowName/get/rejected訊息內文錯誤回應文件中具有 的主題。

使用 擷取影子文件 REST API

  1. 裝置或用戶端使用GetThingShadowAPI空白訊息內文呼叫 。

  2. 如果請求有效， 會 AWS IoT 傳回HTTP成功回應碼，並以/accepted response state document影子文件作為回應訊息內文。

  3. 如果請求無效， 會 AWS IoT 傳回HTTP錯誤回應碼 錯誤回應文件作為回應訊息內文。

刪除影子資料

有兩種方法可以刪除影子資料：您可以刪除影子文件中的特定屬性，也可以完全刪除影子。

  • 若要從影子中刪除特定屬性，請更新影子；不過，請將您要刪除的屬性值設定為 null。值為 null 的欄位會從影子文件中移除。

  • 若要刪除整個影子，請使用 DeleteThingShadowAPI或 發佈至/delete主題。

注意

刪除影子不會一次將其版本號碼重設為零。其將於 48 小時後重設為零。

從影子文件中刪除屬性

使用MQTT通訊協定從影子中刪除屬性

  1. 裝置或用戶端應該有目前的影子文件，以便識別要變更的屬性。如需如何取得目前影子文件的詳細資訊，請參閱 擷取影子文件。

  2. 裝置或用戶端訂閱下列MQTT主題：

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

  3. 裝置或用戶端會發佈 $aws/things/thingName/shadow/name/shadowName/update 請求主題，其中包含狀態文件，該文件會將 null 值指派給要刪除的影子屬性。只有要變更的屬性需要包含在文件中。這是刪除 engine 屬性的文件範例。

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  4. 如果更新請求有效， 會 AWS IoT 刪除影子中的指定屬性，並在訊息內文中發佈具有影/accepted response state document子文件$aws/things/thingName/shadow/name/shadowName/update/accepted的主題訊息。

  5. 如果更新請求無效， 會使用描述錯誤的錯誤回應文件影子文件 AWS IoT 發佈具有$aws/things/thingName/shadow/name/shadowName/update/rejected主題的訊息。

若要使用 刪除陰影中的屬性 REST API

  1. 裝置或用戶端UpdateThingShadowAPI會使用 呼叫 請求狀態文件，將null值指派給要刪除的影子屬性。只包含您要在文件中刪除的屬性。這是刪除 engine 屬性的文件範例。

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  2. 如果請求有效， 會 AWS IoT 傳回HTTP成功回應碼和/accepted response state document影子文件作為其回應訊息內文。

  3. 如果請求無效， 會 AWS IoT 傳回HTTP錯誤回應碼 錯誤回應文件作為回應訊息內文。

刪除影子

以下是刪除裝置影子時的一些考量事項。

  • 將裝置的影子狀態設定為 null 不會刪除影子。影子版本將在下一次更新時遞增。

  • 刪除裝置的影子並不會刪除物件物件。刪除物件物件也不會刪除對應的裝置影子。

  • 刪除影子不會一次將其版本號碼重設為零。其將於 48 小時後重設為零。

使用MQTT通訊協定刪除影子

  1. 裝置或用戶端訂閱下列MQTT主題：

    • $aws/things/thingName/shadow/name/shadowName/delete/accepted

    • $aws/things/thingName/shadow/name/shadowName/delete/rejected

  2. 裝置或用戶端會發佈具有空白訊息緩衝區的 $aws/things/thingName/shadow/name/shadowName/delete。

  3. 如果刪除請求有效， 會 AWS IoT 刪除影子，並在訊息內文中發佈具有$aws/things/thingName/shadow/name/shadowName/delete/accepted主題和縮寫/accepted response state document影子文件的訊息。以下是接受的刪除訊息範例：

    {
  "version": 4,
  "timestamp": 1591057529
}

  4. 如果更新請求無效， 會使用描述錯誤的錯誤回應文件影子文件 AWS IoT 發佈具有$aws/things/thingName/shadow/name/shadowName/delete/rejected主題的訊息。

使用 刪除影子 REST API

  1. 裝置或用戶端DeleteThingShadowAPI使用空白訊息緩衝區呼叫 。

  2. 如果請求有效， 會在訊息內文中 AWS IoT 傳回HTTP成功回應碼和 /accepted response state document以及縮寫/accepted response state document陰影文件。以下是接受的刪除訊息範例：

    {
  "version": 4,
  "timestamp": 1591057529
}

  3. 如果請求無效， 會 AWS IoT 傳回HTTP錯誤回應碼 錯誤回應文件作為回應訊息內文。