feat(client-iot-jobs-data-plane): General Availability (GA) release of AWS IoT Device Management - Commands, to trigger light-weight remote actions on targeted devices

Author: awstools

Diff for: clients/client-iot-jobs-data-plane/README.md

@@ -6,17 +6,27 @@
 
 AWS SDK for JavaScript IoTJobsDataPlane Client for Node.js, Browser and React Native.
 
-<p>AWS IoT Jobs is a service that allows you to define a set of jobs — remote operations that are sent to
-and executed on one or more devices connected to AWS IoT. For example, you can define a job that instructs a
-set of devices to download and install application or firmware updates, reboot, rotate certificates, or perform
-remote troubleshooting operations.</p>
-<p> To create a job, you make a job document which is a description of the remote operations to be
-performed, and you specify a list of targets that should perform the operations. The targets can be individual
-things, thing groups or both.</p>
-<p> AWS IoT Jobs sends a message to inform the targets that a job is available. The target starts the
-execution of the job by downloading the job document, performing the operations it specifies, and reporting its
-progress to AWS IoT. The Jobs service provides commands to track the progress of a job on a specific target and
-for all the targets of the job</p>
+<p>IoT Jobs is a service that allows you to define a set of jobs — remote operations
+that are sent to and executed on one or more devices connected to Amazon Web Services IoT Core. For example,
+you can define a job that instructs a set of devices to download and install application or
+firmware updates, reboot, rotate certificates, or perform remote troubleshooting
+operations.</p>
+<p>Find the endpoint address for actions in the IoT jobs data plane by running this
+CLI command:</p>
+<p>
+<code>aws iot describe-endpoint --endpoint-type iot:Jobs</code>
+</p>
+<p>The service name used by <a href="https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html">Amazon Web Services
+Signature Version 4</a> to sign requests is:
+<i>iot-jobs-data</i>.</p>
+<p> To create a job, you make a job document which is a description of the remote
+operations to be performed, and you specify a list of targets that should perform the
+operations. The targets can be individual things, thing groups or both.</p>
+<p> IoT Jobs sends a message to inform the targets that a job is available. The target
+starts the execution of the job by downloading the job document, performing the operations
+it specifies, and reporting its progress to Amazon Web Services IoT Core. The Jobs service provides commands
+to track the progress of a job on a specific target and for all the targets of the
+job</p>
 
 ## Installing
 
@@ -228,6 +238,14 @@ GetPendingJobExecutions
 
 [Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/iot-jobs-data-plane/command/GetPendingJobExecutionsCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-iot-jobs-data-plane/Interface/GetPendingJobExecutionsCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-iot-jobs-data-plane/Interface/GetPendingJobExecutionsCommandOutput/)
 
+</details>
+<details>
+<summary>
+StartCommandExecution
+</summary>
+
+[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/iot-jobs-data-plane/command/StartCommandExecutionCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-iot-jobs-data-plane/Interface/StartCommandExecutionCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-iot-jobs-data-plane/Interface/StartCommandExecutionCommandOutput/)
+
 </details>
 <details>
 <summary>

Diff for: clients/client-iot-jobs-data-plane/package.json

@@ -58,7 +58,9 @@
     "@smithy/util-middleware": "^3.0.10",
     "@smithy/util-retry": "^3.0.10",
     "@smithy/util-utf8": "^3.0.0",
-    "tslib": "^2.6.2"
+    "@types/uuid": "^9.0.1",
+    "tslib": "^2.6.2",
+    "uuid": "^9.0.1"
   },
   "devDependencies": {
     "@tsconfig/node16": "16.1.3",

Diff for: clients/client-iot-jobs-data-plane/src/IoTJobsDataPlane.ts

@@ -12,6 +12,11 @@ import {
   GetPendingJobExecutionsCommandInput,
   GetPendingJobExecutionsCommandOutput,
 } from "./commands/GetPendingJobExecutionsCommand";
+import {
+  StartCommandExecutionCommand,
+  StartCommandExecutionCommandInput,
+  StartCommandExecutionCommandOutput,
+} from "./commands/StartCommandExecutionCommand";
 import {
   StartNextPendingJobExecutionCommand,
   StartNextPendingJobExecutionCommandInput,
@@ -27,6 +32,7 @@ import { IoTJobsDataPlaneClient, IoTJobsDataPlaneClientConfig } from "./IoTJobsD
 const commands = {
   DescribeJobExecutionCommand,
   GetPendingJobExecutionsCommand,
+  StartCommandExecutionCommand,
   StartNextPendingJobExecutionCommand,
   UpdateJobExecutionCommand,
 };
@@ -66,6 +72,23 @@ export interface IoTJobsDataPlane {
     cb: (err: any, data?: GetPendingJobExecutionsCommandOutput) => void
   ): void;
 
+  /**
+   * @see {@link StartCommandExecutionCommand}
+   */
+  startCommandExecution(
+    args: StartCommandExecutionCommandInput,
+    options?: __HttpHandlerOptions
+  ): Promise<StartCommandExecutionCommandOutput>;
+  startCommandExecution(
+    args: StartCommandExecutionCommandInput,
+    cb: (err: any, data?: StartCommandExecutionCommandOutput) => void
+  ): void;
+  startCommandExecution(
+    args: StartCommandExecutionCommandInput,
+    options: __HttpHandlerOptions,
+    cb: (err: any, data?: StartCommandExecutionCommandOutput) => void
+  ): void;
+
   /**
    * @see {@link StartNextPendingJobExecutionCommand}
    */
@@ -102,17 +125,27 @@ export interface IoTJobsDataPlane {
 }
 
 /**
- * <p>AWS IoT Jobs is a service that allows you to define a set of jobs — remote operations that are sent to
- *          and executed on one or more devices connected to AWS IoT. For example, you can define a job that instructs a
- *          set of devices to download and install application or firmware updates, reboot, rotate certificates, or perform
- *          remote troubleshooting operations.</p>
- *          <p> To create a job, you make a job document which is a description of the remote operations to be
- *          performed, and you specify a list of targets that should perform the operations. The targets can be individual
- *          things, thing groups or both.</p>
- *          <p> AWS IoT Jobs sends a message to inform the targets that a job is available. The target starts the
- *          execution of the job by downloading the job document, performing the operations it specifies, and reporting its
- *          progress to AWS IoT. The Jobs service provides commands to track the progress of a job on a specific target and
- *          for all the targets of the job</p>
+ * <p>IoT Jobs is a service that allows you to define a set of jobs — remote operations
+ *          that are sent to and executed on one or more devices connected to Amazon Web Services IoT Core. For example,
+ *          you can define a job that instructs a set of devices to download and install application or
+ *          firmware updates, reboot, rotate certificates, or perform remote troubleshooting
+ *          operations.</p>
+ *          <p>Find the endpoint address for actions in the IoT jobs data plane by running this
+ *          CLI command:</p>
+ *          <p>
+ *             <code>aws iot describe-endpoint --endpoint-type iot:Jobs</code>
+ *          </p>
+ *          <p>The service name used by <a href="https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html">Amazon Web Services
+ *             Signature Version 4</a> to sign requests is:
+ *          <i>iot-jobs-data</i>.</p>
+ *          <p> To create a job, you make a job document which is a description of the remote
+ *          operations to be performed, and you specify a list of targets that should perform the
+ *          operations. The targets can be individual things, thing groups or both.</p>
+ *          <p> IoT Jobs sends a message to inform the targets that a job is available. The target
+ *          starts the execution of the job by downloading the job document, performing the operations
+ *          it specifies, and reporting its progress to Amazon Web Services IoT Core. The Jobs service provides commands
+ *          to track the progress of a job on a specific target and for all the targets of the
+ *          job</p>
  * @public
  */
 export class IoTJobsDataPlane extends IoTJobsDataPlaneClient implements IoTJobsDataPlane {}

Diff for: clients/client-iot-jobs-data-plane/src/IoTJobsDataPlaneClient.ts

@@ -61,6 +61,10 @@ import {
   GetPendingJobExecutionsCommandInput,
   GetPendingJobExecutionsCommandOutput,
 } from "./commands/GetPendingJobExecutionsCommand";
+import {
+  StartCommandExecutionCommandInput,
+  StartCommandExecutionCommandOutput,
+} from "./commands/StartCommandExecutionCommand";
 import {
   StartNextPendingJobExecutionCommandInput,
   StartNextPendingJobExecutionCommandOutput,
@@ -83,6 +87,7 @@ export { __Client };
 export type ServiceInputTypes =
   | DescribeJobExecutionCommandInput
   | GetPendingJobExecutionsCommandInput
+  | StartCommandExecutionCommandInput
   | StartNextPendingJobExecutionCommandInput
   | UpdateJobExecutionCommandInput;
 
@@ -92,6 +97,7 @@ export type ServiceInputTypes =
 export type ServiceOutputTypes =
   | DescribeJobExecutionCommandOutput
   | GetPendingJobExecutionsCommandOutput
+  | StartCommandExecutionCommandOutput
   | StartNextPendingJobExecutionCommandOutput
   | UpdateJobExecutionCommandOutput;
 
@@ -267,17 +273,27 @@ export type IoTJobsDataPlaneClientResolvedConfigType = __SmithyResolvedConfigura
 export interface IoTJobsDataPlaneClientResolvedConfig extends IoTJobsDataPlaneClientResolvedConfigType {}
 
 /**
- * <p>AWS IoT Jobs is a service that allows you to define a set of jobs — remote operations that are sent to
- *          and executed on one or more devices connected to AWS IoT. For example, you can define a job that instructs a
- *          set of devices to download and install application or firmware updates, reboot, rotate certificates, or perform
- *          remote troubleshooting operations.</p>
- *          <p> To create a job, you make a job document which is a description of the remote operations to be
- *          performed, and you specify a list of targets that should perform the operations. The targets can be individual
- *          things, thing groups or both.</p>
- *          <p> AWS IoT Jobs sends a message to inform the targets that a job is available. The target starts the
- *          execution of the job by downloading the job document, performing the operations it specifies, and reporting its
- *          progress to AWS IoT. The Jobs service provides commands to track the progress of a job on a specific target and
- *          for all the targets of the job</p>
+ * <p>IoT Jobs is a service that allows you to define a set of jobs — remote operations
+ *          that are sent to and executed on one or more devices connected to Amazon Web Services IoT Core. For example,
+ *          you can define a job that instructs a set of devices to download and install application or
+ *          firmware updates, reboot, rotate certificates, or perform remote troubleshooting
+ *          operations.</p>
+ *          <p>Find the endpoint address for actions in the IoT jobs data plane by running this
+ *          CLI command:</p>
+ *          <p>
+ *             <code>aws iot describe-endpoint --endpoint-type iot:Jobs</code>
+ *          </p>
+ *          <p>The service name used by <a href="https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html">Amazon Web Services
+ *             Signature Version 4</a> to sign requests is:
+ *          <i>iot-jobs-data</i>.</p>
+ *          <p> To create a job, you make a job document which is a description of the remote
+ *          operations to be performed, and you specify a list of targets that should perform the
+ *          operations. The targets can be individual things, thing groups or both.</p>
+ *          <p> IoT Jobs sends a message to inform the targets that a job is available. The target
+ *          starts the execution of the job by downloading the job document, performing the operations
+ *          it specifies, and reporting its progress to Amazon Web Services IoT Core. The Jobs service provides commands
+ *          to track the progress of a job on a specific target and for all the targets of the
+ *          job</p>
  * @public
  */
 export class IoTJobsDataPlaneClient extends __Client<

Diff for: clients/client-iot-jobs-data-plane/src/commands/DescribeJobExecutionCommand.ts

@@ -29,6 +29,7 @@ export interface DescribeJobExecutionCommandOutput extends DescribeJobExecutionR
 
 /**
  * <p>Gets details of a job execution.</p>
+ *          <p>Requires permission to access the <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-actions-as-permissions">DescribeJobExecution</a> action.</p>
  * @example
  * Use a bare-bones client and the command you need to make an API call.
  * ```javascript
@@ -73,7 +74,7 @@ export interface DescribeJobExecutionCommandOutput extends DescribeJobExecutionR
  *  <p>The certificate is invalid.</p>
  *
  * @throws {@link InvalidRequestException} (client fault)
- *  <p>The contents of the request were invalid. For example, this code is returned when an UpdateJobExecution request contains invalid status details. The message contains details about the error.</p>
+ *  <p>The contents of the request were invalid.</p>
  *
  * @throws {@link ResourceNotFoundException} (client fault)
  *  <p>The specified resource does not exist.</p>

Diff for: clients/client-iot-jobs-data-plane/src/commands/GetPendingJobExecutionsCommand.ts

@@ -29,6 +29,7 @@ export interface GetPendingJobExecutionsCommandOutput extends GetPendingJobExecu
 
 /**
  * <p>Gets the list of all jobs for a thing that are not in a terminal status.</p>
+ *          <p>Requires permission to access the <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-actions-as-permissions">GetPendingJobExecutions</a> action.</p>
  * @example
  * Use a bare-bones client and the command you need to make an API call.
  * ```javascript
@@ -75,7 +76,7 @@ export interface GetPendingJobExecutionsCommandOutput extends GetPendingJobExecu
  *  <p>The certificate is invalid.</p>
  *
  * @throws {@link InvalidRequestException} (client fault)
- *  <p>The contents of the request were invalid. For example, this code is returned when an UpdateJobExecution request contains invalid status details. The message contains details about the error.</p>
+ *  <p>The contents of the request were invalid.</p>
  *
  * @throws {@link ResourceNotFoundException} (client fault)
  *  <p>The specified resource does not exist.</p>

Diff for: clients/client-iot-jobs-data-plane/src/commands/StartCommandExecutionCommand.ts

@@ -0,0 +1,125 @@
+// smithy-typescript generated code
+import { getEndpointPlugin } from "@smithy/middleware-endpoint";
+import { getSerdePlugin } from "@smithy/middleware-serde";
+import { Command as $Command } from "@smithy/smithy-client";
+import { MetadataBearer as __MetadataBearer } from "@smithy/types";
+
+import { commonParams } from "../endpoint/EndpointParameters";
+import { IoTJobsDataPlaneClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from "../IoTJobsDataPlaneClient";
+import { StartCommandExecutionRequest, StartCommandExecutionResponse } from "../models/models_0";
+import { de_StartCommandExecutionCommand, se_StartCommandExecutionCommand } from "../protocols/Aws_restJson1";
+
+/**
+ * @public
+ */
+export type { __MetadataBearer };
+export { $Command };
+/**
+ * @public
+ *
+ * The input for {@link StartCommandExecutionCommand}.
+ */
+export interface StartCommandExecutionCommandInput extends StartCommandExecutionRequest {}
+/**
+ * @public
+ *
+ * The output of {@link StartCommandExecutionCommand}.
+ */
+export interface StartCommandExecutionCommandOutput extends StartCommandExecutionResponse, __MetadataBearer {}
+
+/**
+ * <p>Using the command created with the <code>CreateCommand</code> API, start a command
+ *          execution on a specific device.</p>
+ * @example
+ * Use a bare-bones client and the command you need to make an API call.
+ * ```javascript
+ * import { IoTJobsDataPlaneClient, StartCommandExecutionCommand } from "@aws-sdk/client-iot-jobs-data-plane"; // ES Modules import
+ * // const { IoTJobsDataPlaneClient, StartCommandExecutionCommand } = require("@aws-sdk/client-iot-jobs-data-plane"); // CommonJS import
+ * const client = new IoTJobsDataPlaneClient(config);
+ * const input = { // StartCommandExecutionRequest
+ *   targetArn: "STRING_VALUE", // required
+ *   commandArn: "STRING_VALUE", // required
+ *   parameters: { // CommandExecutionParameterMap
+ *     "<keys>": { // CommandParameterValue
+ *       S: "STRING_VALUE",
+ *       B: true || false,
+ *       I: Number("int"),
+ *       L: Number("long"),
+ *       D: Number("double"),
+ *       BIN: new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")
+ *       UL: "STRING_VALUE",
+ *     },
+ *   },
+ *   executionTimeoutSeconds: Number("long"),
+ *   clientToken: "STRING_VALUE",
+ * };
+ * const command = new StartCommandExecutionCommand(input);
+ * const response = await client.send(command);
+ * // { // StartCommandExecutionResponse
+ * //   executionId: "STRING_VALUE",
+ * // };
+ *
+ * ```
+ *
+ * @param StartCommandExecutionCommandInput - {@link StartCommandExecutionCommandInput}
+ * @returns {@link StartCommandExecutionCommandOutput}
+ * @see {@link StartCommandExecutionCommandInput} for command's `input` shape.
+ * @see {@link StartCommandExecutionCommandOutput} for command's `response` shape.
+ * @see {@link IoTJobsDataPlaneClientResolvedConfig | config} for IoTJobsDataPlaneClient's `config` shape.
+ *
+ * @throws {@link ConflictException} (client fault)
+ *  <p>A conflict has occurred when performing the API request.</p>
+ *
+ * @throws {@link InternalServerException} (server fault)
+ *  <p>An internal server error occurred when performing the API request.</p>
+ *
+ * @throws {@link ResourceNotFoundException} (client fault)
+ *  <p>The specified resource does not exist.</p>
+ *
+ * @throws {@link ServiceQuotaExceededException} (client fault)
+ *  <p>The service quota has been exceeded for this request.</p>
+ *
+ * @throws {@link ThrottlingException} (client fault)
+ *  <p>The rate exceeds the limit.</p>
+ *
+ * @throws {@link ValidationException} (client fault)
+ *  <p>A validation error occurred when performing the API request.</p>
+ *
+ * @throws {@link IoTJobsDataPlaneServiceException}
+ * <p>Base exception class for all service exceptions from IoTJobsDataPlane service.</p>
+ *
+ * @public
+ */
+export class StartCommandExecutionCommand extends $Command
+  .classBuilder<
+    StartCommandExecutionCommandInput,
+    StartCommandExecutionCommandOutput,
+    IoTJobsDataPlaneClientResolvedConfig,
+    ServiceInputTypes,
+    ServiceOutputTypes
+  >()
+  .ep(commonParams)
+  .m(function (this: any, Command: any, cs: any, config: IoTJobsDataPlaneClientResolvedConfig, o: any) {
+    return [
+      getSerdePlugin(config, this.serialize, this.deserialize),
+      getEndpointPlugin(config, Command.getEndpointParameterInstructions()),
+    ];
+  })
+  .s("IotLaserThingJobManagerExternalService", "StartCommandExecution", {})
+  .n("IoTJobsDataPlaneClient", "StartCommandExecutionCommand")
+  .f(void 0, void 0)
+  .ser(se_StartCommandExecutionCommand)
+  .de(de_StartCommandExecutionCommand)
+  .build() {
+  /** @internal type navigation helper, not in runtime. */
+  protected declare static __types: {
+    api: {
+      input: StartCommandExecutionRequest;
+      output: StartCommandExecutionResponse;
+    };
+    sdk: {
+      input: StartCommandExecutionCommandInput;
+      output: StartCommandExecutionCommandOutput;
+    };
+  };
+}