Device Shadow 服務文件 - AWS IoT Core
影子文件範例文件屬性差量狀態版本控制影子文件影子文件中的用戶端字符空白影子文件屬性影子文件中的陣列值

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

Device Shadow 服務文件

Device Shadow 服務遵守 JSON 規格的所有規則。值、物件與陣列均存放於裝置的影子文件中。

影子文件範例

在使用 REST API 或 MQTT 發佈/訂閱訊息的 UPDATE、GET、DELETE 操作中，Device Shadow 服務會使用下列文件。

請求狀態文件

請求狀態文件具有以下格式：

{
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer1,
            "attribute2": "string1",
            ...
            "attributeN": boolean1
        }
    },
    "clientToken": "token",
    "version": version
}

  • state：更新僅會影響所指定的欄位。一般而言，您會使用 desired 或 reported 屬性，但不會在同一個要求中使用兩者。

    • desired：請求在裝置中更新的狀態屬性和值。

    • reported：裝置回報的狀態屬性和值。

  • clientToken：如已使用，您可透過用戶端字符來比對請求和相應的回應。

  • version：若使用此項目，Device Shadow 服務只有在指定版本與其擁有的最新版本相符時，才會處理更新。

回應狀態文件

根據回應類型，回應狀態文件的格式如下。

/accepted response state document

{
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "timestamp": timestamp,
    "clientToken": "token",
    "version": version
}

/delta response state document

{
    "state": {
        "attribute1": integer2,
        "attribute2": "string2",
        ...
        "attributeN": boolean2
    },
    "metadata": {
        "attribute1": {
            "timestamp": timestamp
        },
        "attribute2": {
            "timestamp": timestamp
        },
        ...
        "attributeN": {
            "timestamp": timestamp
        }
    },
    "timestamp": timestamp,
    "clientToken": "token",
    "version": version
}

/documents response state document

{
  "previous" : {
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer1,
            "attribute2": "string1",
            ...
            "attributeN": boolean1
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        },
        "reported": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "version": version-1
  },
  "current": {
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        },
        "reported": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "version": version
  },
  "timestamp": timestamp,
  "clientToken": "token"
}

回應狀態文件屬性

  • previous：成功更新之後，會在更新前包含物件的 state。

  • current：成功更新之後，會在更新後包含物件的 state。

  • state

    • reported：僅當物件於 reported 區段回報任何資料，且包含僅位於請求狀態文件中的欄位時才出現。

    • desired：僅當裝置於 desired 區段回報任何資料，且包含僅位於請求狀態文件中的欄位時才出現。

    • delta：僅當 desired 資料與影子目前 reported 資料不同時才會存在。

  • metadata：包含 desired 和 reported 部分中每個屬性的時間戳記，因此您可確定狀態的更新時間。

  • timestamp-響應生成的時代日期和時間。 AWS IoT

  • clientToken：僅在發佈有效 JSON 至 /update 主題並使用用戶端符記時才會出現。

  • version： AWS IoT 中目前共用之裝置影子的文件版本。此版本會在先前的文件版本編號加一。

錯誤回應文件

錯誤回應文件的格式如下：

{
    "code": error-code,
    "message": "error-message",
    "timestamp": timestamp,
    "clientToken": "token"
}

  • code：用於指明錯誤類型的 HTTP 回應碼。

  • message：可提供額外資訊的文字訊息。

  • timestamp— 生成響應的日期和時間 AWS IoT。此屬性不會出現在所有錯誤回應文件中。

  • clientToken：僅於已發佈的訊息中使用用戶端字符時才會出現。

如需詳細資訊，請參閱 Device Shadow 錯誤訊息。

影子名稱清單回應文件

影子名稱清單回應文件的格式如下：

{
    "results": [
        "shadowName-1",
        "shadowName-2",
        "shadowName-3",
        "shadowName-n"
    ],
    "nextToken": "nextToken",
    "timestamp": timestamp
}

  • results：影子名稱的陣列。

  • nextToken：在分頁請求中使用的字符值，以取得序列中的下一頁。當沒有更多的影子名稱返回時，這個屬性不存在。

  • timestamp— 生成響應的日期和時間 AWS IoT。

文件屬性

裝置的影子文件具有下列屬性：

state
desired

裝置所需的狀態。應用程式可將此部分編寫入文件，在無需直接連線的狀況下更新裝置狀態。

reported

裝置回報的狀態。裝置會在文件中編寫此部分以回報其新狀態。應用程式會讀取文件的這部分，以判斷裝置上次報告的狀態。

metadata

存放於文件 state 部分之資料的相關資訊。其中包括針對 state 部分中各屬性的時間戳記 (Epoch 時間)，可讓您確定資料是在何時更新的。

注意

中繼資料不會影響服務限制或定價的文件大小。如需詳細資訊，請參閱 AWS IoT 服務限制。

timestamp

指出訊息的傳送時間 AWS IoT。藉由使用訊息中的時間戳記和 desired 或 reported 區段中的個別屬性的時間戳記，裝置可以判斷屬性的保留天數，即使裝置沒有內部時鐘也是如此。

clientToken

裝置特有的字串能夠讓您在 MQTT 環境中將回應與請求建立關聯。

version

文件版本。每次文件更新時，版本編號便會自動增加。如此可確保更新的文件為最新版本。

如需詳細資訊，請參閱 影子文件範例。

差量狀態

差量 (delta) 狀態是一種虛擬類型的狀態，包含了 desired 和 reported 之間的差異。在 desired 部分的欄位若未出現於 reported 部分，則會納入差量之中。在 reported 部分的欄位若未出現於 desired 部分，則不會納入差量之中。差量包含中繼資料，且其值與 desired 欄位裡的中繼資料相同。例如：

{
  "state": {
    "desired": {
      "color": "RED",
      "state": "STOP"
    },
    "reported": {
      "color": "GREEN",
      "engine": "ON"
    },
    "delta": {
      "color": "RED",
      "state": "STOP"
    }
  },
  "metadata": {
    "desired": {
      "color": {
        "timestamp": 12345
      },
      "state": {
        "timestamp": 12345
      }
      },
      "reported": {
        "color": {
          "timestamp": 12345
        },
        "engine": {
          "timestamp": 12345
        }
      },
      "delta": {
        "color": {
          "timestamp": 12345
        },
        "state": {
          "timestamp": 12345
        }
      }
    },
    "version": 17,
    "timestamp": 123456789
  }
}

當巢狀物件不同，差量則會包含根路徑。

{
  "state": {
    "desired": {
      "lights": {
        "color": {
          "r": 255,
          "g": 255,
          "b": 255
        }
      }
    },
    "reported": {
      "lights": {
        "color": {
          "r": 255,
          "g": 0,
          "b": 255
        }
      }
    },
    "delta": {
      "lights": {
        "color": {
          "g": 255
        }
      }
    }
  },
  "version": 18,
  "timestamp": 123456789
}

Device Shadow 服務會重複查看 desired 狀態內的所有欄位，然後將其與 reported 狀態相比較，藉此計算出差量。

陣列的處理和值相同。如果 desired 部分的某個陣列與 reported 部分的陣列不符，則整組所需陣列都會複製到差量中。

版本控制影子文件

Device Shadow 服務支援每個更新訊息的版本控制，包括請求和回應。這表示，隨著影子的每次更新，JSON 文件的版本都會遞增。如此可確保兩種情況：

  • 如果用戶端嘗試以較舊的版本編號覆寫影子，就會收到錯誤訊息。通知用戶端必須先重新同步裝置的影子，才可進行更新。

  • 如果此訊息的版本低於存放於用戶端的訊息版本，則用戶端可以決定不採取行動。

用戶端可以透過不在影子文件中包含版本來略過版本比對。

影子文件中的用戶端字符

您可以使用用戶端符記收發以 MQTT 為基礎的訊息，藉此驗證請求與針對請求的回應中是否包含了同樣的用戶端符記。如此可確保回應與請求之間具有關聯。

注意

用戶端字符不能超過 64 位元組。長於 64 位元組的用戶端字符會導致 400 (Bad Request) 回應以及一個 Invalid clientToken 錯誤訊息。

空白影子文件屬性

當影子文件中的 reported 和 desired 屬性不適用於目前影子狀態時，它們可以是空的，您也可以省略它們。例如，影子文件只有在具有所需狀態時才會包含 desired 屬性。以下是沒有 desired 屬性的狀態文件的有效範例：

{
    "reported" : { "temp": 55 }
}

該 reported 屬性也可以是空白，例如，如果影子尚未由裝置更新：

{
    "desired" : { "color" : "RED" }
}

如果更新導致 desired 或 reported 屬性變為 null，則會從文件中移除。下面顯示了如何透過將屬性設定為 null 來刪除 desired。例如，當裝置更新其狀態時，您可能會這麼做。

{ 
    "state": {
        "reported": {
            "color": "red" 
        }, 
        "desired": null 
    } 
}

影子文件也可以具有 desired 或 reported 屬性，使影子文件變成空白。這是一個空白但有效的影子文件範例。

{
}

影子文件中的陣列值

影子支援陣列，但會將其視為一般值，即更新某陣列會取代整組陣列。您無法只更新陣列中的某部分。

初始狀態：

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

更新：

{
    "desired" : { "colors" : ["RED"] }
}

最終狀態：

{
    "desired" : { "colors" : ["RED"] }
}

陣列不能有 Null 值。例如，以下陣列無效並且會被拒絕。

{
    "desired" : { 
        "colors" : [ null, "RED", "GREEN" ]
    }
}