Device Shadow REST API

影子會公開下列 URI 以更新狀態資訊：

https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow

端點是特定於您的 AWS 帳戶. 如要尋找您的端點，您可以：

• 使用來自 AWS CLI 的 describe-endpoint 命令。

• 使用主 AWS IoT 控台設定。於 Settings (設定) 中，端點會列於 Custom endpoint (自訂端點) 之下

• 使用 AWS IoT 主控台物件詳細資訊頁面。在主控台中：

  1. 開啟 Manage (管理)，在 Manage (管理) 之下，選擇 Things (物件)。

  2. 於物件清單中，選擇要取得端點 URI 的物件。

  3. 選擇 Device Shadows 索引標籤，選擇您的影子。您可在 Device Shadow 詳細資訊頁面的 Device Shadow URL 區段中檢視端點 URI。

端點格式如下：

identifier.iot.region.amazonaws.com

影子 REST API 會遵循相同的 HTTPS 通訊協定/連接埠映射，如 裝置通訊協定 中所述。

注意

若要使用 API，您必須使用 iotdevicegateway 作為身分驗證的服務名稱。如需詳細資訊，請參閱 IoT DataPlane。

您也可以透過提供 name=shadowName 作為 API 的查詢參數的一部分，使用 API 建立已命名的影子。

GetThingShadow

取得特定物件的影子。

回應狀態文件包括 desired 和 reported 狀態之間的差量。

請求

此請求包括標準 HTTP 標頭加上以下 URI：

HTTP GET https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)

未命名 (典型) 影子不需要 name 查詢參數。

回應

成功時，回應會包括標準 HTTP 標頭以及下列程式碼與本文：

HTTP 200
Response Body: response state document

如需詳細資訊，請參閱回應狀態文件範例。

授權

擷取影子需要一項允許呼叫者可執行 iot:GetThingShadow 動作的政策。Device Shadow 服務接受兩種形式的身分驗證：使用 IAM 憑證的 Signature 第 4 版，或使用用戶端憑證的 TLS 交互身分驗證。

下列為允許呼叫者擷取裝置影子的政策範例：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:GetThingShadow",
      "Resource": [
        "arn:aws:iot:region:account:thing/thing"
      ]
    }
  ]
}

UpdateThingShadow

更新指定之物件的影子。

更新僅會影響請求狀態文件中所指定的欄位。值為 null 的任何欄位，皆會從裝置影子中移除。

請求

此請求包含標準 HTTP 標頭和內文加上以下 URI 與本文：

HTTP POST https://endpoint/things/thingName/shadow?name=shadowName
Request body: request state document

未命名 (典型) 影子不需要 name 查詢參數。

如需詳細資訊，請參閱請求狀態文件範例。

回應

成功時，回應會包括標準 HTTP 標頭以及下列程式碼與本文：

HTTP 200
Response body: response state document

如需詳細資訊，請參閱回應狀態文件範例。

授權

更新影子需要一項允許呼叫者執行 iot:UpdateThingShadow 動作的政策。Device Shadow 服務接受兩種形式的身分驗證：使用 IAM 憑證的 Signature 第 4 版，或使用用戶端憑證的 TLS 交互身分驗證。

下列為允許呼叫者更新裝置影子的政策範例：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:UpdateThingShadow",
      "Resource": [
        "arn:aws:iot:region:account:thing/thing"
      ]
    }
  ]
}

DeleteThingShadow

刪除特定物件的影子。

請求

此請求包括標準 HTTP 標頭加上以下 URI：

HTTP DELETE https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)

未命名 (典型) 影子不需要 name 查詢參數。

回應

成功時，回應會包括標準 HTTP 標頭以及下列程式碼與本文：

HTTP 200
Response body: Empty response state document

請注意，刪除影子並不會將其版本號碼重設為 0。

授權

刪除裝置影子需要一項允許呼叫者執行 iot:DeleteThingShadow 動作的政策。Device Shadow 服務接受兩種形式的身分驗證：使用 IAM 憑證的 Signature 第 4 版，或使用用戶端憑證的 TLS 交互身分驗證。

下列為允許呼叫者刪除裝置影子的政策範例：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:DeleteThingShadow",
      "Resource": [
        "arn:aws:iot:region:account:thing/thing"
      ]
    }
  ]
}

ListNamedShadowsForThing

列出指定物件的影子。

請求

此請求包括標準 HTTP 標頭加上以下 URI：

HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize
Request body: (none)

nextToken

用來擷取下一組結果的符記。

此值會在分頁結果上傳回，並在傳回下一頁的呼叫中使用。

pageSize

影子名稱在每個呼叫中傳回的數目。另請參閱 nextToken。

thingName

要列出命名影子的物件的名稱。

回應

成功時，回應會包括標準 HTTP 標頭以及下列回應程式碼與 影子名稱清單回應文件。

注意

未命名 (傳統) 影子不會出現在此清單中。如果您只有一個經典的影子，或者您指定的 thingName 不存在，則回應將是一個空清單。

HTTP 200
Response body: Shadow name list document

授權

列出裝置影子需要一項允許呼叫者執行 iot:ListNamedShadowsForThing 動作的政策。Device Shadow 服務接受兩種形式的身分驗證：使用 IAM 憑證的 Signature 第 4 版，或使用用戶端憑證的 TLS 交互身分驗證。

以下為允許呼叫者更新物件已命名影子的範例政策：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:ListNamedShadowsForThing",
      "Resource": [
        "arn:aws:iot:region:account:thing/thing"
      ]
    }
  ]
}