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 */).
- CreateGroup ( array $params = [] )
Creates a group with a specified name, description, and resource query.
- DeleteGroup ( array $params = [] )
Deletes a specified resource group.
- GetGroup ( array $params = [] )
Returns information about a specified resource group.
- GetGroupQuery ( array $params = [] )
Returns the resource query associated with the specified resource group.
- GetTags ( array $params = [] )
Returns a list of tags that are associated with a resource group, specified by an ARN.
- ListGroupResources ( array $params = [] )
Returns a list of ARNs of resources that are members of a specified resource group.
- ListGroups ( array $params = [] )
Returns a list of existing resource groups in your account.
- SearchResources ( array $params = [] )
Returns a list of AWS resource identifiers that matches a specified query.
- Tag ( array $params = [] )
Adds tags to a resource group with the specified ARN.
- Untag ( array $params = [] )
Deletes specified tags from a specified resource.
- UpdateGroup ( array $params = [] )
Updates an existing group with a new or changed description.
- 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:
Operations
CreateGroup
$result = $client->createGroup([/* ... */]); $promise = $client->createGroupAsync([/* ... */]);
Creates a group with a specified name, description, and resource query.
Parameter Syntax
$result = $client->createGroup([
'Description' => '<string>',
'Name' => '<string>', // REQUIRED
'ResourceQuery' => [ // REQUIRED
'Query' => '<string>', // REQUIRED
'Type' => 'TAG_FILTERS_1_0|CLOUDFORMATION_STACK_1_0', // REQUIRED
],
'Tags' => ['<string>', ...],
]);
Parameter Details
Members
- Description
-
- Type: string
The description of the resource group. Descriptions can have a maximum of 511 characters, including letters, numbers, hyphens, underscores, punctuation, and spaces.
- Name
-
- Required: Yes
- Type: string
The name of the group, which is the identifier of the group in other operations. A resource group name cannot be updated after it is created. A resource group name can have a maximum of 128 characters, including letters, numbers, hyphens, dots, and underscores. The name cannot start with
AWSoraws; these are reserved. A resource group name must be unique within your account. - ResourceQuery
-
- Required: Yes
- Type: ResourceQuery structure
The resource query that determines which AWS resources are members of this group.
- Tags
-
- Type: Associative array of custom strings keys (TagKey) to strings
The tags to add to the group. A tag is a string-to-string map of key-value pairs. Tag keys can have a maximum character length of 128 characters, and tag values can have a maximum length of 256 characters.
Result Syntax
[
'Group' => [
'Description' => '<string>',
'GroupArn' => '<string>',
'Name' => '<string>',
],
'ResourceQuery' => [
'Query' => '<string>',
'Type' => 'TAG_FILTERS_1_0|CLOUDFORMATION_STACK_1_0',
],
'Tags' => ['<string>', ...],
]
Result Details
Members
- Group
-
- Type: Group structure
A full description of the resource group after it is created.
- ResourceQuery
-
- Type: ResourceQuery structure
The resource query associated with the group.
- Tags
-
- Type: Associative array of custom strings keys (TagKey) to strings
The tags associated with the group.
Errors
-
The request does not comply with validation rules that are defined for the request parameters.
-
The caller is not authorized to make the request.
-
The request uses an HTTP method which is not allowed for the specified resource.
-
The caller has exceeded throttling limits.
-
An internal error occurred while processing the request.
DeleteGroup
$result = $client->deleteGroup([/* ... */]); $promise = $client->deleteGroupAsync([/* ... */]);
Deletes a specified resource group. Deleting a resource group does not delete resources that are members of the group; it only deletes the group structure.
Parameter Syntax
$result = $client->deleteGroup([
'GroupName' => '<string>', // REQUIRED
]);
Parameter Details
Result Syntax
[
'Group' => [
'Description' => '<string>',
'GroupArn' => '<string>',
'Name' => '<string>',
],
]
Result Details
Members
- Group
-
- Type: Group structure
A full description of the deleted resource group.
Errors
-
The request does not comply with validation rules that are defined for the request parameters.
-
The caller is not authorized to make the request.
-
One or more resources specified in the request do not exist.
-
The request uses an HTTP method which is not allowed for the specified resource.
-
The caller has exceeded throttling limits.
-
An internal error occurred while processing the request.
GetGroup
$result = $client->getGroup([/* ... */]); $promise = $client->getGroupAsync([/* ... */]);
Returns information about a specified resource group.
Parameter Syntax
$result = $client->getGroup([
'GroupName' => '<string>', // REQUIRED
]);
Parameter Details
Result Syntax
[
'Group' => [
'Description' => '<string>',
'GroupArn' => '<string>',
'Name' => '<string>',
],
]
Result Details
Members
- Group
-
- Type: Group structure
A full description of the resource group.
Errors
-
The request does not comply with validation rules that are defined for the request parameters.
-
The caller is not authorized to make the request.
-
One or more resources specified in the request do not exist.
-
The request uses an HTTP method which is not allowed for the specified resource.
-
The caller has exceeded throttling limits.
-
An internal error occurred while processing the request.
GetGroupQuery
$result = $client->getGroupQuery([/* ... */]); $promise = $client->getGroupQueryAsync([/* ... */]);
Returns the resource query associated with the specified resource group.
Parameter Syntax
$result = $client->getGroupQuery([
'GroupName' => '<string>', // REQUIRED
]);
Parameter Details
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.
Errors
-
The request does not comply with validation rules that are defined for the request parameters.
-
The caller is not authorized to make the request.
-
One or more resources specified in the request do not exist.
-
The request uses an HTTP method which is not allowed for the specified resource.
-
The caller has exceeded throttling limits.
-
An internal error occurred while processing the request.
GetTags
$result = $client->getTags([/* ... */]); $promise = $client->getTagsAsync([/* ... */]);
Returns a list of tags that are associated with a resource group, specified by an ARN.
Parameter Syntax
$result = $client->getTags([
'Arn' => '<string>', // REQUIRED
]);
Parameter Details
Members
Result Syntax
[
'Arn' => '<string>',
'Tags' => ['<string>', ...],
]
Result Details
Members
Errors
-
The request does not comply with validation rules that are defined for the request parameters.
-
The caller is not authorized to make the request.
-
One or more resources specified in the request do not exist.
-
The request uses an HTTP method which is not allowed for the specified resource.
-
The caller has exceeded throttling limits.
-
An internal error occurred while processing the request.
ListGroupResources
$result = $client->listGroupResources([/* ... */]); $promise = $client->listGroupResourcesAsync([/* ... */]);
Returns a list of ARNs of resources that are members of a specified resource group.
Parameter Syntax
$result = $client->listGroupResources([
'Filters' => [
[
'Name' => 'resource-type', // REQUIRED
'Values' => ['<string>', ...], // REQUIRED
],
// ...
],
'GroupName' => '<string>', // REQUIRED
'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.
-
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.
- GroupName
-
- Required: Yes
- Type: string
The name of the resource group.
- MaxResults
-
- Type: int
The maximum number of group member ARNs that are returned in a single call by ListGroupResources, in paginated output. By default, this number is 50.
- NextToken
-
- Type: string
The NextToken value that is returned in a paginated ListGroupResources request. To get the next page of results, run the call again, add the NextToken parameter, and specify the NextToken value.
Result Syntax
[
'NextToken' => '<string>',
'QueryErrors' => [
[
'ErrorCode' => 'CLOUDFORMATION_STACK_INACTIVE|CLOUDFORMATION_STACK_NOT_EXISTING',
'Message' => '<string>',
],
// ...
],
'ResourceIdentifiers' => [
[
'ResourceArn' => '<string>',
'ResourceType' => '<string>',
],
// ...
],
]
Result Details
Members
- NextToken
-
- Type: string
The NextToken value to include in a subsequent
ListGroupResourcesrequest, to get more results. - QueryErrors
-
- Type: Array of QueryError structures
A list of
QueryErrorobjects. Each error is an object that containsErrorCodeandMessagestructures. Possible values forErrorCodeareCLOUDFORMATION_STACK_INACTIVEandCLOUDFORMATION_STACK_NOT_EXISTING. - ResourceIdentifiers
-
- Type: Array of ResourceIdentifier structures
The ARNs and resource types of resources that are members of the group that you specified.
Errors
-
The request has not been applied because it lacks valid authentication credentials for the target resource.
-
The request does not comply with validation rules that are defined for the request parameters.
-
The caller is not authorized to make the request.
-
One or more resources specified in the request do not exist.
-
The request uses an HTTP method which is not allowed for the specified resource.
-
The caller has exceeded throttling limits.
-
An internal error occurred while processing the request.
ListGroups
$result = $client->listGroups([/* ... */]); $promise = $client->listGroupsAsync([/* ... */]);
Returns a list of existing resource groups in your account.
Parameter Syntax
$result = $client->listGroups([
'Filters' => [
[
'Name' => 'resource-type', // 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 groups by resource type. Specify up to five resource types in the format AWS::ServiceCode::ResourceType. For example, AWS::EC2::Instance, or AWS::S3::Bucket.
- MaxResults
-
- Type: int
The maximum number of resource group results that are returned by ListGroups in paginated output. By default, this number is 50.
- NextToken
-
- Type: string
The NextToken value that is returned in a paginated
ListGroupsrequest. To get the next page of results, run the call again, add the NextToken parameter, and specify the NextToken value.
Result Syntax
[
'GroupIdentifiers' => [
[
'GroupArn' => '<string>',
'GroupName' => '<string>',
],
// ...
],
'Groups' => [
[
'Description' => '<string>',
'GroupArn' => '<string>',
'Name' => '<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 GroupName and the GroupArn.
- Groups
-
- Type: Array of Group structures
A list of resource groups.
- NextToken
-
- Type: string
The NextToken value to include in a subsequent
ListGroupsrequest, to get more results.
Errors
-
The request does not comply with validation rules that are defined for the request parameters.
-
The caller is not authorized to make the request.
-
The request uses an HTTP method which is not allowed for the specified resource.
-
The caller has exceeded throttling limits.
-
An internal error occurred while processing the request.
SearchResources
$result = $client->searchResources([/* ... */]); $promise = $client->searchResourcesAsync([/* ... */]);
Returns a list of AWS resource identifiers that matches a specified query. The query uses the same format as a resource query in a CreateGroup or UpdateGroupQuery operation.
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 maximum number of group member ARNs returned by
SearchResourcesin paginated output. By default, this number is 50. - NextToken
-
- Type: string
The NextToken value that is returned in a paginated
SearchResourcesrequest. To get the next page of results, run the call again, add the NextToken parameter, and specify the NextToken value. - ResourceQuery
-
- Required: Yes
- Type: ResourceQuery structure
The search query, using the same formats that are supported for resource group definition.
Result Syntax
[
'NextToken' => '<string>',
'QueryErrors' => [
[
'ErrorCode' => 'CLOUDFORMATION_STACK_INACTIVE|CLOUDFORMATION_STACK_NOT_EXISTING',
'Message' => '<string>',
],
// ...
],
'ResourceIdentifiers' => [
[
'ResourceArn' => '<string>',
'ResourceType' => '<string>',
],
// ...
],
]
Result Details
Members
- NextToken
-
- Type: string
The NextToken value to include in a subsequent
SearchResourcesrequest, to get more results. - QueryErrors
-
- Type: Array of QueryError structures
A list of
QueryErrorobjects. Each error is an object that containsErrorCodeandMessagestructures. Possible values forErrorCodeareCLOUDFORMATION_STACK_INACTIVEandCLOUDFORMATION_STACK_NOT_EXISTING. - ResourceIdentifiers
-
- Type: Array of ResourceIdentifier structures
The ARNs and resource types of resources that are members of the group that you specified.
Errors
-
The request has not been applied because it lacks valid authentication credentials for the target resource.
-
The request does not comply with validation rules that are defined for the request parameters.
-
The caller is not authorized to make the request.
-
The request uses an HTTP method which is not allowed for the specified resource.
-
The caller has exceeded throttling limits.
-
An internal error occurred while processing the request.
Tag
$result = $client->tag([/* ... */]); $promise = $client->tagAsync([/* ... */]);
Adds tags to a resource group with the specified ARN. Existing tags on a resource group are not changed if they are not specified in the request parameters.
Parameter Syntax
$result = $client->tag([
'Arn' => '<string>', // REQUIRED
'Tags' => ['<string>', ...], // REQUIRED
]);
Parameter Details
Members
- Arn
-
- Required: Yes
- Type: string
The ARN of the resource 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. A tag is a string-to-string map of key-value pairs. Tag keys can have a maximum character length of 128 characters, and tag values can have a maximum length of 256 characters.
Result Syntax
[
'Arn' => '<string>',
'Tags' => ['<string>', ...],
]
Result Details
Members
Errors
-
The request does not comply with validation rules that are defined for the request parameters.
-
The caller is not authorized to make the request.
-
One or more resources specified in the request do not exist.
-
The request uses an HTTP method which is not allowed for the specified resource.
-
The caller has exceeded throttling limits.
-
An internal error occurred while processing the request.
Untag
$result = $client->untag([/* ... */]); $promise = $client->untagAsync([/* ... */]);
Deletes specified tags from a specified resource.
Parameter Syntax
$result = $client->untag([
'Arn' => '<string>', // REQUIRED
'Keys' => ['<string>', ...], // REQUIRED
]);
Parameter Details
Members
Result Syntax
[
'Arn' => '<string>',
'Keys' => ['<string>', ...],
]
Result Details
Members
Errors
-
The request does not comply with validation rules that are defined for the request parameters.
-
The caller is not authorized to make the request.
-
One or more resources specified in the request do not exist.
-
The request uses an HTTP method which is not allowed for the specified resource.
-
The caller has exceeded throttling limits.
-
An internal error occurred while processing the request.
UpdateGroup
$result = $client->updateGroup([/* ... */]); $promise = $client->updateGroupAsync([/* ... */]);
Updates an existing group with a new or changed description. You cannot update the name of a resource group.
Parameter Syntax
$result = $client->updateGroup([
'Description' => '<string>',
'GroupName' => '<string>', // REQUIRED
]);
Parameter Details
Members
- Description
-
- Type: string
The description of the resource group. Descriptions can have a maximum of 511 characters, including letters, numbers, hyphens, underscores, punctuation, and spaces.
- GroupName
-
- Required: Yes
- Type: string
The name of the resource group for which you want to update its description.
Result Syntax
[
'Group' => [
'Description' => '<string>',
'GroupArn' => '<string>',
'Name' => '<string>',
],
]
Result Details
Members
- Group
-
- Type: Group structure
The full description of the resource group after it has been updated.
Errors
-
The request does not comply with validation rules that are defined for the request parameters.
-
The caller is not authorized to make the request.
-
One or more resources specified in the request do not exist.
-
The request uses an HTTP method which is not allowed for the specified resource.
-
The caller has exceeded throttling limits.
-
An internal error occurred while processing the request.
UpdateGroupQuery
$result = $client->updateGroupQuery([/* ... */]); $promise = $client->updateGroupQueryAsync([/* ... */]);
Updates the resource query of a group.
Parameter Syntax
$result = $client->updateGroupQuery([
'GroupName' => '<string>', // REQUIRED
'ResourceQuery' => [ // REQUIRED
'Query' => '<string>', // REQUIRED
'Type' => 'TAG_FILTERS_1_0|CLOUDFORMATION_STACK_1_0', // REQUIRED
],
]);
Parameter Details
Members
- GroupName
-
- Required: Yes
- Type: string
The name of the resource group for which you want to edit the query.
- ResourceQuery
-
- Required: Yes
- Type: ResourceQuery structure
The resource query that determines which AWS resources are members of the resource group.
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 resource group after the update.
Errors
-
The request does not comply with validation rules that are defined for the request parameters.
-
The caller is not authorized to make the request.
-
One or more resources specified in the request do not exist.
-
The request uses an HTTP method which is not allowed for the specified resource.
-
The caller has exceeded throttling limits.
-
An internal error occurred while processing the request.
Shapes
BadRequestException
Description
The request does not comply with validation rules that are defined for the request parameters.
Members
ForbiddenException
Group
Description
A resource group.
Members
GroupFilter
Description
A filter name and value pair that is used to obtain more specific results from a list of groups.
Members
GroupIdentifier
Description
The ARN and group name of a group.
Members
GroupQuery
Description
The underlying resource query of a resource group. Resources that match query results are part of the group.
Members
- GroupName
-
- Required: Yes
- Type: string
The name of a resource group that is associated with a specific resource query.
- ResourceQuery
-
- Required: Yes
- Type: ResourceQuery structure
The resource query which determines which AWS resources are members of the associated resource group.
InternalServerErrorException
MethodNotAllowedException
Description
The request uses an HTTP method which is not allowed for the specified resource.
Members
NotFoundException
Description
One or more resources specified in the request do not exist.
Members
QueryError
Description
A two-part error structure that can occur in ListGroupResources or SearchResources operations on CloudFormation stack-based queries. The error occurs if the CloudFormation stack on which the query is based either does not exist, or has a status that renders the stack inactive. A QueryError occurrence does not necessarily mean that AWS Resource Groups could not complete the operation, but the resulting group might have no member resources.
Members
- ErrorCode
-
- Type: string
Possible values are
CLOUDFORMATION_STACK_INACTIVEandCLOUDFORMATION_STACK_NOT_EXISTING. - Message
-
- Type: string
A message that explains the
ErrorCodevalue. Messages might state that the specified CloudFormation stack does not exist (or no longer exists). ForCLOUDFORMATION_STACK_INACTIVE, the message typically states that the CloudFormation stack has a status that is not (or no longer) active, such asCREATE_FAILED.
ResourceFilter
Description
A filter name and value pair that is used to obtain more specific results from a list of resources.
Members
ResourceIdentifier
Description
The ARN of a resource, and its resource type.
Members
ResourceQuery
Description
The query that is used to define a resource group or a search for resources.
Members
- Query
-
- Required: Yes
- Type: string
The query that defines a group or a search.
- Type
-
- Required: Yes
- Type: string
The type of the query. The valid values in this release are
TAG_FILTERS_1_0andCLOUDFORMATION_STACK_1_0.TAG_FILTERS_1_0:A JSON syntax that lets you specify a collection of simple tag filters for resource types and tags, as supported by the AWS Tagging API GetResources operation. 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,
StageandVersion, with two values each. ([{"Key":"Stage","Values":["Test","Deploy"]},{"Key":"Version","Values":["1","2"]}]) The results of this query might include the following.-
An EC2 instance that has the following two tags:
{"Key":"Stage","Value":"Deploy"}, and{"Key":"Version","Value":"2"} -
An S3 bucket that has the following two tags: {"Key":"Stage","Value":"Test"}, and {"Key":"Version","Value":"1"}
The query would not return the following results, however. The following EC2 instance does not have all tag keys specified in the filter, so it is rejected. The RDS database has all of the tag keys, but no values that match at least one of the specified tag key values in the filter.
-
An EC2 instance that has only the following tag:
{"Key":"Stage","Value":"Deploy"}. -
An RDS database that has the following two tags:
{"Key":"Stage","Value":"Archived"}, and{"Key":"Version","Value":"4"}
CLOUDFORMATION_STACK_1_0:A JSON syntax that lets you specify a CloudFormation stack ARN.
