CreateGroupCommand

Suggest an Edit

Creates a group which you can use to associate canaries with each other, including cross-Region canaries. Using groups can help you with managing and automating your canaries, and you can also view aggregated run results and statistics for all canaries in a group.

Groups are global resources. When you create a group, it is replicated across Amazon Web Services Regions, and you can view it and add canaries to it from any Region. Although the group ARN format reflects the Region name where it was created, a group is not constrained to any Region. This means that you can put canaries from multiple Regions into the same group, and then use that group to view and manage all of those canaries in a single view.

Groups are supported in all Regions except the Regions that are disabled by default. For more information about these Regions, see Enabling a Region .

Each group can contain as many as 10 canaries. You can have as many as 20 groups in your account. Any single canary can be a member of up to 10 groups.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { SyntheticsClient, CreateGroupCommand } from "@aws-sdk/client-synthetics"; // ES Modules import
// const { SyntheticsClient, CreateGroupCommand } = require("@aws-sdk/client-synthetics"); // CommonJS import
const client = new SyntheticsClient(config);
const input = { // CreateGroupRequest
  Name: "STRING_VALUE", // required
  Tags: { // TagMap
    "<keys>": "STRING_VALUE",
  },
};
const command = new CreateGroupCommand(input);
const response = await client.send(command);
// { // CreateGroupResponse
//   Group: { // Group
//     Id: "STRING_VALUE",
//     Name: "STRING_VALUE",
//     Arn: "STRING_VALUE",
//     Tags: { // TagMap
//       "<keys>": "STRING_VALUE",
//     },
//     CreatedTime: new Date("TIMESTAMP"),
//     LastModifiedTime: new Date("TIMESTAMP"),
//   },
// };

CreateGroupCommand Input

See CreateGroupCommandInput for more details

Parameter
Type
Description
Name
Required
string | undefined

The name for the group. It can include any Unicode characters.

The names for all groups in your account, across all Regions, must be unique.

Tags
Record<string, string> | undefined

A list of key-value pairs to associate with the group. You can associate as many as 50 tags with a group.

Tags can help you organize and categorize your resources. You can also use them to scope user permissions, by granting a user permission to access or change only the resources that have certain tag values.

CreateGroupCommand Output

See CreateGroupCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
Group
Group | undefined

A structure that contains information about the group that was just created.

Throws

Name
Fault
Details
ConflictException
client

A conflicting operation is already in progress.

InternalServerException
server

An unknown internal error occurred.

ServiceQuotaExceededException
client

The request exceeded a service quota value.

ValidationException
client

A parameter could not be validated.

SyntheticsServiceException
Base exception class for all service exceptions from Synthetics service.