feat(client-synthetics): Add support to test a canary update by invoking a dry run of a canary. This behavior can be used via the new StartCanaryDryRun API along with new fields in UpdateCanary to apply dry run changes. Also includes changes in GetCanary and GetCanaryRuns to support retrieving dry run configurations.

awstools · awstools · commit 338d4016bf3d · 2025-05-07T18:18:15.000Z
diff --git a/clients/client-synthetics/README.md b/clients/client-synthetics/README.md
@@ -353,6 +353,14 @@ StartCanary
 
 [Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/synthetics/command/StartCanaryCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-synthetics/Interface/StartCanaryCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-synthetics/Interface/StartCanaryCommandOutput/)
 
+</details>
+<details>
+<summary>
+StartCanaryDryRun
+</summary>
+
+[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/synthetics/command/StartCanaryDryRunCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-synthetics/Interface/StartCanaryDryRunCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-synthetics/Interface/StartCanaryDryRunCommandOutput/)
+
 </details>
 <details>
 <summary>
diff --git a/clients/client-synthetics/src/Synthetics.ts b/clients/client-synthetics/src/Synthetics.ts
@@ -63,6 +63,11 @@ import {
   ListTagsForResourceCommandOutput,
 } from "./commands/ListTagsForResourceCommand";
 import { StartCanaryCommand, StartCanaryCommandInput, StartCanaryCommandOutput } from "./commands/StartCanaryCommand";
+import {
+  StartCanaryDryRunCommand,
+  StartCanaryDryRunCommandInput,
+  StartCanaryDryRunCommandOutput,
+} from "./commands/StartCanaryDryRunCommand";
 import { StopCanaryCommand, StopCanaryCommandInput, StopCanaryCommandOutput } from "./commands/StopCanaryCommand";
 import { TagResourceCommand, TagResourceCommandInput, TagResourceCommandOutput } from "./commands/TagResourceCommand";
 import {
@@ -95,6 +100,7 @@ const commands = {
   ListGroupsCommand,
   ListTagsForResourceCommand,
   StartCanaryCommand,
+  StartCanaryDryRunCommand,
   StopCanaryCommand,
   TagResourceCommand,
   UntagResourceCommand,
@@ -341,6 +347,23 @@ export interface Synthetics {
     cb: (err: any, data?: StartCanaryCommandOutput) => void
   ): void;
 
+  /**
+   * @see {@link StartCanaryDryRunCommand}
+   */
+  startCanaryDryRun(
+    args: StartCanaryDryRunCommandInput,
+    options?: __HttpHandlerOptions
+  ): Promise<StartCanaryDryRunCommandOutput>;
+  startCanaryDryRun(
+    args: StartCanaryDryRunCommandInput,
+    cb: (err: any, data?: StartCanaryDryRunCommandOutput) => void
+  ): void;
+  startCanaryDryRun(
+    args: StartCanaryDryRunCommandInput,
+    options: __HttpHandlerOptions,
+    cb: (err: any, data?: StartCanaryDryRunCommandOutput) => void
+  ): void;
+
   /**
    * @see {@link StopCanaryCommand}
    */
diff --git a/clients/client-synthetics/src/SyntheticsClient.ts b/clients/client-synthetics/src/SyntheticsClient.ts
@@ -85,6 +85,7 @@ import {
   ListTagsForResourceCommandOutput,
 } from "./commands/ListTagsForResourceCommand";
 import { StartCanaryCommandInput, StartCanaryCommandOutput } from "./commands/StartCanaryCommand";
+import { StartCanaryDryRunCommandInput, StartCanaryDryRunCommandOutput } from "./commands/StartCanaryDryRunCommand";
 import { StopCanaryCommandInput, StopCanaryCommandOutput } from "./commands/StopCanaryCommand";
 import { TagResourceCommandInput, TagResourceCommandOutput } from "./commands/TagResourceCommand";
 import { UntagResourceCommandInput, UntagResourceCommandOutput } from "./commands/UntagResourceCommand";
@@ -121,6 +122,7 @@ export type ServiceInputTypes =
   | ListGroupsCommandInput
   | ListTagsForResourceCommandInput
   | StartCanaryCommandInput
+  | StartCanaryDryRunCommandInput
   | StopCanaryCommandInput
   | TagResourceCommandInput
   | UntagResourceCommandInput
@@ -147,6 +149,7 @@ export type ServiceOutputTypes =
   | ListGroupsCommandOutput
   | ListTagsForResourceCommandOutput
   | StartCanaryCommandOutput
+  | StartCanaryDryRunCommandOutput
   | StopCanaryCommandOutput
   | TagResourceCommandOutput
   | UntagResourceCommandOutput
diff --git a/clients/client-synthetics/src/commands/CreateCanaryCommand.ts b/clients/client-synthetics/src/commands/CreateCanaryCommand.ts
@@ -164,6 +164,10 @@ export interface CreateCanaryCommandOutput extends CreateCanaryResponse, __Metad
  * //         KmsKeyArn: "STRING_VALUE",
  * //       },
  * //     },
+ * //     DryRunConfig: { // DryRunConfigOutput
+ * //       DryRunId: "STRING_VALUE",
+ * //       LastDryRunExecutionStatus: "STRING_VALUE",
+ * //     },
  * //   },
  * // };
  *
diff --git a/clients/client-synthetics/src/commands/DescribeCanariesCommand.ts b/clients/client-synthetics/src/commands/DescribeCanariesCommand.ts
@@ -119,6 +119,10 @@ export interface DescribeCanariesCommandOutput extends DescribeCanariesResponse,
  * //           KmsKeyArn: "STRING_VALUE",
  * //         },
  * //       },
+ * //       DryRunConfig: { // DryRunConfigOutput
+ * //         DryRunId: "STRING_VALUE",
+ * //         LastDryRunExecutionStatus: "STRING_VALUE",
+ * //       },
  * //     },
  * //   ],
  * //   NextToken: "STRING_VALUE",
diff --git a/clients/client-synthetics/src/commands/DescribeCanariesLastRunCommand.ts b/clients/client-synthetics/src/commands/DescribeCanariesLastRunCommand.ts
@@ -69,6 +69,9 @@ export interface DescribeCanariesLastRunCommandOutput extends DescribeCanariesLa
  * //           Completed: new Date("TIMESTAMP"),
  * //         },
  * //         ArtifactS3Location: "STRING_VALUE",
+ * //         DryRunConfig: { // CanaryDryRunConfigOutput
+ * //           DryRunId: "STRING_VALUE",
+ * //         },
  * //       },
  * //     },
  * //   ],
diff --git a/clients/client-synthetics/src/commands/GetCanaryCommand.ts b/clients/client-synthetics/src/commands/GetCanaryCommand.ts
@@ -39,6 +39,7 @@ export interface GetCanaryCommandOutput extends GetCanaryResponse, __MetadataBea
  * const client = new SyntheticsClient(config);
  * const input = { // GetCanaryRequest
  *   Name: "STRING_VALUE", // required
+ *   DryRunId: "STRING_VALUE",
  * };
  * const command = new GetCanaryCommand(input);
  * const response = await client.send(command);
@@ -107,6 +108,10 @@ export interface GetCanaryCommandOutput extends GetCanaryResponse, __MetadataBea
  * //         KmsKeyArn: "STRING_VALUE",
  * //       },
  * //     },
+ * //     DryRunConfig: { // DryRunConfigOutput
+ * //       DryRunId: "STRING_VALUE",
+ * //       LastDryRunExecutionStatus: "STRING_VALUE",
+ * //     },
  * //   },
  * // };
  *
diff --git a/clients/client-synthetics/src/commands/GetCanaryRunsCommand.ts b/clients/client-synthetics/src/commands/GetCanaryRunsCommand.ts
@@ -39,6 +39,8 @@ export interface GetCanaryRunsCommandOutput extends GetCanaryRunsResponse, __Met
  *   Name: "STRING_VALUE", // required
  *   NextToken: "STRING_VALUE",
  *   MaxResults: Number("int"),
+ *   DryRunId: "STRING_VALUE",
+ *   RunType: "CANARY_RUN" || "DRY_RUN",
  * };
  * const command = new GetCanaryRunsCommand(input);
  * const response = await client.send(command);
@@ -57,6 +59,9 @@ export interface GetCanaryRunsCommandOutput extends GetCanaryRunsResponse, __Met
  * //         Completed: new Date("TIMESTAMP"),
  * //       },
  * //       ArtifactS3Location: "STRING_VALUE",
+ * //       DryRunConfig: { // CanaryDryRunConfigOutput
+ * //         DryRunId: "STRING_VALUE",
+ * //       },
  * //     },
  * //   ],
  * //   NextToken: "STRING_VALUE",
diff --git a/clients/client-synthetics/src/commands/StartCanaryDryRunCommand.ts b/clients/client-synthetics/src/commands/StartCanaryDryRunCommand.ts
@@ -0,0 +1,158 @@
+// 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 { StartCanaryDryRunRequest, StartCanaryDryRunResponse } from "../models/models_0";
+import { de_StartCanaryDryRunCommand, se_StartCanaryDryRunCommand } from "../protocols/Aws_restJson1";
+import { ServiceInputTypes, ServiceOutputTypes, SyntheticsClientResolvedConfig } from "../SyntheticsClient";
+
+/**
+ * @public
+ */
+export type { __MetadataBearer };
+export { $Command };
+/**
+ * @public
+ *
+ * The input for {@link StartCanaryDryRunCommand}.
+ */
+export interface StartCanaryDryRunCommandInput extends StartCanaryDryRunRequest {}
+/**
+ * @public
+ *
+ * The output of {@link StartCanaryDryRunCommand}.
+ */
+export interface StartCanaryDryRunCommandOutput extends StartCanaryDryRunResponse, __MetadataBearer {}
+
+/**
+ * <p>Use this operation to start a dry run for a canary that has already been created</p>
+ * @example
+ * Use a bare-bones client and the command you need to make an API call.
+ * ```javascript
+ * import { SyntheticsClient, StartCanaryDryRunCommand } from "@aws-sdk/client-synthetics"; // ES Modules import
+ * // const { SyntheticsClient, StartCanaryDryRunCommand } = require("@aws-sdk/client-synthetics"); // CommonJS import
+ * const client = new SyntheticsClient(config);
+ * const input = { // StartCanaryDryRunRequest
+ *   Name: "STRING_VALUE", // required
+ *   Code: { // CanaryCodeInput
+ *     S3Bucket: "STRING_VALUE",
+ *     S3Key: "STRING_VALUE",
+ *     S3Version: "STRING_VALUE",
+ *     ZipFile: new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")
+ *     Handler: "STRING_VALUE", // required
+ *   },
+ *   RuntimeVersion: "STRING_VALUE",
+ *   RunConfig: { // CanaryRunConfigInput
+ *     TimeoutInSeconds: Number("int"),
+ *     MemoryInMB: Number("int"),
+ *     ActiveTracing: true || false,
+ *     EnvironmentVariables: { // EnvironmentVariablesMap
+ *       "<keys>": "STRING_VALUE",
+ *     },
+ *   },
+ *   VpcConfig: { // VpcConfigInput
+ *     SubnetIds: [ // SubnetIds
+ *       "STRING_VALUE",
+ *     ],
+ *     SecurityGroupIds: [ // SecurityGroupIds
+ *       "STRING_VALUE",
+ *     ],
+ *     Ipv6AllowedForDualStack: true || false,
+ *   },
+ *   ExecutionRoleArn: "STRING_VALUE",
+ *   SuccessRetentionPeriodInDays: Number("int"),
+ *   FailureRetentionPeriodInDays: Number("int"),
+ *   VisualReference: { // VisualReferenceInput
+ *     BaseScreenshots: [ // BaseScreenshots
+ *       { // BaseScreenshot
+ *         ScreenshotName: "STRING_VALUE", // required
+ *         IgnoreCoordinates: [ // BaseScreenshotIgnoreCoordinates
+ *           "STRING_VALUE",
+ *         ],
+ *       },
+ *     ],
+ *     BaseCanaryRunId: "STRING_VALUE", // required
+ *   },
+ *   ArtifactS3Location: "STRING_VALUE",
+ *   ArtifactConfig: { // ArtifactConfigInput
+ *     S3Encryption: { // S3EncryptionConfig
+ *       EncryptionMode: "SSE_S3" || "SSE_KMS",
+ *       KmsKeyArn: "STRING_VALUE",
+ *     },
+ *   },
+ *   ProvisionedResourceCleanup: "AUTOMATIC" || "OFF",
+ * };
+ * const command = new StartCanaryDryRunCommand(input);
+ * const response = await client.send(command);
+ * // { // StartCanaryDryRunResponse
+ * //   DryRunConfig: { // DryRunConfigOutput
+ * //     DryRunId: "STRING_VALUE",
+ * //     LastDryRunExecutionStatus: "STRING_VALUE",
+ * //   },
+ * // };
+ *
+ * ```
+ *
+ * @param StartCanaryDryRunCommandInput - {@link StartCanaryDryRunCommandInput}
+ * @returns {@link StartCanaryDryRunCommandOutput}
+ * @see {@link StartCanaryDryRunCommandInput} for command's `input` shape.
+ * @see {@link StartCanaryDryRunCommandOutput} for command's `response` shape.
+ * @see {@link SyntheticsClientResolvedConfig | config} for SyntheticsClient's `config` shape.
+ *
+ * @throws {@link AccessDeniedException} (client fault)
+ *  <p>You don't have permission to perform this operation on this resource.</p>
+ *
+ * @throws {@link ConflictException} (client fault)
+ *  <p>A conflicting operation is already in progress.</p>
+ *
+ * @throws {@link InternalServerException} (server fault)
+ *  <p>An unknown internal error occurred.</p>
+ *
+ * @throws {@link ResourceNotFoundException} (client fault)
+ *  <p>One of the specified resources was not found.</p>
+ *
+ * @throws {@link ValidationException} (client fault)
+ *  <p>A parameter could not be validated.</p>
+ *
+ * @throws {@link SyntheticsServiceException}
+ * <p>Base exception class for all service exceptions from Synthetics service.</p>
+ *
+ *
+ * @public
+ */
+export class StartCanaryDryRunCommand extends $Command
+  .classBuilder<
+    StartCanaryDryRunCommandInput,
+    StartCanaryDryRunCommandOutput,
+    SyntheticsClientResolvedConfig,
+    ServiceInputTypes,
+    ServiceOutputTypes
+  >()
+  .ep(commonParams)
+  .m(function (this: any, Command: any, cs: any, config: SyntheticsClientResolvedConfig, o: any) {
+    return [
+      getSerdePlugin(config, this.serialize, this.deserialize),
+      getEndpointPlugin(config, Command.getEndpointParameterInstructions()),
+    ];
+  })
+  .s("Synthetics", "StartCanaryDryRun", {})
+  .n("SyntheticsClient", "StartCanaryDryRunCommand")
+  .f(void 0, void 0)
+  .ser(se_StartCanaryDryRunCommand)
+  .de(de_StartCanaryDryRunCommand)
+  .build() {
+  /** @internal type navigation helper, not in runtime. */
+  protected declare static __types: {
+    api: {
+      input: StartCanaryDryRunRequest;
+      output: StartCanaryDryRunResponse;
+    };
+    sdk: {
+      input: StartCanaryDryRunCommandInput;
+      output: StartCanaryDryRunCommandOutput;
+    };
+  };
+}
diff --git a/clients/client-synthetics/src/commands/UpdateCanaryCommand.ts b/clients/client-synthetics/src/commands/UpdateCanaryCommand.ts
@@ -33,6 +33,9 @@ export interface UpdateCanaryCommandOutput extends UpdateCanaryResponse, __Metad
  *          <p>You can't use this operation to update the tags of an existing canary. To
  *          change the tags of an existing canary, use
  *          <a href="https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_TagResource.html">TagResource</a>.</p>
+ *          <note>
+ *             <p>When you use the <code>dryRunId</code> field when updating a canary, the only other field you can provide is the <code>Schedule</code>. Adding any other field will thrown an exception.</p>
+ *          </note>
  * @example
  * Use a bare-bones client and the command you need to make an API call.
  * ```javascript
@@ -92,6 +95,7 @@ export interface UpdateCanaryCommandOutput extends UpdateCanaryResponse, __Metad
  *     },
  *   },
  *   ProvisionedResourceCleanup: "AUTOMATIC" || "OFF",
+ *   DryRunId: "STRING_VALUE",
  * };
  * const command = new UpdateCanaryCommand(input);
  * const response = await client.send(command);
@@ -105,6 +109,9 @@ export interface UpdateCanaryCommandOutput extends UpdateCanaryResponse, __Metad
  * @see {@link UpdateCanaryCommandOutput} for command's `response` shape.
  * @see {@link SyntheticsClientResolvedConfig | config} for SyntheticsClient's `config` shape.
  *
+ * @throws {@link AccessDeniedException} (client fault)
+ *  <p>You don't have permission to perform this operation on this resource.</p>
+ *
  * @throws {@link ConflictException} (client fault)
  *  <p>A conflicting operation is already in progress.</p>
  *
diff --git a/clients/client-synthetics/src/commands/index.ts b/clients/client-synthetics/src/commands/index.ts
@@ -16,6 +16,7 @@ export * from "./ListGroupResourcesCommand";
 export * from "./ListGroupsCommand";
 export * from "./ListTagsForResourceCommand";
 export * from "./StartCanaryCommand";
+export * from "./StartCanaryDryRunCommand";
 export * from "./StopCanaryCommand";
 export * from "./TagResourceCommand";
 export * from "./UntagResourceCommand";
diff --git a/clients/client-synthetics/src/models/models_0.ts b/clients/client-synthetics/src/models/models_0.ts
diff --git a/clients/client-synthetics/src/protocols/Aws_restJson1.ts b/clients/client-synthetics/src/protocols/Aws_restJson1.ts
diff --git a/codegen/sdk-codegen/aws-models/synthetics.json b/codegen/sdk-codegen/aws-models/synthetics.json
