Skip to content

Commit

Permalink
feat(client-iot-jobs-data-plane): General Availability (GA) release o…
Browse files Browse the repository at this point in the history
…f AWS IoT Device Management - Commands, to trigger light-weight remote actions on targeted devices
  • Loading branch information
awstools committed Nov 21, 2024
1 parent 0f45892 commit b203a9c
Show file tree
Hide file tree
Showing 14 changed files with 1,056 additions and 144 deletions.
40 changes: 29 additions & 11 deletions clients/client-iot-jobs-data-plane/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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>
Expand Down
4 changes: 3 additions & 1 deletion clients/client-iot-jobs-data-plane/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
55 changes: 44 additions & 11 deletions clients/client-iot-jobs-data-plane/src/IoTJobsDataPlane.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,11 @@ import {
GetPendingJobExecutionsCommandInput,
GetPendingJobExecutionsCommandOutput,
} from "./commands/GetPendingJobExecutionsCommand";
import {
StartCommandExecutionCommand,
StartCommandExecutionCommandInput,
StartCommandExecutionCommandOutput,
} from "./commands/StartCommandExecutionCommand";
import {
StartNextPendingJobExecutionCommand,
StartNextPendingJobExecutionCommandInput,
Expand All @@ -27,6 +32,7 @@ import { IoTJobsDataPlaneClient, IoTJobsDataPlaneClientConfig } from "./IoTJobsD
const commands = {
DescribeJobExecutionCommand,
GetPendingJobExecutionsCommand,
StartCommandExecutionCommand,
StartNextPendingJobExecutionCommand,
UpdateJobExecutionCommand,
};
Expand Down Expand Up @@ -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}
*/
Expand Down Expand Up @@ -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 {}
Expand Down
38 changes: 27 additions & 11 deletions clients/client-iot-jobs-data-plane/src/IoTJobsDataPlaneClient.ts
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,10 @@ import {
GetPendingJobExecutionsCommandInput,
GetPendingJobExecutionsCommandOutput,
} from "./commands/GetPendingJobExecutionsCommand";
import {
StartCommandExecutionCommandInput,
StartCommandExecutionCommandOutput,
} from "./commands/StartCommandExecutionCommand";
import {
StartNextPendingJobExecutionCommandInput,
StartNextPendingJobExecutionCommandOutput,
Expand All @@ -83,6 +87,7 @@ export { __Client };
export type ServiceInputTypes =
| DescribeJobExecutionCommandInput
| GetPendingJobExecutionsCommandInput
| StartCommandExecutionCommandInput
| StartNextPendingJobExecutionCommandInput
| UpdateJobExecutionCommandInput;

Expand All @@ -92,6 +97,7 @@ export type ServiceInputTypes =
export type ServiceOutputTypes =
| DescribeJobExecutionCommandOutput
| GetPendingJobExecutionsCommandOutput
| StartCommandExecutionCommandOutput
| StartNextPendingJobExecutionCommandOutput
| UpdateJobExecutionCommandOutput;

Expand Down Expand Up @@ -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<
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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>
Expand Down
Original file line number Diff line number Diff line change
@@ -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;
};
};
}
Loading

0 comments on commit b203a9c

Please sign in to comment.