SDK for PHP 3.x

AWS Resource Groups 2017-11-27

Client: Aws\ResourceGroups\ResourceGroupsClient
Service ID: resource-groups
Version: 2017-11-27

This page describes the parameters and results for the operations of the AWS Resource Groups (2017-11-27), and shows how to use the Aws\ResourceGroups\ResourceGroupsClient object to call the described operations. This documentation is specific to the 2017-11-27 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

CancelTagSyncTask ( array $params = [] )
Cancels the specified tag-sync task.
CreateGroup ( array $params = [] )
Creates a resource group with the specified name and description.
DeleteGroup ( array $params = [] )
Deletes the specified resource group.
GetAccountSettings ( array $params = [] )
Retrieves the current status of optional features in Resource Groups.
GetGroup ( array $params = [] )
Returns information about a specified resource group.
GetGroupConfiguration ( array $params = [] )
Retrieves the service configuration associated with the specified resource group.
GetGroupQuery ( array $params = [] )
Retrieves the resource query associated with the specified resource group.
GetTagSyncTask ( array $params = [] )
Returns information about a specified tag-sync task.
GetTags ( array $params = [] )
Returns a list of tags that are associated with a resource group, specified by an Amazon resource name (ARN).
GroupResources ( array $params = [] )
Adds the specified resources to the specified group.
ListGroupResources ( array $params = [] )
Returns a list of Amazon resource names (ARNs) of the resources that are members of a specified resource group.
ListGroupingStatuses ( array $params = [] )
Returns the status of the last grouping or ungrouping action for each resource in the specified application group.
ListGroups ( array $params = [] )
Returns a list of existing Resource Groups in your account.
ListTagSyncTasks ( array $params = [] )
Returns a list of tag-sync tasks.
PutGroupConfiguration ( array $params = [] )
Attaches a service configuration to the specified group.
SearchResources ( array $params = [] )
Returns a list of Amazon Web Services resource identifiers that matches the specified query.
StartTagSyncTask ( array $params = [] )
Creates a new tag-sync task to onboard and sync resources tagged with a specific tag key-value pair to an application.
Tag ( array $params = [] )
Adds tags to a resource group with the specified Amazon resource name (ARN).
UngroupResources ( array $params = [] )
Removes the specified resources from the specified group.
Untag ( array $params = [] )
Deletes tags from a specified resource group.
UpdateAccountSettings ( array $params = [] )
Turns on or turns off optional features in Resource Groups.
UpdateGroup ( array $params = [] )
Updates the description for an existing group.
UpdateGroupQuery ( array $params = [] )
Updates the resource query of a group.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

ListGroupResources
ListGroupingStatuses
ListGroups
ListTagSyncTasks
SearchResources

Operations

CancelTagSyncTask 

$result = $client->cancelTagSyncTask([/* ... */]);
$promise = $client->cancelTagSyncTaskAsync([/* ... */]);

Cancels the specified tag-sync task.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:CancelTagSyncTask on the application group

  • resource-groups:DeleteGroup

Parameter Syntax

$result = $client->cancelTagSyncTask([
    'TaskArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
TaskArn
Required: Yes
Type: string

The Amazon resource name (ARN) of the tag-sync task.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

UnauthorizedException:

The request was rejected because it doesn't have valid credentials for the target resource.

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

CreateGroup 

$result = $client->createGroup([/* ... */]);
$promise = $client->createGroupAsync([/* ... */]);

Creates a resource group with the specified name and description. You can optionally include either a resource query or a service configuration. For more information about constructing a resource query, see Build queries and groups in Resource Groups in the Resource Groups User Guide. For more information about service-linked groups and service configurations, see Service configurations for Resource Groups.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:CreateGroup

Parameter Syntax

$result = $client->createGroup([
    'Configuration' => [
        [
            'Parameters' => [
                [
                    'Name' => '<string>', // REQUIRED
                    'Values' => ['<string>', ...],
                ],
                // ...
            ],
            'Type' => '<string>', // REQUIRED
        ],
        // ...
    ],
    'Criticality' => <integer>,
    'Description' => '<string>',
    'DisplayName' => '<string>',
    'Name' => '<string>', // REQUIRED
    'Owner' => '<string>',
    'ResourceQuery' => [
        'Query' => '<string>', // REQUIRED
        'Type' => 'TAG_FILTERS_1_0|CLOUDFORMATION_STACK_1_0', // REQUIRED
    ],
    'Tags' => ['<string>', ...],
]);

Parameter Details

Members
Configuration
Type: Array of GroupConfigurationItem structures

A configuration associates the resource group with an Amazon Web Services service and specifies how the service can interact with the resources in the group. A configuration is an array of GroupConfigurationItem elements. For details about the syntax of service configurations, see Service configurations for Resource Groups.

A resource group can contain either a Configuration or a ResourceQuery, but not both.

Criticality
Type: int

The critical rank of the application group on a scale of 1 to 10, with a rank of 1 being the most critical, and a rank of 10 being least critical.

Description
Type: string

The description of the resource group. Descriptions can consist of letters, numbers, hyphens, underscores, periods, and spaces.

DisplayName
Type: string

The name of the application group, which you can change at any time.

Name
Required: Yes
Type: string

The name of the group, which is the identifier of the group in other operations. You can't change the name of a resource group after you create it. A resource group name can consist of letters, numbers, hyphens, periods, and underscores. The name cannot start with AWS, aws, or any other possible capitalization; these are reserved. A resource group name must be unique within each Amazon Web Services Region in your Amazon Web Services account.

Owner
Type: string

A name, email address or other identifier for the person or group who is considered as the owner of this application group within your organization.

ResourceQuery
Type: ResourceQuery structure

The resource query that determines which Amazon Web Services resources are members of this group. For more information about resource queries, see Create a tag-based group in Resource Groups.

A resource group can contain either a ResourceQuery or a Configuration, but not both.

Tags
Type: Associative array of custom strings keys (TagKey) to strings

The tags to add to the group. A tag is key-value pair string.

Result Syntax

[
    'Group' => [
        'ApplicationTag' => ['<string>', ...],
        'Criticality' => <integer>,
        'Description' => '<string>',
        'DisplayName' => '<string>',
        'GroupArn' => '<string>',
        'Name' => '<string>',
        'Owner' => '<string>',
    ],
    'GroupConfiguration' => [
        'Configuration' => [
            [
                'Parameters' => [
                    [
                        'Name' => '<string>',
                        'Values' => ['<string>', ...],
                    ],
                    // ...
                ],
                'Type' => '<string>',
            ],
            // ...
        ],
        'FailureReason' => '<string>',
        'ProposedConfiguration' => [
            [
                'Parameters' => [
                    [
                        'Name' => '<string>',
                        'Values' => ['<string>', ...],
                    ],
                    // ...
                ],
                'Type' => '<string>',
            ],
            // ...
        ],
        'Status' => 'UPDATING|UPDATE_COMPLETE|UPDATE_FAILED',
    ],
    'ResourceQuery' => [
        'Query' => '<string>',
        'Type' => 'TAG_FILTERS_1_0|CLOUDFORMATION_STACK_1_0',
    ],
    'Tags' => ['<string>', ...],
]

Result Details

Members
Group
Type: Group structure

The description of the resource group.

GroupConfiguration
Type: GroupConfiguration structure

The service configuration associated with the resource group. For details about the syntax of a service configuration, see Service configurations for Resource Groups.

ResourceQuery
Type: ResourceQuery structure

The resource query associated with the group. For more information about resource queries, see Create a tag-based group in Resource Groups.

Tags
Type: Associative array of custom strings keys (TagKey) to strings

The tags associated with the group.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

DeleteGroup 

$result = $client->deleteGroup([/* ... */]);
$promise = $client->deleteGroupAsync([/* ... */]);

Deletes the specified resource group. Deleting a resource group does not delete any resources that are members of the group; it only deletes the group structure.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:DeleteGroup

Parameter Syntax

$result = $client->deleteGroup([
    'Group' => '<string>',
    'GroupName' => '<string>',
]);

Parameter Details

Members
Group
Type: string

The name or the Amazon resource name (ARN) of the resource group to delete.

GroupName
Type: string

Deprecated - don't use this parameter. Use Group instead.

Result Syntax

[
    'Group' => [
        'ApplicationTag' => ['<string>', ...],
        'Criticality' => <integer>,
        'Description' => '<string>',
        'DisplayName' => '<string>',
        'GroupArn' => '<string>',
        'Name' => '<string>',
        'Owner' => '<string>',
    ],
]

Result Details

Members
Group
Type: Group structure

A full description of the deleted resource group.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

GetAccountSettings 

$result = $client->getAccountSettings([/* ... */]);
$promise = $client->getAccountSettingsAsync([/* ... */]);

Retrieves the current status of optional features in Resource Groups.

Parameter Syntax

$result = $client->getAccountSettings([
]);

Parameter Details

Members

Result Syntax

[
    'AccountSettings' => [
        'GroupLifecycleEventsDesiredStatus' => 'ACTIVE|INACTIVE',
        'GroupLifecycleEventsStatus' => 'ACTIVE|INACTIVE|IN_PROGRESS|ERROR',
        'GroupLifecycleEventsStatusMessage' => '<string>',
    ],
]

Result Details

Members
AccountSettings
Type: AccountSettings structure

The current settings for the optional features in Resource Groups.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

GetGroup 

$result = $client->getGroup([/* ... */]);
$promise = $client->getGroupAsync([/* ... */]);

Returns information about a specified resource group.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:GetGroup

Parameter Syntax

$result = $client->getGroup([
    'Group' => '<string>',
    'GroupName' => '<string>',
]);

Parameter Details

Members
Group
Type: string

The name or the Amazon resource name (ARN) of the resource group to retrieve.

GroupName
Type: string

Deprecated - don't use this parameter. Use Group instead.

Result Syntax

[
    'Group' => [
        'ApplicationTag' => ['<string>', ...],
        'Criticality' => <integer>,
        'Description' => '<string>',
        'DisplayName' => '<string>',
        'GroupArn' => '<string>',
        'Name' => '<string>',
        'Owner' => '<string>',
    ],
]

Result Details

Members
Group
Type: Group structure

A structure that contains the metadata details for the specified resource group. Use GetGroupQuery and GetGroupConfiguration to get those additional details of the resource group.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

GetGroupConfiguration 

$result = $client->getGroupConfiguration([/* ... */]);
$promise = $client->getGroupConfigurationAsync([/* ... */]);

Retrieves the service configuration associated with the specified resource group. For details about the service configuration syntax, see Service configurations for Resource Groups.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:GetGroupConfiguration

Parameter Syntax

$result = $client->getGroupConfiguration([
    'Group' => '<string>',
]);

Parameter Details

Members
Group
Type: string

The name or the Amazon resource name (ARN) of the resource group for which you want to retrive the service configuration.

Result Syntax

[
    'GroupConfiguration' => [
        'Configuration' => [
            [
                'Parameters' => [
                    [
                        'Name' => '<string>',
                        'Values' => ['<string>', ...],
                    ],
                    // ...
                ],
                'Type' => '<string>',
            ],
            // ...
        ],
        'FailureReason' => '<string>',
        'ProposedConfiguration' => [
            [
                'Parameters' => [
                    [
                        'Name' => '<string>',
                        'Values' => ['<string>', ...],
                    ],
                    // ...
                ],
                'Type' => '<string>',
            ],
            // ...
        ],
        'Status' => 'UPDATING|UPDATE_COMPLETE|UPDATE_FAILED',
    ],
]

Result Details

Members
GroupConfiguration
Type: GroupConfiguration structure

A structure that describes the service configuration attached with the specified group. For details about the service configuration syntax, see Service configurations for Resource Groups.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

GetGroupQuery 

$result = $client->getGroupQuery([/* ... */]);
$promise = $client->getGroupQueryAsync([/* ... */]);

Retrieves the resource query associated with the specified resource group. For more information about resource queries, see Create a tag-based group in Resource Groups.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:GetGroupQuery

Parameter Syntax

$result = $client->getGroupQuery([
    'Group' => '<string>',
    'GroupName' => '<string>',
]);

Parameter Details

Members
Group
Type: string

The name or the Amazon resource name (ARN) of the resource group to query.

GroupName
Type: string

Don't use this parameter. Use Group instead.

Result Syntax

[
    'GroupQuery' => [
        'GroupName' => '<string>',
        'ResourceQuery' => [
            'Query' => '<string>',
            'Type' => 'TAG_FILTERS_1_0|CLOUDFORMATION_STACK_1_0',
        ],
    ],
]

Result Details

Members
GroupQuery
Type: GroupQuery structure

The resource query associated with the specified group. For more information about resource queries, see Create a tag-based group in Resource Groups.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

GetTagSyncTask 

$result = $client->getTagSyncTask([/* ... */]);
$promise = $client->getTagSyncTaskAsync([/* ... */]);

Returns information about a specified tag-sync task.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:GetTagSyncTask on the application group

Parameter Syntax

$result = $client->getTagSyncTask([
    'TaskArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
TaskArn
Required: Yes
Type: string

The Amazon resource name (ARN) of the tag-sync task.

Result Syntax

[
    'CreatedAt' => <DateTime>,
    'ErrorMessage' => '<string>',
    'GroupArn' => '<string>',
    'GroupName' => '<string>',
    'RoleArn' => '<string>',
    'Status' => 'ACTIVE|ERROR',
    'TagKey' => '<string>',
    'TagValue' => '<string>',
    'TaskArn' => '<string>',
]

Result Details

Members
CreatedAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

The timestamp of when the tag-sync task was created.

ErrorMessage
Type: string

The specific error message in cases where the tag-sync task status is ERROR.

GroupArn
Type: string

The Amazon resource name (ARN) of the application group.

GroupName
Type: string

The name of the application group.

RoleArn
Type: string

The Amazon resource name (ARN) of the role assumed by Resource Groups to tag and untag resources on your behalf.

For more information about this role, review Tag-sync required permissions.

Status
Type: string

The status of the tag-sync task.

Valid values include:

  • ACTIVE - The tag-sync task is actively managing resources in the application by adding or removing the awsApplication tag from resources when they are tagged or untagged with the specified tag key-value pair.

  • ERROR - The tag-sync task is not actively managing resources in the application. Review the ErrorMessage for more information about resolving the error.

TagKey
Type: string

The tag key.

TagValue
Type: string

The tag value.

TaskArn
Type: string

The Amazon resource name (ARN) of the tag-sync task.

Errors

UnauthorizedException:

The request was rejected because it doesn't have valid credentials for the target resource.

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

GetTags 

$result = $client->getTags([/* ... */]);
$promise = $client->getTagsAsync([/* ... */]);

Returns a list of tags that are associated with a resource group, specified by an Amazon resource name (ARN).

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:GetTags

Parameter Syntax

$result = $client->getTags([
    'Arn' => '<string>', // REQUIRED
]);

Parameter Details

Members
Arn
Required: Yes
Type: string

The Amazon resource name (ARN) of the resource group whose tags you want to retrieve.

Result Syntax

[
    'Arn' => '<string>',
    'Tags' => ['<string>', ...],
]

Result Details

Members
Arn
Type: string

TheAmazon resource name (ARN) of the tagged resource group.

Tags
Type: Associative array of custom strings keys (TagKey) to strings

The tags associated with the specified resource group.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

GroupResources 

$result = $client->groupResources([/* ... */]);
$promise = $client->groupResourcesAsync([/* ... */]);

Adds the specified resources to the specified group.

You can only use this operation with the following groups:

  • AWS::EC2::HostManagement

  • AWS::EC2::CapacityReservationPool

  • AWS::ResourceGroups::ApplicationGroup

Other resource group types and resource types are not currently supported by this operation.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:GroupResources

Parameter Syntax

$result = $client->groupResources([
    'Group' => '<string>', // REQUIRED
    'ResourceArns' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members
Group
Required: Yes
Type: string

The name or the Amazon resource name (ARN) of the resource group to add resources to.

ResourceArns
Required: Yes
Type: Array of strings

The list of Amazon resource names (ARNs) of the resources to be added to the group.

Result Syntax

[
    'Failed' => [
        [
            'ErrorCode' => '<string>',
            'ErrorMessage' => '<string>',
            'ResourceArn' => '<string>',
        ],
        // ...
    ],
    'Pending' => [
        [
            'ResourceArn' => '<string>',
        ],
        // ...
    ],
    'Succeeded' => ['<string>', ...],
]

Result Details

Members
Failed
Type: Array of FailedResource structures

A list of Amazon resource names (ARNs) of any resources that this operation failed to add to the group.

Pending
Type: Array of PendingResource structures

A list of Amazon resource names (ARNs) of any resources that this operation is still in the process adding to the group. These pending additions continue asynchronously. You can check the status of pending additions by using the ListGroupResources operation, and checking the Resources array in the response and the Status field of each object in that array.

Succeeded
Type: Array of strings

A list of Amazon resource names (ARNs) of the resources that this operation successfully added to the group.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

ListGroupResources 

$result = $client->listGroupResources([/* ... */]);
$promise = $client->listGroupResourcesAsync([/* ... */]);

Returns a list of Amazon resource names (ARNs) of the resources that are members of a specified resource group.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:ListGroupResources

  • cloudformation:DescribeStacks

  • cloudformation:ListStackResources

  • tag:GetResources

Parameter Syntax

$result = $client->listGroupResources([
    'Filters' => [
        [
            'Name' => 'resource-type', // REQUIRED
            'Values' => ['<string>', ...], // REQUIRED
        ],
        // ...
    ],
    'Group' => '<string>',
    'GroupName' => '<string>',
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members
Filters
Type: Array of ResourceFilter structures

Filters, formatted as ResourceFilter objects, that you want to apply to a ListGroupResources operation. Filters the results to include only those of the specified resource types.

  • resource-type - Filter resources by their type. Specify up to five resource types in the format AWS::ServiceCode::ResourceType. For example, AWS::EC2::Instance, or AWS::S3::Bucket.

When you specify a resource-type filter for ListGroupResources, Resource Groups validates your filter resource types against the types that are defined in the query associated with the group. For example, if a group contains only S3 buckets because its query specifies only that resource type, but your resource-type filter includes EC2 instances, AWS Resource Groups does not filter for EC2 instances. In this case, a ListGroupResources request returns a BadRequestException error with a message similar to the following:

The resource types specified as filters in the request are not valid.

The error includes a list of resource types that failed the validation because they are not part of the query associated with the group. This validation doesn't occur when the group query specifies AWS::AllSupported, because a group based on such a query can contain any of the allowed resource types for the query type (tag-based or Amazon CloudFront stack-based queries).

Group
Type: string

The name or the Amazon resource name (ARN) of the resource group.

GroupName
Type: string

Deprecated - don't use this parameter. Use the Group request field instead.

MaxResults
Type: int

The total number of results that you want included on each page of the response. If you do not include this parameter, it defaults to a value that is specific to the operation. If additional items exist beyond the maximum you specify, the NextToken response element is present and has a value (is not null). Include that value as the NextToken request parameter in the next call to the operation to get the next part of the results. Note that the service might return fewer results than the maximum even when there are more results available. You should check NextToken after every operation to ensure that you receive all of the results.

NextToken
Type: string

The parameter for receiving additional results if you receive a NextToken response in a previous request. A NextToken response indicates that more output is available. Set this parameter to the value provided by a previous call's NextToken response to indicate where the output should continue from.

Result Syntax

[
    'NextToken' => '<string>',
    'QueryErrors' => [
        [
            'ErrorCode' => 'CLOUDFORMATION_STACK_INACTIVE|CLOUDFORMATION_STACK_NOT_EXISTING|CLOUDFORMATION_STACK_UNASSUMABLE_ROLE|RESOURCE_TYPE_NOT_SUPPORTED',
            'Message' => '<string>',
        ],
        // ...
    ],
    'ResourceIdentifiers' => [
        [
            'ResourceArn' => '<string>',
            'ResourceType' => '<string>',
        ],
        // ...
    ],
    'Resources' => [
        [
            'Identifier' => [
                'ResourceArn' => '<string>',
                'ResourceType' => '<string>',
            ],
            'Status' => [
                'Name' => 'PENDING',
            ],
        ],
        // ...
    ],
]

Result Details

Members
NextToken
Type: string

If present, indicates that more output is available than is included in the current response. Use this value in the NextToken request parameter in a subsequent call to the operation to get the next part of the output. You should repeat this until the NextToken response element comes back as null.

QueryErrors
Type: Array of QueryError structures

A list of QueryError objects. Each error contains an ErrorCode and Message. Possible values for ErrorCode are CLOUDFORMATION_STACK_INACTIVE, CLOUDFORMATION_STACK_NOT_EXISTING, CLOUDFORMATION_STACK_UNASSUMABLE_ROLE and RESOURCE_TYPE_NOT_SUPPORTED.

ResourceIdentifiers
Type: Array of ResourceIdentifier structures

Deprecated - don't use this parameter. Use the Resources response field instead.

Resources
Type: Array of ListGroupResourcesItem structures

An array of resources from which you can determine each resource's identity, type, and group membership status.

Errors

UnauthorizedException:

The request was rejected because it doesn't have valid credentials for the target resource.

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

ListGroupingStatuses 

$result = $client->listGroupingStatuses([/* ... */]);
$promise = $client->listGroupingStatusesAsync([/* ... */]);

Returns the status of the last grouping or ungrouping action for each resource in the specified application group.

Parameter Syntax

$result = $client->listGroupingStatuses([
    'Filters' => [
        [
            'Name' => 'status|resource-arn', // REQUIRED
            'Values' => ['<string>', ...], // REQUIRED
        ],
        // ...
    ],
    'Group' => '<string>', // REQUIRED
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members
Filters
Type: Array of ListGroupingStatusesFilter structures

The filter name and value pair that is used to return more specific results from a list of resources.

Group
Required: Yes
Type: string

The application group identifier, expressed as an Amazon resource name (ARN) or the application group name.

MaxResults
Type: int

The maximum number of resources and their statuses returned in the response.

NextToken
Type: string

The parameter for receiving additional results if you receive a NextToken response in a previous request. A NextToken response indicates that more output is available. Set this parameter to the value provided by a previous call's NextToken response to indicate where the output should continue from.

Result Syntax

[
    'Group' => '<string>',
    'GroupingStatuses' => [
        [
            'Action' => 'GROUP|UNGROUP',
            'ErrorCode' => '<string>',
            'ErrorMessage' => '<string>',
            'ResourceArn' => '<string>',
            'Status' => 'SUCCESS|FAILED|IN_PROGRESS|SKIPPED',
            'UpdatedAt' => <DateTime>,
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Members
Group
Type: string

The application group identifier, expressed as an Amazon resource name (ARN) or the application group name.

GroupingStatuses
Type: Array of GroupingStatusesItem structures

Returns details about the grouping or ungrouping status of the resources in the specified application group.

NextToken
Type: string

If present, indicates that more output is available than is included in the current response. Use this value in the NextToken request parameter in a subsequent call to the operation to get the next part of the output. You should repeat this until the NextToken response element comes back as null.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

ListGroups 

$result = $client->listGroups([/* ... */]);
$promise = $client->listGroupsAsync([/* ... */]);

Returns a list of existing Resource Groups in your account.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:ListGroups

Parameter Syntax

$result = $client->listGroups([
    'Filters' => [
        [
            'Name' => 'resource-type|configuration-type|owner|display-name|criticality', // REQUIRED
            'Values' => ['<string>', ...], // REQUIRED
        ],
        // ...
    ],
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members
Filters
Type: Array of GroupFilter structures

Filters, formatted as GroupFilter objects, that you want to apply to a ListGroups operation.

  • resource-type - Filter the results to include only those resource groups that have the specified resource type in their ResourceTypeFilter. For example, AWS::EC2::Instance would return any resource group with a ResourceTypeFilter that includes AWS::EC2::Instance.

  • configuration-type - Filter the results to include only those groups that have the specified configuration types attached. The current supported values are:

    • AWS::ResourceGroups::ApplicationGroup

    • AWS::AppRegistry::Application

    • AWS::AppRegistry::ApplicationResourceGroups

    • AWS::CloudFormation::Stack

    • AWS::EC2::CapacityReservationPool

    • AWS::EC2::HostManagement

    • AWS::NetworkFirewall::RuleGroup

MaxResults
Type: int

The total number of results that you want included on each page of the response. If you do not include this parameter, it defaults to a value that is specific to the operation. If additional items exist beyond the maximum you specify, the NextToken response element is present and has a value (is not null). Include that value as the NextToken request parameter in the next call to the operation to get the next part of the results. Note that the service might return fewer results than the maximum even when there are more results available. You should check NextToken after every operation to ensure that you receive all of the results.

NextToken
Type: string

The parameter for receiving additional results if you receive a NextToken response in a previous request. A NextToken response indicates that more output is available. Set this parameter to the value provided by a previous call's NextToken response to indicate where the output should continue from.

Result Syntax

[
    'GroupIdentifiers' => [
        [
            'Criticality' => <integer>,
            'Description' => '<string>',
            'DisplayName' => '<string>',
            'GroupArn' => '<string>',
            'GroupName' => '<string>',
            'Owner' => '<string>',
        ],
        // ...
    ],
    'Groups' => [
        [
            'ApplicationTag' => ['<string>', ...],
            'Criticality' => <integer>,
            'Description' => '<string>',
            'DisplayName' => '<string>',
            'GroupArn' => '<string>',
            'Name' => '<string>',
            'Owner' => '<string>',
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Members
GroupIdentifiers
Type: Array of GroupIdentifier structures

A list of GroupIdentifier objects. Each identifier is an object that contains both the Name and the GroupArn.

Groups
Type: Array of Group structures

Deprecated - don't use this field. Use the GroupIdentifiers response field instead.

NextToken
Type: string

If present, indicates that more output is available than is included in the current response. Use this value in the NextToken request parameter in a subsequent call to the operation to get the next part of the output. You should repeat this until the NextToken response element comes back as null.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

ListTagSyncTasks 

$result = $client->listTagSyncTasks([/* ... */]);
$promise = $client->listTagSyncTasksAsync([/* ... */]);

Returns a list of tag-sync tasks.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:ListTagSyncTasks with the group passed in the filters as the resource or * if using no filters

Parameter Syntax

$result = $client->listTagSyncTasks([
    'Filters' => [
        [
            'GroupArn' => '<string>',
            'GroupName' => '<string>',
        ],
        // ...
    ],
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members
Filters
Type: Array of ListTagSyncTasksFilter structures

The Amazon resource name (ARN) or name of the application group for which you want to return a list of tag-sync tasks.

MaxResults
Type: int

The maximum number of results to be included in the response.

NextToken
Type: string

The parameter for receiving additional results if you receive a NextToken response in a previous request. A NextToken response indicates that more output is available. Set this parameter to the value provided by a previous call's NextToken response to indicate where the output should continue from.

Result Syntax

[
    'NextToken' => '<string>',
    'TagSyncTasks' => [
        [
            'CreatedAt' => <DateTime>,
            'ErrorMessage' => '<string>',
            'GroupArn' => '<string>',
            'GroupName' => '<string>',
            'RoleArn' => '<string>',
            'Status' => 'ACTIVE|ERROR',
            'TagKey' => '<string>',
            'TagValue' => '<string>',
            'TaskArn' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
NextToken
Type: string

If present, indicates that more output is available than is included in the current response. Use this value in the NextToken request parameter in a subsequent call to the operation to get the next part of the output. You should repeat this until the NextToken response element comes back as null.

TagSyncTasks
Type: Array of TagSyncTaskItem structures

A list of tag-sync tasks and information about each task.

Errors

UnauthorizedException:

The request was rejected because it doesn't have valid credentials for the target resource.

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

PutGroupConfiguration 

$result = $client->putGroupConfiguration([/* ... */]);
$promise = $client->putGroupConfigurationAsync([/* ... */]);

Attaches a service configuration to the specified group. This occurs asynchronously, and can take time to complete. You can use GetGroupConfiguration to check the status of the update.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:PutGroupConfiguration

Parameter Syntax

$result = $client->putGroupConfiguration([
    'Configuration' => [
        [
            'Parameters' => [
                [
                    'Name' => '<string>', // REQUIRED
                    'Values' => ['<string>', ...],
                ],
                // ...
            ],
            'Type' => '<string>', // REQUIRED
        ],
        // ...
    ],
    'Group' => '<string>',
]);

Parameter Details

Members
Configuration
Type: Array of GroupConfigurationItem structures

The new configuration to associate with the specified group. A configuration associates the resource group with an Amazon Web Services service and specifies how the service can interact with the resources in the group. A configuration is an array of GroupConfigurationItem elements.

For information about the syntax of a service configuration, see Service configurations for Resource Groups.

A resource group can contain either a Configuration or a ResourceQuery, but not both.

Group
Type: string

The name or Amazon resource name (ARN) of the resource group with the configuration that you want to update.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

SearchResources 

$result = $client->searchResources([/* ... */]);
$promise = $client->searchResourcesAsync([/* ... */]);

Returns a list of Amazon Web Services resource identifiers that matches the specified query. The query uses the same format as a resource query in a CreateGroup or UpdateGroupQuery operation.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:SearchResources

  • cloudformation:DescribeStacks

  • cloudformation:ListStackResources

  • tag:GetResources

Parameter Syntax

$result = $client->searchResources([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'ResourceQuery' => [ // REQUIRED
        'Query' => '<string>', // REQUIRED
        'Type' => 'TAG_FILTERS_1_0|CLOUDFORMATION_STACK_1_0', // REQUIRED
    ],
]);

Parameter Details

Members
MaxResults
Type: int

The total number of results that you want included on each page of the response. If you do not include this parameter, it defaults to a value that is specific to the operation. If additional items exist beyond the maximum you specify, the NextToken response element is present and has a value (is not null). Include that value as the NextToken request parameter in the next call to the operation to get the next part of the results. Note that the service might return fewer results than the maximum even when there are more results available. You should check NextToken after every operation to ensure that you receive all of the results.

NextToken
Type: string

The parameter for receiving additional results if you receive a NextToken response in a previous request. A NextToken response indicates that more output is available. Set this parameter to the value provided by a previous call's NextToken response to indicate where the output should continue from.

ResourceQuery
Required: Yes
Type: ResourceQuery structure

The search query, using the same formats that are supported for resource group definition. For more information, see CreateGroup.

Result Syntax

[
    'NextToken' => '<string>',
    'QueryErrors' => [
        [
            'ErrorCode' => 'CLOUDFORMATION_STACK_INACTIVE|CLOUDFORMATION_STACK_NOT_EXISTING|CLOUDFORMATION_STACK_UNASSUMABLE_ROLE|RESOURCE_TYPE_NOT_SUPPORTED',
            'Message' => '<string>',
        ],
        // ...
    ],
    'ResourceIdentifiers' => [
        [
            'ResourceArn' => '<string>',
            'ResourceType' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
NextToken
Type: string

If present, indicates that more output is available than is included in the current response. Use this value in the NextToken request parameter in a subsequent call to the operation to get the next part of the output. You should repeat this until the NextToken response element comes back as null.

QueryErrors
Type: Array of QueryError structures

A list of QueryError objects. Each error contains an ErrorCode and Message.

Possible values for ErrorCode:

  • CLOUDFORMATION_STACK_INACTIVE

  • CLOUDFORMATION_STACK_NOT_EXISTING

  • CLOUDFORMATION_STACK_UNASSUMABLE_ROLE

ResourceIdentifiers
Type: Array of ResourceIdentifier structures

The ARNs and resource types of resources that are members of the group that you specified.

Errors

UnauthorizedException:

The request was rejected because it doesn't have valid credentials for the target resource.

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

StartTagSyncTask 

$result = $client->startTagSyncTask([/* ... */]);
$promise = $client->startTagSyncTaskAsync([/* ... */]);

Creates a new tag-sync task to onboard and sync resources tagged with a specific tag key-value pair to an application.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:StartTagSyncTask on the application group

  • resource-groups:CreateGroup

  • iam:PassRole on the role provided in the request

Parameter Syntax

$result = $client->startTagSyncTask([
    'Group' => '<string>', // REQUIRED
    'RoleArn' => '<string>', // REQUIRED
    'TagKey' => '<string>', // REQUIRED
    'TagValue' => '<string>', // REQUIRED
]);

Parameter Details

Members
Group
Required: Yes
Type: string

The Amazon resource name (ARN) or name of the application group for which you want to create a tag-sync task.

RoleArn
Required: Yes
Type: string

The Amazon resource name (ARN) of the role assumed by the service to tag and untag resources on your behalf.

TagKey
Required: Yes
Type: string

The tag key. Resources tagged with this tag key-value pair will be added to the application. If a resource with this tag is later untagged, the tag-sync task removes the resource from the application.

TagValue
Required: Yes
Type: string

The tag value. Resources tagged with this tag key-value pair will be added to the application. If a resource with this tag is later untagged, the tag-sync task removes the resource from the application.

Result Syntax

[
    'GroupArn' => '<string>',
    'GroupName' => '<string>',
    'RoleArn' => '<string>',
    'TagKey' => '<string>',
    'TagValue' => '<string>',
    'TaskArn' => '<string>',
]

Result Details

Members
GroupArn
Type: string

The Amazon resource name (ARN) of the application group for which you want to add or remove resources.

GroupName
Type: string

The name of the application group to onboard and sync resources.

RoleArn
Type: string

The Amazon resource name (ARN) of the role assumed by the service to tag and untag resources on your behalf.

TagKey
Type: string

The tag key of the tag-sync task.

TagValue
Type: string

The tag value of the tag-sync task.

TaskArn
Type: string

The Amazon resource name (ARN) of the new tag-sync task.

Errors

UnauthorizedException:

The request was rejected because it doesn't have valid credentials for the target resource.

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

Tag 

$result = $client->tag([/* ... */]);
$promise = $client->tagAsync([/* ... */]);

Adds tags to a resource group with the specified Amazon resource name (ARN). Existing tags on a resource group are not changed if they are not specified in the request parameters.

Do not store personally identifiable information (PII) or other confidential or sensitive information in tags. We use tags to provide you with billing and administration services. Tags are not intended to be used for private or sensitive data.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:Tag

Parameter Syntax

$result = $client->tag([
    'Arn' => '<string>', // REQUIRED
    'Tags' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members
Arn
Required: Yes
Type: string

The Amazon resource name (ARN) of the resource group to which to add tags.

Tags
Required: Yes
Type: Associative array of custom strings keys (TagKey) to strings

The tags to add to the specified resource group. A tag is a string-to-string map of key-value pairs.

Result Syntax

[
    'Arn' => '<string>',
    'Tags' => ['<string>', ...],
]

Result Details

Members
Arn
Type: string

The Amazon resource name (ARN) of the tagged resource.

Tags
Type: Associative array of custom strings keys (TagKey) to strings

The tags that have been added to the specified resource group.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

UngroupResources 

$result = $client->ungroupResources([/* ... */]);
$promise = $client->ungroupResourcesAsync([/* ... */]);

Removes the specified resources from the specified group. This operation works only with static groups that you populated using the GroupResources operation. It doesn't work with any resource groups that are automatically populated by tag-based or CloudFormation stack-based queries.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:UngroupResources

Parameter Syntax

$result = $client->ungroupResources([
    'Group' => '<string>', // REQUIRED
    'ResourceArns' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members
Group
Required: Yes
Type: string

The name or the Amazon resource name (ARN) of the resource group from which to remove the resources.

ResourceArns
Required: Yes
Type: Array of strings

The Amazon resource names (ARNs) of the resources to be removed from the group.

Result Syntax

[
    'Failed' => [
        [
            'ErrorCode' => '<string>',
            'ErrorMessage' => '<string>',
            'ResourceArn' => '<string>',
        ],
        // ...
    ],
    'Pending' => [
        [
            'ResourceArn' => '<string>',
        ],
        // ...
    ],
    'Succeeded' => ['<string>', ...],
]

Result Details

Members
Failed
Type: Array of FailedResource structures

A list of any resources that failed to be removed from the group by this operation.

Pending
Type: Array of PendingResource structures

A list of any resources that are still in the process of being removed from the group by this operation. These pending removals continue asynchronously. You can check the status of pending removals by using the ListGroupResources operation. After the resource is successfully removed, it no longer appears in the response.

Succeeded
Type: Array of strings

A list of resources that were successfully removed from the group by this operation.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

Untag 

$result = $client->untag([/* ... */]);
$promise = $client->untagAsync([/* ... */]);

Deletes tags from a specified resource group.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:Untag

Parameter Syntax

$result = $client->untag([
    'Arn' => '<string>', // REQUIRED
    'Keys' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members
Arn
Required: Yes
Type: string

The Amazon resource name (ARN) of the resource group from which to remove tags. The command removed both the specified keys and any values associated with those keys.

Keys
Required: Yes
Type: Array of strings

The keys of the tags to be removed.

Result Syntax

[
    'Arn' => '<string>',
    'Keys' => ['<string>', ...],
]

Result Details

Members
Arn
Type: string

The Amazon resource name (ARN) of the resource group from which tags have been removed.

Keys
Type: Array of strings

The keys of the tags that were removed.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

UpdateAccountSettings 

$result = $client->updateAccountSettings([/* ... */]);
$promise = $client->updateAccountSettingsAsync([/* ... */]);

Turns on or turns off optional features in Resource Groups.

The preceding example shows that the request to turn on group lifecycle events is IN_PROGRESS. You can call the GetAccountSettings operation to check for completion by looking for GroupLifecycleEventsStatus to change to ACTIVE.

Parameter Syntax

$result = $client->updateAccountSettings([
    'GroupLifecycleEventsDesiredStatus' => 'ACTIVE|INACTIVE',
]);

Parameter Details

Members
GroupLifecycleEventsDesiredStatus
Type: string

Specifies whether you want to turn group lifecycle events on or off.

You can't turn on group lifecycle events if your resource groups quota is greater than 2,000.

Result Syntax

[
    'AccountSettings' => [
        'GroupLifecycleEventsDesiredStatus' => 'ACTIVE|INACTIVE',
        'GroupLifecycleEventsStatus' => 'ACTIVE|INACTIVE|IN_PROGRESS|ERROR',
        'GroupLifecycleEventsStatusMessage' => '<string>',
    ],
]

Result Details

Members
AccountSettings
Type: AccountSettings structure

A structure that displays the status of the optional features in the account.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

UpdateGroup 

$result = $client->updateGroup([/* ... */]);
$promise = $client->updateGroupAsync([/* ... */]);

Updates the description for an existing group. You cannot update the name of a resource group.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:UpdateGroup

Parameter Syntax

$result = $client->updateGroup([
    'Criticality' => <integer>,
    'Description' => '<string>',
    'DisplayName' => '<string>',
    'Group' => '<string>',
    'GroupName' => '<string>',
    'Owner' => '<string>',
]);

Parameter Details

Members
Criticality
Type: int

The critical rank of the application group on a scale of 1 to 10, with a rank of 1 being the most critical, and a rank of 10 being least critical.

Description
Type: string

The new description that you want to update the resource group with. Descriptions can contain letters, numbers, hyphens, underscores, periods, and spaces.

DisplayName
Type: string

The name of the application group, which you can change at any time.

Group
Type: string

The name or the ARN of the resource group to update.

GroupName
Type: string

Don't use this parameter. Use Group instead.

Owner
Type: string

A name, email address or other identifier for the person or group who is considered as the owner of this application group within your organization.

Result Syntax

[
    'Group' => [
        'ApplicationTag' => ['<string>', ...],
        'Criticality' => <integer>,
        'Description' => '<string>',
        'DisplayName' => '<string>',
        'GroupArn' => '<string>',
        'Name' => '<string>',
        'Owner' => '<string>',
    ],
]

Result Details

Members
Group
Type: Group structure

The update description of the resource group.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

UpdateGroupQuery 

$result = $client->updateGroupQuery([/* ... */]);
$promise = $client->updateGroupQueryAsync([/* ... */]);

Updates the resource query of a group. For more information about resource queries, see Create a tag-based group in Resource Groups.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:UpdateGroupQuery

Parameter Syntax

$result = $client->updateGroupQuery([
    'Group' => '<string>',
    'GroupName' => '<string>',
    'ResourceQuery' => [ // REQUIRED
        'Query' => '<string>', // REQUIRED
        'Type' => 'TAG_FILTERS_1_0|CLOUDFORMATION_STACK_1_0', // REQUIRED
    ],
]);

Parameter Details

Members
Group
Type: string

The name or the Amazon resource name (ARN) of the resource group to query.

GroupName
Type: string

Don't use this parameter. Use Group instead.

ResourceQuery
Required: Yes
Type: ResourceQuery structure

The resource query to determine which Amazon Web Services resources are members of this resource group.

A resource group can contain either a Configuration or a ResourceQuery, but not both.

Result Syntax

[
    'GroupQuery' => [
        'GroupName' => '<string>',
        'ResourceQuery' => [
            'Query' => '<string>',
            'Type' => 'TAG_FILTERS_1_0|CLOUDFORMATION_STACK_1_0',
        ],
    ],
]

Result Details

Members
GroupQuery
Type: GroupQuery structure

The updated resource query associated with the resource group after the update.

Errors

BadRequestException:

The request includes one or more parameters that violate validation rules.

ForbiddenException:

The caller isn't authorized to make the request. Check permissions.

NotFoundException:

One or more of the specified resources don't exist.

MethodNotAllowedException:

The request uses an HTTP method that isn't allowed for the specified resource.

TooManyRequestsException:

You've exceeded throttling limits by making too many requests in a period of time.

InternalServerErrorException:

An internal error occurred while processing the request. Try again later.

Shapes

AccountSettings

Description

The Resource Groups settings for this Amazon Web Services account.

Members
GroupLifecycleEventsDesiredStatus
Type: string

The desired target status of the group lifecycle events feature. If

GroupLifecycleEventsStatus
Type: string

The current status of the group lifecycle events feature.

GroupLifecycleEventsStatusMessage
Type: string

The text of any error message occurs during an attempt to turn group lifecycle events on or off.

BadRequestException

Description

The request includes one or more parameters that violate validation rules.

Members
Message
Type: string

FailedResource

Description

A resource that failed to be added to or removed from a group.

Members
ErrorCode
Type: string

The error code associated with the failure.

ErrorMessage
Type: string

The error message text associated with the failure.

ResourceArn
Type: string

The Amazon resource name (ARN) of the resource that failed to be added or removed.

ForbiddenException

Description

The caller isn't authorized to make the request. Check permissions.

Members
Message
Type: string

Group

Description

A resource group that contains Amazon Web Services resources. You can assign resources to the group by associating either of the following elements with the group:

  • ResourceQuery - Use a resource query to specify a set of tag keys and values. All resources in the same Amazon Web Services Region and Amazon Web Services account that have those keys with the same values are included in the group. You can add a resource query when you create the group, or later by using the PutGroupConfiguration operation.

  • GroupConfiguration - Use a service configuration to associate the group with an Amazon Web Services service. The configuration specifies which resource types can be included in the group.

Members
ApplicationTag
Type: Associative array of custom strings keys (ApplicationTagKey) to strings

A tag that defines the application group membership. This tag is only supported for application groups.

Criticality
Type: int

The critical rank of the application group on a scale of 1 to 10, with a rank of 1 being the most critical, and a rank of 10 being least critical.

Description
Type: string

The description of the resource group.

DisplayName
Type: string

The name of the application group, which you can change at any time.

GroupArn
Required: Yes
Type: string

The Amazon resource name (ARN) of the resource group.

Name
Required: Yes
Type: string

The name of the resource group.

Owner
Type: string

A name, email address or other identifier for the person or group who is considered as the owner of this application group within your organization.

GroupConfiguration

Description

A service configuration associated with a resource group. The configuration options are determined by the Amazon Web Services service that defines the Type, and specifies which resources can be included in the group. You can add a service configuration when you create the group by using CreateGroup, or later by using the PutGroupConfiguration operation. For details about group service configuration syntax, see Service configurations for resource groups.

Members
Configuration
Type: Array of GroupConfigurationItem structures

The configuration currently associated with the group and in effect.

FailureReason
Type: string

If present, the reason why a request to update the group configuration failed.

ProposedConfiguration
Type: Array of GroupConfigurationItem structures

If present, the new configuration that is in the process of being applied to the group.

Status
Type: string

The current status of an attempt to update the group configuration.

GroupConfigurationItem

Description

An item in a group configuration. A group service configuration can have one or more items. For details about group service configuration syntax, see Service configurations for resource groups.

Members
Parameters
Type: Array of GroupConfigurationParameter structures

A collection of parameters for this group configuration item. For the list of parameters that you can use with each configuration item type, see Supported resource types and parameters.

Type
Required: Yes
Type: string

Specifies the type of group configuration item. Each item must have a unique value for type. For the list of types that you can specify for a configuration item, see Supported resource types and parameters.

GroupConfigurationParameter

Description

A parameter for a group configuration item. For details about group service configuration syntax, see Service configurations for resource groups.

Members
Name
Required: Yes
Type: string

The name of the group configuration parameter. For the list of parameters that you can use with each configuration item type, see Supported resource types and parameters.

Values
Type: Array of strings

The value or values to be used for the specified parameter. For the list of values you can use with each parameter, see Supported resource types and parameters.

GroupFilter

Description

A filter collection that you can use to restrict the results from a List operation to only those you want to include.

Members
Name
Required: Yes
Type: string

The name of the filter. Filter names are case-sensitive.

Values
Required: Yes
Type: Array of strings

One or more filter values. Allowed filter values vary by group filter name, and are case-sensitive.

GroupIdentifier

Description

The unique identifiers for a resource group.

Members
Criticality
Type: int

The critical rank of the application group on a scale of 1 to 10, with a rank of 1 being the most critical, and a rank of 10 being least critical.

Description
Type: string

The description of the application group.

DisplayName
Type: string

The name of the application group, which you can change at any time.

GroupArn
Type: string

The Amazon resource name (ARN) of the resource group.

GroupName
Type: string

The name of the resource group.

Owner
Type: string

A name, email address or other identifier for the person or group who is considered as the owner of this group within your organization.

GroupQuery

Description

A mapping of a query attached to a resource group that determines the Amazon Web Services resources that are members of the group.

Members
GroupName
Required: Yes
Type: string

The name of the resource group that is associated with the specified resource query.

ResourceQuery
Required: Yes
Type: ResourceQuery structure

The resource query that determines which Amazon Web Services resources are members of the associated resource group.

GroupingStatusesItem

Description

The information about a grouping or ungrouping resource action.

Members
Action
Type: string

Describes the resource grouping action with values of GROUP or UNGROUP.

ErrorCode
Type: string

Specifies the error code that was raised.

ErrorMessage
Type: string

A message that explains the ErrorCode.

ResourceArn
Type: string

The Amazon resource name (ARN) of a resource.

Status
Type: string

Describes the resource grouping status with values of SUCCESS, FAILED, IN_PROGRESS, or SKIPPED.

UpdatedAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

A timestamp of when the status was last updated.

InternalServerErrorException

Description

An internal error occurred while processing the request. Try again later.

Members
Message
Type: string

ListGroupResourcesItem

Description

A structure returned by the ListGroupResources operation that contains identity and group membership status information for one of the resources in the group.

Members
Identifier
Type: ResourceIdentifier structure

A structure that contains the ARN of a resource and its resource type.

Status
Type: ResourceStatus structure

A structure that contains the status of this resource's membership in the group.

This field is present in the response only if the group is of type AWS::EC2::HostManagement.

ListGroupingStatusesFilter

Description

A filter name and value pair that is used to obtain more specific results from the list of grouping statuses.

Members
Name
Required: Yes
Type: string

The name of the filter. Filter names are case-sensitive.

Values
Required: Yes
Type: Array of strings

One or more filter values. Allowed filter values vary by resource filter name, and are case-sensitive.

ListTagSyncTasksFilter

Description

Returns tag-sync tasks filtered by the Amazon resource name (ARN) or name of a specified application group.

Members
GroupArn
Type: string

The Amazon resource name (ARN) of the application group.

GroupName
Type: string

The name of the application group.

MethodNotAllowedException

Description

The request uses an HTTP method that isn't allowed for the specified resource.

Members
Message
Type: string

NotFoundException

Description

One or more of the specified resources don't exist.

Members
Message
Type: string

PendingResource

Description

A structure that identifies a resource that is currently pending addition to the group as a member. Adding a resource to a resource group happens asynchronously as a background task and this one isn't completed yet.

Members
ResourceArn
Type: string

The Amazon resource name (ARN) of the resource that's in a pending state.

QueryError

Description

A two-part error structure that can occur in ListGroupResources or SearchResources.

Members
ErrorCode
Type: string

Specifies the error code that was raised.

Message
Type: string

A message that explains the ErrorCode.

ResourceFilter

Description

A filter name and value pair that is used to obtain more specific results from a list of resources.

Members
Name
Required: Yes
Type: string

The name of the filter. Filter names are case-sensitive.

Values
Required: Yes
Type: Array of strings

One or more filter values. Allowed filter values vary by resource filter name, and are case-sensitive.

ResourceIdentifier

Description

A structure that contains the ARN of a resource and its resource type.

Members
ResourceArn
Type: string

The Amazon resource name (ARN) of a resource.

ResourceType
Type: string

The resource type of a resource, such as AWS::EC2::Instance.

ResourceQuery

Description

The query you can use to define a resource group or a search for resources. A ResourceQuery specifies both a query Type and a Query string as JSON string objects. See the examples section for example JSON strings. For more information about creating a resource group with a resource query, see Build queries and groups in Resource Groups in the Resource Groups User Guide

When you combine all of the elements together into a single string, any double quotes that are embedded inside another double quote pair must be escaped by preceding the embedded double quote with a backslash character (\). For example, a complete ResourceQuery parameter must be formatted like the following CLI parameter example:

--resource-query '{"Type":"TAG_FILTERS_1_0","Query":"{\"ResourceTypeFilters\":[\"AWS::AllSupported\"],\"TagFilters\":[{\"Key\":\"Stage\",\"Values\":[\"Test\"]}]}"}'

In the preceding example, all of the double quote characters in the value part of the Query element must be escaped because the value itself is surrounded by double quotes. For more information, see Quoting strings in the Command Line Interface User Guide.

For the complete list of resource types that you can use in the array value for ResourceTypeFilters, see Resources you can use with Resource Groups and Tag Editor in the Resource Groups User Guide. For example:

"ResourceTypeFilters":["AWS::S3::Bucket", "AWS::EC2::Instance"]

Members
Query
Required: Yes
Type: string

The query that defines a group or a search. The contents depends on the value of the Type element.

  • ResourceTypeFilters – Applies to all ResourceQuery objects of either Type. This element contains one of the following two items:

    • The value AWS::AllSupported. This causes the ResourceQuery to match resources of any resource type that also match the query.

    • A list (a JSON array) of resource type identifiers that limit the query to only resources of the specified types. For the complete list of resource types that you can use in the array value for ResourceTypeFilters, see Resources you can use with Resource Groups and Tag Editor in the Resource Groups User Guide.

    Example: "ResourceTypeFilters": ["AWS::AllSupported"] or "ResourceTypeFilters": ["AWS::EC2::Instance", "AWS::S3::Bucket"]

  • TagFilters – applicable only if Type = TAG_FILTERS_1_0. The Query contains a JSON string that represents a collection of simple tag filters. The JSON string uses a syntax similar to the GetResources operation, but uses only the ResourceTypeFilters and TagFilters fields. If you specify more than one tag key, only resources that match all tag keys, and at least one value of each specified tag key, are returned in your query. If you specify more than one value for a tag key, a resource matches the filter if it has a tag key value that matches any of the specified values.

    For example, consider the following sample query for resources that have two tags, Stage and Version, with two values each:

    [{"Stage":["Test","Deploy"]},{"Version":["1","2"]}]

    The results of this resource query could include the following.

    • An Amazon EC2 instance that has the following two tags: {"Stage":"Deploy"}, and {"Version":"2"}

    • An S3 bucket that has the following two tags: {"Stage":"Test"}, and {"Version":"1"}

    The resource query results would not include the following items in the results, however.

    • An Amazon EC2 instance that has only the following tag: {"Stage":"Deploy"}.

      The instance does not have all of the tag keys specified in the filter, so it is excluded from the results.

    • An RDS database that has the following two tags: {"Stage":"Archived"} and {"Version":"4"}

      The database has all of the tag keys, but none of those keys has an associated value that matches at least one of the specified values in the filter.

    Example: "TagFilters": [ { "Key": "Stage", "Values": [ "Gamma", "Beta" ] }

  • StackIdentifier – applicable only if Type = CLOUDFORMATION_STACK_1_0. The value of this parameter is the Amazon Resource Name (ARN) of the CloudFormation stack whose resources you want included in the group.

Type
Required: Yes
Type: string

The type of the query to perform. This can have one of two values:

  • CLOUDFORMATION_STACK_1_0: Specifies that you want the group to contain the members of an CloudFormation stack. The Query contains a StackIdentifier element with an Amazon resource name (ARN) for a CloudFormation stack.

  • TAG_FILTERS_1_0: Specifies that you want the group to include resource that have tags that match the query.

ResourceStatus

Description

A structure that identifies the current group membership status for a resource. Adding a resource to a resource group is performed asynchronously as a background task. A PENDING status indicates, for this resource, that the process isn't completed yet.

Members
Name
Type: string

The current status.

TagSyncTaskItem

Description

The Amazon resource name (ARN) of the tag-sync task.

Members
CreatedAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

The timestamp of when the tag-sync task was created.

ErrorMessage
Type: string

The specific error message in cases where the tag-sync task status is Error.

GroupArn
Type: string

The Amazon resource name (ARN) of the application group.

GroupName
Type: string

The name of the application group.

RoleArn
Type: string

The Amazon resource name (ARN) of the role assumed by the service to tag and untag resources on your behalf.

Status
Type: string

The status of the tag-sync task.

Valid values include:

  • ACTIVE - The tag-sync task is actively managing resources in the application by adding or removing the awsApplication tag from resources when they are tagged or untagged with the specified tag key-value pair.

  • ERROR - The tag-sync task is not actively managing resources in the application. Review the ErrorMessage for more information about resolving the error.

TagKey
Type: string

The tag key.

TagValue
Type: string

The tag value.

TaskArn
Type: string

The Amazon resource name (ARN) of the tag-sync task.

TooManyRequestsException

Description

You've exceeded throttling limits by making too many requests in a period of time.

Members
Message
Type: string

UnauthorizedException

Description

The request was rejected because it doesn't have valid credentials for the target resource.

Members
Message
Type: string