All Products
Search
Document Center

Elastic Compute Service:ListTagResources

Last Updated:May 14, 2024

Queries the tags that are added to one or more Elastic Compute Service (ECS) resources.

Operation description

You must specify at least one of the following parameters or parameter pairs in a request to determine a query object:

  • ResourceId.N
  • Tag.N parameter pair (Tag.N.Key and Tag.N.Value)
  • TagFilter.N

If one of the following sets of request parameters is specified as filter conditions, only ECS resources that meet all of the specified filter conditions are returned:

  • Set 1: Tag.N.Key, Tag.N.Value, and ResourceId.N
  • Set 2: TagFilter.N.TagKey, TagFilter.N.TagValues.N, and ResourceId.N

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringYes

The region ID of the resource. You can call the DescribeRegions operation to query the most recent region list.

cn-hangzhou
NextTokenstringNo

The pagination token that is used in the next request to retrieve a new page of results.

caeba0bbb2be03f84eb48b699f0a4883
ResourceTypestringYes

The type of the resource. Valid values:

  • instance: ECS instance
  • disk: disk
  • snapshot: snapshot
  • image: image
  • securitygroup: security group
  • volume: storage volume
  • eni: ENI
  • ddh: dedicated host
  • ddhcluster: dedicated host cluster
  • keypair: SSH key pair
  • launchtemplate: launch template
  • reservedinstance: reserved instance
  • snapshotpolicy: automatic snapshot policy
  • elasticityassurance: elasticity assurance
  • capacityreservation: capacity reservation
  • command: Cloud Assistant command
  • invocation: Cloud Assistant command execution result
instance
ResourceIdarrayNo

The resource IDs. Valid values of N: 1 to 50.

stringNo

The resource ID. Valid values of N: 1 to 50.

i-bp1j6qtvdm8w0z1o****
Tagobject []No

The tags.

KeystringNo

The key of tag N used for exact search of ECS resources. The tag key must be 1 to 128 characters in length. Valid values of N: 1 to 20.

Methods of using the Tag.N parameter pair (Tag.N.Key and Tag.N.Value):

  • Method 1: Use this parameter pair for exact search of ECS resources that have specified tags added. Each tag is a key-value pair.

    • If you specify only Tag.N.Key, all ECS resources whose tags contain the specified tag key are returned.
    • If you specify only Tag.N.Value, the InvalidParameter.TagValue error is returned.
    • If you specify multiple tag key-value pairs, only the ECS resources that have all these tag key-value pairs added are returned.
  • Method 2: Use this parameter pair to query resource information of a non-default resource group. Set Key to acs:rm:rgId and Value to the ID of a resource group.

    • If you set Key to acs:rm:rgId, you must set Value to the ID of a non-default resource group. If you set Value to the ID of the default resource group, an error message is returned.
    • If you set Key to acs:rm:rgId, you cannot specify other Tag.N parameter pairs. If you specify multiple Tag.N parameter pairs to query resource groups and resources at the same time, an error message is returned.
TestKey
ValuestringNo

The value of tag N used for exact search of ECS resources. The tag value must be 1 to 128 characters in length. Valid values of N: 1 to 20.

Note When Key is set to acs:rm:rgId, you can set Value only to the ID of a non-default resource group.
TestValue
TagFilterobject []No

The regular expressions used to filter tags.

TagValuesarrayNo

The values of tag N used for fuzzy search of ECS resources. The tag values must be 1 to 128 characters in length. Valid values of N: 1 to 5. For more information, see the description of TagFilter.N.TagKey.

stringNo

The value of tag N used for fuzzy search of ECS resources. The tag value must be 1 to 128 characters in length. Valid values of N: 1 to 5. For more information, see the description of TagFilter.N.TagKey.

TestTagFilter
TagKeystringNo

The key of tag N used for fuzzy search of ECS resources. The tag key must be 1 to 128 characters in length. Valid values of N: 1 to 5.

The TagFilter.N parameter pair (TagFilter.N.TagKey and TagFilter.N.TagValues.N) is used for fuzzy search of ECS resources that have specified tags added. In the specified tags, a single tag key may correspond to one or more tag values. Fuzzy search may have a latency of 2 seconds. A fuzzy search can return a result set of entries about a maximum of 5,000 resources.

  • When you use TagFilter.N.TagKey for fuzzy search of ECS resources, you must leave TagFilter.N.TagValues.N empty. For example, to query ECS resources whose tags contain the environment tag key, you can set TagFilter.1.TagKey to env* for prefix search, *env* for infix search, or env for exact search, but you must leave TagFilter.1.TagValues empty.
  • When you use TagFilter.N.TagValues.N for fuzzy search of ECS resources, you must set TagFilter.N.TagKey to an exact value. For example, to query ECS resources that have a tag composed of the env tag key and the product tag value, you must set TagFilter.1.TagKey to env and can set TagFilter.1.TagValues.1 to proc* for prefix search, to *proc* for infix search, or to proc for exact search. Only one of the preceding search methods can be used for each tag key (TagFilter.N.TagKey). If multiple search methods are configured for a tag key, the first search method prevails.
  • If you specify multiple tag keys, only the ECS resources that have all the specified tag keys added are returned.
  • If you specify a tag key that corresponds to multiple tag values, all the ECS resources that have one or more of these tag key-value pairs added are returned.
Note The TagFilter.N parameter pair (TagFilter.N.TagKey and TagFilter.N.TagValues.N) cannot be used together with the Tag.N parameter pair (Tag.N.Key and Tag.N.Value). Otherwise, an error message is returned.
env

Response parameters

ParameterTypeDescriptionExample
object
NextTokenstring

A pagination token.

caeba0bbb2be03f84eb48b699f0a4883
RequestIdstring

The request ID.

484256DA-D816-44D2-9D86-B6EE4D5BA78C
TagResourcesobject []

The details about the resources and tags, such as the resource ID, the resource type, tag keys, and tag values.

TagValuestring

The value of the tag.

TestValue
ResourceTypestring

The type of a resource. Valid values:

  • instance: ECS instance
  • disk: disk
  • snapshot: snapshot
  • image: image
  • securitygroup: security group
  • volume: storage volume
  • eni: ENI
  • ddh: dedicated host
  • ddhcluster: dedicated host cluster
  • keypair: SSH key pair
  • launchtemplate: launch template
  • reservedinstance: reserved instance
  • snapshotpolicy: automatic snapshot policy
  • elasticityassurance: elasticity assurance
  • capacityreservation: capacity reservation
  • command: Cloud Assistant command
  • invocation: Cloud Assistant command execution result
instance
ResourceIdstring

The resource ID.

i-bp1j6qtvdm8w0z1o****
TagKeystring

The key of the tag.

TestKey

Examples

Sample success responses

JSONformat

{
  "NextToken": "caeba0bbb2be03f84eb48b699f0a4883",
  "RequestId": "484256DA-D816-44D2-9D86-B6EE4D5BA78C",
  "TagResources": {
    "TagResource": [
      {
        "TagValue": "TestValue",
        "ResourceType": "instance",
        "ResourceId": "i-bp1j6qtvdm8w0z1o****",
        "TagKey": "TestKey"
      }
    ]
  }
}

Error codes

HTTP status codeError codeError messageDescription
400InvalidDefaultResourceGroup.NotSupportedThe specified parameter Tag is not support for default resource group.The default resource group cannot be queried.
400InvalidTag.NotSupportedYou can only specify Tag for either resource tag or resource group.Resource groups and tags cannot be queried at the same time.
400NumberExceed.ResourceIdsThe ResourceIds parameter's number is exceed , Valid : 50.-
400NumberExceed.TagsThe Tags parameter's number is exceed , Valid : 20.-
400Duplicate.TagKeyThe Tag.N.Key contain duplicate key.The specified tag key already exists. Tag keys must be unique.
400InvalidTagKey.MalformedThe specified Tag.n.Key is not valid.The specified Tag.N.Key parameter is invalid.
400InvalidTagValue.MalformedThe specified Tag.n.Value is not valid.The specified tag value is invalid.
400OperationDenied.QuotaExceedThe quota of tags on resource is beyond permitted range.The maximum number of tags on resource is exceeded.
400InvalidTag.MismatchThe specified Tag.n.Key and Tag.n.Value are not match.The specified Tag.N.Key and Tag.N.Value parameters do not correspond to each other.
400InvalidTagCountThe specified tags are beyond the permitted range.The number of specified tags exceeds the upper limit.
400Invalid.ScopeThe specified scope is invalid.The specified Scope parameter is invalid.
400InvalidTags.MalFormedThe tags must be empty, when the tagFilters is not empty.-
403PermissionDenied.TagOwnerBidThe specified operator not have permission to set TagOwnerBid value.-
403PermissionDenied.TagOwnerUidThe specified operator not have permission to set TagOwnerUid value.You are not authorized to specify the TagOwnerUid parameter.
403PermissionDenied.ScopeThe specified operator not have permission to set Scope value.You are not authorized to specify the Scope parameter.
403InvalidResourceId.NotSupportedThe specified ResourceId does not support tagging.The specified resource does not support tagging.
403NoPermission.TagThe operator is not permission for the tag.You are not authorized to manage the tag.
403BothEmpty.TagsAndResourcesThe specified Tags and ResourcesIds are not allow to both empty.-
403PermissionDenied.TagsFuzzyQueryThe specified operator has not permission to query fuzzy tags.-
403NumberExceed.TagValuesThe number of the specified TagValues is beyond permitted range, the max is 5.-
403InvalidFilter.MalformedThe specified Filter is not valid.-
403InvalidTagFilter.MalformedThe specified TagFilter is not valid.-
403Invalid.NextTokenThe specified NextToken is not valid.-
404InvalidRegionId.NotFoundThe RegionId provided does not exist in our records.The RegionId provided does not exist
404InvalidRegionId.NotFound%sThe specified region ID does not exist.
404MissingParameter.ResourceIdsThe parameter - ResourceIds.N should not be null.-
404MissingParameter.TagOwnerUidThe parameter - TagOwnerUid should not be null.-
404MissingParameter.TagOwnerBidThe parameter - TagOwnerBid should not be null.-
404MissingParameter.ResourceTypeThe parameter - ResourceType should not be null.The ResourceType parameter is required.
404MissingParameter.TagsThe parameter - Tags should not be null.-
404MissingParameter.RegionIdThe parameter - RegionId should not be null.-
404InvalidResourceId.NotFoundThe specified ResourceIds are not found in our records.The specified resource does not exist. Check whether the ResourceId parameter is correct.
404InvalidResourceType.NotFoundThe ResourceType provided does not exist in our records.The specified resource type does not exist.
404InvalidRegionId.NotFoundThe specified RegionId does not exist.The specified region ID does not exist.
500ServiceUnavailableThe service is unavailable, please try again later.-
500InternalErrorThe process of creating snapshot has failed due to some unknown error.The snapshot cannot be created.

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
No change history