裝置影子 REST API - AWS IoT Core
GetThingShadowUpdateThingShadowDeleteThingShadowListNamedShadowsForThing

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

裝置影子 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 URL 詳細資訊頁面的 Device Shadow 區段URI中檢視端點。

端點格式如下：

identifier.iot.region.amazonaws.com

影子RESTAPI遵循與 中所述相同的HTTPS通訊協定/連接埠映射裝置通訊協定。

注意

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

您也可以使用 作為 查詢參數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"
      ]
    }
  ]
}