You can call this operation to query the tags that have been bound to one or more ECS resources.

Description

  • Specify at least one parameter in the request to determine the query object: ResourceId.N, Tag.N (Tag.N.Key and Tag.N.Value), or TagFilter.N .
  • When you specify the following parameters, the returned results contain only ECS resources that meet both of the following conditions.
    • Tag.N and ResourceId.N
    • TagFilter.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. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
RegionId String Yes cn-hangzhou

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

ResourceType String Yes instance

The type of the resource. Valid values:

  • instance
  • disk
  • snapshot
  • image
  • securitygroup
  • volume
  • eni
  • ddh
  • keypair
  • launchtemplate
TagFilter.N.TagKey String Yes env

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

TagFilter.N is used for fuzzy match of ECS resources that are bound to specified tags. It consists of one key and one or more values. Fuzzy match may have a latency of two seconds. Only the fuzzy match that has less than or equal to 5,000 resources is supported.

  • When the tag key (TagFilter.N.TagKey) is used for fuzzy match of ECS resources, the tag value (TagFilter.N.TagValues.N) must be empty. For example, when you use the tag key environment for fuzzy match of ECS resources, you can set TagFilter.1.TagKey to env and TagFilter.1.TagValues must be empty.
  • When the tag value (TagFilter.N.TagValues.N) is used for fuzzy match of ECS resources, the tag key (TagFilter.N.TagKey) must be set to an exact value. For example, when you use the tag key env and tag value product for fuzzy match of ECS resources, you must set TagFilter.1.TagKey exactly to env, and set TagFilter.1.TagValues.1 to proc.
  • Only the ECS resources that belong to the intersection of the tag keys are returned.
  • The ECS resources that belong to the union of the tag keys are returned.
Note TagFilter.N and Tag.N cannot be used at the same time. Otherwise, an error message is returned.
Action String Yes ListTagResources

The operation that you want to perform. Set the value to ListTagResources.

NextToken String No caeba0bbb2be03f84eb48b699f0a4883

The token for the next query.

ResourceId.N RepeatList No i-bp1j6qtvdm8w0z1o0***

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

Tag.N.Key String No FinanceDept

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

Tag.N is used for exact match of ECS resources that are bound to specified tags. It consists of one key-value pair.

  • When you specify only Tag.N.Key, all resources that are associated with this tag key are returned.
  • When you specify only Tag.N.Value, the error InvalidParameter.TagValue is returned.
  • When you specify multiple tag key-value pairs at the same time, only ECS resources that match all tag key-value pairs can be found.
Tag.N.Value String No FinanceJoshua

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

TagFilter.N.TagValues.N RepeatList No product

The tag value that is used for fuzzy match of ECS resources. A tag value must be 1 to 128 characters in length. Valid values of N: 1 to 5.

Response parameters

Parameter Type Example Description
NextToken String caeba0bbb2be03f84eb48b699f0a4883

The token for the next query.

RequestId String DE65F6B7-7566-4802-9007-96F2494AC5XX

The ID of the request.

TagResources Array

A collection of resources and tags, including the resource ID, type, and tag key-value pair.

TagResource

A collection of resources and tags, including the resource ID, type, and tag key-value pair.

ResourceId String i-bp1j6qtvdm8w0z1o0***

The ID of the resource.

ResourceType String instance

The type of the resource.

TagKey String FinanceDept

The key of the tag.

TagValue String FinanceJoshua

The value of the tag.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=ListTagResources
&RegionId=cn-hangzhou
&ResourceType=instance
&ResourceId.1=i-bp1j6qtvdm8w0z1o0***
&<Common request parameters>

Sample success responses

XML format

<ListTagResourcesResponse>
	  <TagResources>
		    <TagResource>
			      <ResourceType>instance</ResourceType>
			      <TagValue>FinanceJoshua</TagValue>
			      <ResourceId>i-bp1j6qtvdm8w0z1o0***</ResourceId>
			      <TagKey>binary</TagKey>
		    </TagResource>
	  </TagResources>
	  <RequestId>DE65F6B7-7566-4802-9007-96F2494AC5XX</RequestId>
</ListTagResourcesResponse>

JSON format

{
	"TagResources":{
		"TagResource":[
			{
				"ResourceType":"instance",
				"TagValue":"FinanceJoshua",
				"ResourceId":"i-bp1j6qtvdm8w0z1o0***",
				"TagKey":"FinanceDept"
			}
		]
	},
	"RequestId":"DE65F6B7-7566-4802-9007-96F2494AC512"
}

Error codes

HTTP status code Error code Error message Description
404 InvalidRegionId.NotFound %s The error message returned because the specified region ID does not exist.
404 MissingParameter.TagOwnerUid The parameter - TagOwnerUid should not be null The error message returned because the user who owns the tag does not exist.
404 MissingParameter.TagOwnerBid The parameter - TagOwnerBid should not be null The error message returned because the channel to which the tag belongs does not exist.
404 MissingParameter.ResourceType The parameter - ResourceType should not be null The error message returned because the specified resource type does not exist.
404 MissingParameter.Tags The parameter - Tags should not be null The error message returned because the specified tag parameter does not exist.
404 MissingParameter.RegionId The parameter - RegionId should not be null The error message returned because the specified region parameter does not exist.
403 PermissionDenied.TagOwnerUid The specified operator not have permission to set TagOwnerUid value. The error message returned because you are not authorized to set the owner of the tag.
403 PermissionDenied.Scope The specified operator not have permission to set Scope value. The error message returned because you are not authorized to modify the value of the Scope parameter.
400 NumberExceed.ResourceIds The ResourceIds parameter's number is exceed , Valid : 50 The error message returned because the number of resource IDs has exceeded 50.
400 NumberExceed.Tags The Tags parameter's number is exceed , Valid : 20 The error message returned because the number of tags has exceeded 20.
400 Duplicate.TagKey The Tag.N.Key contain duplicate key. The error message returned because the specified tag key already exists.
404 InvalidResourceId.NotFound The specified ResourceIds are not found in our records. The error message returned because the specified resource does not exist.
404 InvalidResourceType.NotFound The ResourceType provided does not exist in our records. The error message returned because the specified resource type does not exist.
400 InvalidTagKey.Malformed The specified Tag.n.Key is not valid. The error message returned because the specified value of the Tag.N.Key parameter is invalid.
400 InvalidTagValue.Malformed The specified Tag.n.Value is not valid. The error message returned because the specified Tag.n.Value is invalid.
400 OperationDenied.QuotaExceed The quota of tags on resource is beyond permitted range. The error message returned because the maximum number of tags on the resource has been reached.
403 InvalidResourceId.NotSupported The specified ResourceId does not support tagging. The error message returned because the specified resource does not support tagging.
400 InvalidTag.Mismatch The specified Tag.n.Key and Tag.n.Value are not match. The error message returned because the specified value of the Tag.N.Key parameter does not correspond to that of the Tag.N.Value parameter.
400 InvalidTagCount The specified tags are beyond the permitted range. The error message returned because the number of specified tags exceeds the upper limit.
404 InvalidRegionId.NotFound The specified RegionId does not exist. The error message returned because the specified region ID does not exist.
400 Invalid.Scope The specified scope is invalid. The error message returned because the specified scope value is invalid.
403 NoPermission.Tag The operator is not permission for the tag. The error message returned because you are not authorized to manage the tag.

For a list of error codes, visit the API Error Center.