ListTagResources - Elastic Compute Service - Alibaba Cloud Documentation Center

Description

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. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters


Parameter	Type	Required	Example	Description
Action	String	Yes	ListTagResources	The operation that you want to perform. Set the value to ListTagResources.
RegionId	String	Yes	cn-hangzhou	The region ID of the resource. You can call the DescribeRegions operation to query the most recent region list.
NextToken	String	No	caeba0bbb2be03f84eb48b699f0a4883	The token that is required for the next query.
ResourceType	String	Yes	instance	The type of the resource. Valid values: instance: ECS instance disk: disk snapshot: snapshot image: image securitygroup: security group volume: storage volume eni: elastic network interface (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
ResourceId.N	String	No	i-bp1j6qtvdm8w0z1o****	The ID of resource N. Valid values of N: 1 to 50.
Tag.N.Key	String	No	TestKey	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 `Tag.1.Key` to `acs:rm:rgId` and `Tag.1.Value` to the ID of a resource group. If you set `Tag.1.Key` to `acs:rm:rgId`, you must set `Tag.1.Value` to the ID of a non-default resource group. If you set Tag.1.Value to the ID of the default resource group, an error message is returned. If you set `Tag.1.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 resource tags at the same time, an error message is returned.
Tag.N.Value	String	No	TestValue	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 Tag.1.Key is set to `acs:rm:rgId`, you can set Tag.1.Value only to the ID of a non-default resource group.
TagFilter.N.TagValues.N	String	No	TestTagFilter	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`.
TagFilter.N.TagKey	String	No	env	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 up to 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 consisting 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 of 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.

Response parameters


Parameter	Type	Example	Description
NextToken	String	caeba0bbb2be03f84eb48b699f0a4883	The token that is required for the next query.
RequestId	String	484256DA-D816-44D2-9D86-B6EE4D5BA78C	The ID of the request.
TagResources	Array of TagResource		Details about resources and tags, including resource IDs, resource types, and tag key-value pairs.
TagResource
TagValue	String	TestValue	The value of the tag.
ResourceType	String	instance	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
ResourceId	String	i-bp1j6qtvdm8w0z1o****	The ID of the resource.
TagKey	String	TestKey	The key of the tag.

Examples

Sample requests

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

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<ListTagResourcesResponse>
    <TagResources>
        <TagResource>
            <ResourceType>instance</ResourceType>
            <TagValue>TestValue</TagValue>
            <ResourceId>i-bp1j6qtvdm8w0z1o****</ResourceId>
            <TagKey>TestKey</TagKey>
        </TagResource>
    </TagResources>
    <RequestId>DE65F6B7-7566-4802-9007-96F2494AC512</RequestId>
</ListTagResourcesResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

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

Error codes


HTTP status code	Error code	Error message	Description
400	InvalidDefaultResourceGroup.NotSupported	The specified parameter Tag is not support for default resource group.	The error message returned because queries of the default resource group are not supported.
400	InvalidTag.NotSupported	You can only specify Tag for either resource tag or resource group.	The error message returned because resource groups and resource tags cannot be queried at the same time.
400	Duplicate.TagKey	The Tag.N.Key contain duplicate key.	The error message returned because the specified tag key already exists. Tag keys must be unique.
400	InvalidTagKey.Malformed	The specified Tag.n.Key is not valid.	The error message returned because the specified 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 parameter 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 that can be added to the instance has been reached.
400	InvalidTag.Mismatch	The specified Tag.n.Key and Tag.n.Value are not match.	The error message returned because the specified Tag.N.Key parameter does not correspond to the specified 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.
400	Invalid.Scope	The specified scope is invalid.	The error message returned because the specified Scope parameter is invalid.
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 specify the Scope parameter.
403	InvalidResourceId.NotSupported	The specified ResourceId does not support tagging.	The error message returned because the specified resource does not support tagging.
403	NoPermission.Tag	The operator is not permission for the tag.	The error message returned because you are not authorized to manage the tag.
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 TagOwnerUid parameter is not specified.
404	MissingParameter.TagOwnerBid	The parameter - TagOwnerBid should not be null	The error message returned because the TagOwnerBid parameter is not specified.
404	MissingParameter.Tags	The parameter - Tags should not be null	The error message returned because the tag-related parameters are not specified.
404	MissingParameter.RegionId	The parameter - RegionId should not be null	The error message returned because the RegionId parameter is not specified.
404	InvalidResourceId.NotFound	The specified ResourceIds are not found in our records.	The error message returned because the specified ResourceId parameter does not exist. Check whether the resource ID is correct.
404	InvalidResourceType.NotFound	The ResourceType provided does not exist in our records.	The error message returned because the specified ResourceType parameter does not exist.
404	InvalidRegionId.NotFound	The specified RegionId does not exist.	The error message returned because the specified region ID does not exist.

For a list of error codes, see Service error codes.