IoT Data Model Updates (#3365)

As part of this release, we are introducing a new feature called named shadow, which extends the capability of AWS IoT Device Shadow to support multiple shadows for a single IoT device. With this release, customers can store different device state data into different shadows, and as a result access only the required state data when needed and reduce individual shadow size.
aws · Jun 11, 2020 · 685e18c · 685e18c
1 parent 017cb1d
commit 685e18c
Show file tree

Hide file tree

Showing 7 changed files with 397 additions and 26 deletions.
diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md
@@ -1,4 +1,5 @@
 ### SDK Features
+* `service/iotdataplane`: As part of this release, we are introducing a new feature called named shadow, which extends the capability of AWS IoT Device Shadow to support multiple shadows for a single IoT device. With this release, customers can store different device state data into different shadows, and as a result access only the required state data when needed and reduce individual shadow size.
 
 ### SDK Enhancements
 

diff --git a/models/apis/iot-data/2015-05-28/api-2.json b/models/apis/iot-data/2015-05-28/api-2.json
@@ -1,13 +1,14 @@
 {
   "version":"2.0",
   "metadata":{
-    "uid":"iot-data-2015-05-28",
     "apiVersion":"2015-05-28",
     "endpointPrefix":"data.iot",
     "protocol":"rest-json",
     "serviceFullName":"AWS IoT Data Plane",
+    "serviceId":"IoT Data Plane",
     "signatureVersion":"v4",
-    "signingName":"iotdata"
+    "signingName":"iotdata",
+    "uid":"iot-data-2015-05-28"
   },
   "operations":{
     "DeleteThingShadow":{
@@ -48,6 +49,24 @@
         {"shape":"UnsupportedDocumentEncodingException"}
       ]
     },
+    "ListNamedShadowsForThing":{
+      "name":"ListNamedShadowsForThing",
+      "http":{
+        "method":"GET",
+        "requestUri":"/api/things/shadow/ListNamedShadowsForThing/{thingName}"
+      },
+      "input":{"shape":"ListNamedShadowsForThingRequest"},
+      "output":{"shape":"ListNamedShadowsForThingResponse"},
+      "errors":[
+        {"shape":"ResourceNotFoundException"},
+        {"shape":"InvalidRequestException"},
+        {"shape":"ThrottlingException"},
+        {"shape":"UnauthorizedException"},
+        {"shape":"ServiceUnavailableException"},
+        {"shape":"InternalFailureException"},
+        {"shape":"MethodNotAllowedException"}
+      ]
+    },
     "Publish":{
       "name":"Publish",
       "http":{
@@ -87,7 +106,7 @@
     "ConflictException":{
       "type":"structure",
       "members":{
-        "message":{"shape":"ErrorMessage"}
+        "message":{"shape":"errorMessage"}
       },
       "error":{"httpStatusCode":409},
       "exception":true
@@ -100,6 +119,11 @@
           "shape":"ThingName",
           "location":"uri",
           "locationName":"thingName"
+        },
+        "shadowName":{
+          "shape":"ShadowName",
+          "location":"querystring",
+          "locationName":"name"
         }
       }
     },
@@ -111,7 +135,6 @@
       },
       "payload":"payload"
     },
-    "ErrorMessage":{"type":"string"},
     "GetThingShadowRequest":{
       "type":"structure",
       "required":["thingName"],
@@ -120,6 +143,11 @@
           "shape":"ThingName",
           "location":"uri",
           "locationName":"thingName"
+        },
+        "shadowName":{
+          "shape":"ShadowName",
+          "location":"querystring",
+          "locationName":"name"
         }
       }
     },
@@ -148,14 +176,53 @@
       "exception":true
     },
     "JsonDocument":{"type":"blob"},
+    "ListNamedShadowsForThingRequest":{
+      "type":"structure",
+      "required":["thingName"],
+      "members":{
+        "thingName":{
+          "shape":"ThingName",
+          "location":"uri",
+          "locationName":"thingName"
+        },
+        "nextToken":{
+          "shape":"NextToken",
+          "location":"querystring",
+          "locationName":"nextToken"
+        },
+        "pageSize":{
+          "shape":"PageSize",
+          "location":"querystring",
+          "locationName":"pageSize"
+        }
+      }
+    },
+    "ListNamedShadowsForThingResponse":{
+      "type":"structure",
+      "members":{
+        "results":{"shape":"NamedShadowList"},
+        "nextToken":{"shape":"NextToken"},
+        "timestamp":{"shape":"Timestamp"}
+      }
+    },
     "MethodNotAllowedException":{
       "type":"structure",
       "members":{
-        "message":{"shape":"ErrorMessage"}
+        "message":{"shape":"errorMessage"}
       },
       "error":{"httpStatusCode":405},
       "exception":true
     },
+    "NamedShadowList":{
+      "type":"list",
+      "member":{"shape":"ShadowName"}
+    },
+    "NextToken":{"type":"string"},
+    "PageSize":{
+      "type":"integer",
+      "max":100,
+      "min":1
+    },
     "Payload":{"type":"blob"},
     "PublishRequest":{
       "type":"structure",
@@ -183,7 +250,7 @@
     "RequestEntityTooLargeException":{
       "type":"structure",
       "members":{
-        "message":{"shape":"ErrorMessage"}
+        "message":{"shape":"errorMessage"}
       },
       "error":{"httpStatusCode":413},
       "exception":true
@@ -205,11 +272,17 @@
       "exception":true,
       "fault":true
     },
+    "ShadowName":{
+      "type":"string",
+      "max":64,
+      "min":1,
+      "pattern":"[a-zA-Z0-9:_-]+"
+    },
     "ThingName":{
       "type":"string",
       "max":128,
       "min":1,
-      "pattern":"[a-zA-Z0-9_-]+"
+      "pattern":"[a-zA-Z0-9:_-]+"
     },
     "ThrottlingException":{
       "type":"structure",
@@ -219,6 +292,7 @@
       "error":{"httpStatusCode":429},
       "exception":true
     },
+    "Timestamp":{"type":"long"},
     "Topic":{"type":"string"},
     "UnauthorizedException":{
       "type":"structure",
@@ -248,6 +322,11 @@
           "location":"uri",
           "locationName":"thingName"
         },
+        "shadowName":{
+          "shape":"ShadowName",
+          "location":"querystring",
+          "locationName":"name"
+        },
         "payload":{"shape":"JsonDocument"}
       },
       "payload":"payload"

diff --git a/models/apis/iot-data/2015-05-28/docs-2.json b/models/apis/iot-data/2015-05-28/docs-2.json
@@ -1,11 +1,12 @@
 {
   "version": "2.0",
-  "service": "<fullname>AWS IoT</fullname> <p>AWS IoT-Data enables secure, bi-directional communication between Internet-connected things (such as sensors, actuators, embedded devices, or smart appliances) and the AWS cloud. It implements a broker for applications and things to publish messages over HTTP (Publish) and retrieve, update, and delete thing shadows. A thing shadow is a persistent representation of your things and their state in the AWS cloud.</p>",
+  "service": "<fullname>AWS IoT</fullname> <p>AWS IoT-Data enables secure, bi-directional communication between Internet-connected things (such as sensors, actuators, embedded devices, or smart appliances) and the AWS cloud. It implements a broker for applications and things to publish messages over HTTP (Publish) and retrieve, update, and delete shadows. A shadow is a persistent representation of your things and their state in the AWS cloud.</p> <p>Find the endpoint address for actions in the AWS IoT data plane by running this CLI command:</p> <p> <code>aws iot describe-endpoint --endpoint-type iot:Data-ATS</code> </p> <p>The service name used by <a href=\"https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html\">AWS Signature Version 4</a> to sign requests is: <i>iotdevicegateway</i>.</p>",
   "operations": {
-    "DeleteThingShadow": "<p>Deletes the thing shadow for the specified thing.</p> <p>For more information, see <a href=\"http://docs.aws.amazon.com/iot/latest/developerguide/API_DeleteThingShadow.html\">DeleteThingShadow</a> in the <i>AWS IoT Developer Guide</i>.</p>",
-    "GetThingShadow": "<p>Gets the thing shadow for the specified thing.</p> <p>For more information, see <a href=\"http://docs.aws.amazon.com/iot/latest/developerguide/API_GetThingShadow.html\">GetThingShadow</a> in the <i>AWS IoT Developer Guide</i>.</p>",
-    "Publish": "<p>Publishes state information.</p> <p>For more information, see <a href=\"http://docs.aws.amazon.com/iot/latest/developerguide/protocols.html#http\">HTTP Protocol</a> in the <i>AWS IoT Developer Guide</i>.</p>",
-    "UpdateThingShadow": "<p>Updates the thing shadow for the specified thing.</p> <p>For more information, see <a href=\"http://docs.aws.amazon.com/iot/latest/developerguide/API_UpdateThingShadow.html\">UpdateThingShadow</a> in the <i>AWS IoT Developer Guide</i>.</p>"
+    "DeleteThingShadow": "<p>Deletes the shadow for the specified thing.</p> <p>For more information, see <a href=\"http://docs.aws.amazon.com/iot/latest/developerguide/API_DeleteThingShadow.html\">DeleteThingShadow</a> in the AWS IoT Developer Guide.</p>",
+    "GetThingShadow": "<p>Gets the shadow for the specified thing.</p> <p>For more information, see <a href=\"http://docs.aws.amazon.com/iot/latest/developerguide/API_GetThingShadow.html\">GetThingShadow</a> in the AWS IoT Developer Guide.</p>",
+    "ListNamedShadowsForThing": "<p>Lists the shadows for the specified thing.</p>",
+    "Publish": "<p>Publishes state information.</p> <p>For more information, see <a href=\"http://docs.aws.amazon.com/iot/latest/developerguide/protocols.html#http\">HTTP Protocol</a> in the AWS IoT Developer Guide.</p>",
+    "UpdateThingShadow": "<p>Updates the shadow for the specified thing.</p> <p>For more information, see <a href=\"http://docs.aws.amazon.com/iot/latest/developerguide/API_UpdateThingShadow.html\">UpdateThingShadow</a> in the AWS IoT Developer Guide.</p>"
   },
   "shapes": {
     "ConflictException": {
@@ -23,14 +24,6 @@
       "refs": {
       }
     },
-    "ErrorMessage": {
-      "base": null,
-      "refs": {
-        "ConflictException$message": "<p>The message for the exception.</p>",
-        "MethodNotAllowedException$message": "<p>The message for the exception.</p>",
-        "RequestEntityTooLargeException$message": "<p>The message for the exception.</p>"
-      }
-    },
     "GetThingShadowRequest": {
       "base": "<p>The input for the GetThingShadow operation.</p>",
       "refs": {
@@ -60,11 +53,40 @@
         "UpdateThingShadowResponse$payload": "<p>The state information, in JSON format.</p>"
       }
     },
+    "ListNamedShadowsForThingRequest": {
+      "base": null,
+      "refs": {
+      }
+    },
+    "ListNamedShadowsForThingResponse": {
+      "base": null,
+      "refs": {
+      }
+    },
     "MethodNotAllowedException": {
       "base": "<p>The specified combination of HTTP verb and URI is not supported.</p>",
       "refs": {
       }
     },
+    "NamedShadowList": {
+      "base": null,
+      "refs": {
+        "ListNamedShadowsForThingResponse$results": "<p>The list of shadows for the specified thing.</p>"
+      }
+    },
+    "NextToken": {
+      "base": null,
+      "refs": {
+        "ListNamedShadowsForThingRequest$nextToken": "<p>The token to retrieve the next set of results.</p>",
+        "ListNamedShadowsForThingResponse$nextToken": "<p>The token for the next set of results, or null if there are no additional results.</p>"
+      }
+    },
+    "PageSize": {
+      "base": null,
+      "refs": {
+        "ListNamedShadowsForThingRequest$pageSize": "<p>The result page size.</p>"
+      }
+    },
     "Payload": {
       "base": null,
       "refs": {
@@ -97,11 +119,21 @@
       "refs": {
       }
     },
+    "ShadowName": {
+      "base": null,
+      "refs": {
+        "DeleteThingShadowRequest$shadowName": "<p>The name of the shadow.</p>",
+        "GetThingShadowRequest$shadowName": "<p>The name of the shadow.</p>",
+        "NamedShadowList$member": null,
+        "UpdateThingShadowRequest$shadowName": "<p>The name of the shadow.</p>"
+      }
+    },
     "ThingName": {
       "base": null,
       "refs": {
         "DeleteThingShadowRequest$thingName": "<p>The name of the thing.</p>",
         "GetThingShadowRequest$thingName": "<p>The name of the thing.</p>",
+        "ListNamedShadowsForThingRequest$thingName": "<p>The name of the thing.</p>",
         "UpdateThingShadowRequest$thingName": "<p>The name of the thing.</p>"
       }
     },
@@ -110,6 +142,12 @@
       "refs": {
       }
     },
+    "Timestamp": {
+      "base": null,
+      "refs": {
+        "ListNamedShadowsForThingResponse$timestamp": "<p>The Epoch date and time the response was generated by AWS IoT.</p>"
+      }
+    },
     "Topic": {
       "base": null,
       "refs": {
@@ -139,8 +177,11 @@
     "errorMessage": {
       "base": null,
       "refs": {
+        "ConflictException$message": "<p>The message for the exception.</p>",
         "InternalFailureException$message": "<p>The message for the exception.</p>",
         "InvalidRequestException$message": "<p>The message for the exception.</p>",
+        "MethodNotAllowedException$message": "<p>The message for the exception.</p>",
+        "RequestEntityTooLargeException$message": "<p>The message for the exception.</p>",
         "ResourceNotFoundException$message": "<p>The message for the exception.</p>",
         "ServiceUnavailableException$message": "<p>The message for the exception.</p>",
         "ThrottlingException$message": "<p>The message for the exception.</p>",

diff --git a/models/apis/iot-data/2015-05-28/paginators-1.json b/models/apis/iot-data/2015-05-28/paginators-1.json
@@ -0,0 +1,4 @@
+{
+  "pagination": {
+  }
+}