Querying Resources
Function
This API is used to filter resources. TMS allows you to search for resources by tag. Query results will be displayed in a list. Up to 20 tags can be specified in parameters: tags, tags_any, not_tags, and not_tags_any.
Calling Method
For details, see Calling APIs.
URI
POST /v1/resource-manager/{resource_type}/resource-instances/filter
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
resource_type |
Yes |
String |
Resource type. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
limit |
No |
Integer |
Up to how many records can be queried. This parameter is not available when the action element is set to count. If action is set to filter, the default value is 1000. The maximum value is 1,000, and the minimum value is 1. Minimum: 1 Maximum: 1000 Default: 1000 |
offset |
No |
Integer |
Index position. This parameter is not available when the action element is set to count. If the offset element is set to N, the resource query starts from the N+1 piece of data. If action is set to filter, the value of offset is 0 by default, indicating that the query starts from the first piece of data. The offsset value must be a number and cannot be a negative number. Minimum: 0 Default: 0 |
Request Parameters
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
without_any_tag |
No |
Boolean |
Tags to be excluded.If this parameter is set to true, all resources that do not have the specified tags will be returned. If this parameter is set to false or is not specified, it does not take effect. Default: false |
tags |
No |
Array of Tag objects |
Specified tags. Up to 20 tag keys can be specified, and up to 20 values can be specified for each key. Each tag value can be an empty array, but the tag structure cannot be missing. Each tag key must be unique, and the values of the same key must be unique. Resources containing any of the specified tags will be returned. Keys in this list are in an AND relationship while values in each key-value structure is in an OR relationship.If no tag filtering condition is specified, full data is returned. |
matches |
No |
Array of Match objects |
Search field. A field contains a key (such as resource_name) and a value. Keys are predefined and must be unique and valid. Whether fuzzy or exact match is used is determined based on the filed key. For example, exact match is used for the field key resource_name. If the field value is an empty string, exact match is used. Since very few resources have an empty-string name, an empty list is returned. Exact match is used for the field key resource_id. Currently only resource_name is supported. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
key |
Yes |
String |
Tag key. A key can contain up to 128 Unicode characters and cannot be left blank. The system does not verify the character set of the key when searching for resources. The key element cannot be empty, an empty string, or spaces. Before using the key element, delete single-byte character (SBC) spaces before and after the value. Minimum: 1 Maximum: 128 |
values |
Yes |
Array of strings |
Tag values. A key can contain up to 255 Unicode characters. Before verifying or using the value element, delete single-byte character (SBC) spaces before and after the value. The value can be an empty array but cannot be left blank. If no value is specified, any values are supported. Values are in an Or relathionship. The system does not verify the character set of bvaluesb when searching for resources, but only verifies the length. Maximum: 255 Array Length: 0 - 20 |
Response Parameters
Status code: 200
Parameter |
Type |
Description |
---|---|---|
resources |
Array of ResourceResp objects |
Resource List |
total_count |
Integer |
The total number of records. |
Parameter |
Type |
Description |
---|---|---|
resource_id |
String |
Resource ID. |
resource_detail |
Object |
Resource details.The field is reserved for extension and defaults to an empty string. |
tags |
Array of ResourceTag objects |
Tags. If no tag is specified, this parameter is an empty array by default. |
resource_name |
String |
Resource name. If no resource is specified, this parameter is an empty array by default. For EIP, IPs will be returned. |
Parameter |
Type |
Description |
---|---|---|
key |
String |
Tag key. A tag key can contain up to 128 Unicode characters and must complay with the character set specifications in section 3.1. Minimum: 1 Maximum: 128 |
value |
String |
Tag value. A tag value can contain up to 255 Unicode characters and must comply with the character set specifications in section 3.2. Minimum: 0 Maximum: 255 |
Status code: 400
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Specifies the error code. |
error_msg |
String |
Specifies the error message. |
Status code: 401
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Specifies the error code. |
error_msg |
String |
Specifies the error message. |
Status code: 403
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Specifies the error code. |
error_msg |
String |
Specifies the error message. |
Status code: 404
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Specifies the error code. |
error_msg |
String |
Specifies the error message. |
Status code: 500
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Specifies the error code. |
error_msg |
String |
Specifies the error message. |
Example Requests
Querying Instances by Tag
POST https://{endpoint}/v1/resource-manager/{resource_type}/resource-instances/filter { "tags" : [ { "key" : "key1", "values" : [ "value1", "value2" ] }, { "key" : "key2", "values" : [ "value1", "value2" ] } ], "matches" : [ { "key" : "resource_name", "value" : "resource1" } ], "without_any_tag" : "false" }
Example Responses
Status code: 200
Succeeded.
{ "resources" : [ { "resource_detail" : "", "resource_id" : "cdfs_cefs_wesas_12_dsad", "resource_name" : "resouece1", "tags" : [ { "key" : "key1", "value" : "value1" } ] } ], "total_count" : 1000 }
SDK Sample Code
The SDK sample code is as follows.
Querying Instances by Tag
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 |
package com.huaweicloud.sdk.test; import com.huaweicloud.sdk.core.auth.ICredential; import com.huaweicloud.sdk.core.auth.GlobalCredentials; import com.huaweicloud.sdk.core.exception.ConnectionException; import com.huaweicloud.sdk.core.exception.RequestTimeoutException; import com.huaweicloud.sdk.core.exception.ServiceResponseException; import com.huaweicloud.sdk.config.v1.region.ConfigRegion; import com.huaweicloud.sdk.config.v1.*; import com.huaweicloud.sdk.config.v1.model.*; import java.util.List; import java.util.ArrayList; public class ListResourcesByTagSolution { public static void main(String[] args) { // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security. // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment String ak = System.getenv("CLOUD_SDK_AK"); String sk = System.getenv("CLOUD_SDK_SK"); ICredential auth = new GlobalCredentials() .withAk(ak) .withSk(sk); ConfigClient client = ConfigClient.newBuilder() .withCredential(auth) .withRegion(ConfigRegion.valueOf("<YOUR REGION>")) .build(); ListResourcesByTagRequest request = new ListResourcesByTagRequest(); request.withLimit(<limit>); request.withOffset(<offset>); ResourceInstancesReq body = new ResourceInstancesReq(); List<Match> listbodyMatches = new ArrayList<>(); listbodyMatches.add( new Match() .withKey(Match.KeyEnum.fromValue("resource_name")) .withValue("resource1") ); List<String> listTagsValues = new ArrayList<>(); listTagsValues.add("value1"); listTagsValues.add("value2"); List<String> listTagsValues1 = new ArrayList<>(); listTagsValues1.add("value1"); listTagsValues1.add("value2"); List<Tag> listbodyTags = new ArrayList<>(); listbodyTags.add( new Tag() .withKey("key1") .withValues(listTagsValues1) ); listbodyTags.add( new Tag() .withKey("key2") .withValues(listTagsValues) ); body.withMatches(listbodyMatches); body.withTags(listbodyTags); body.withWithoutAnyTag(false); request.withBody(body); try { ListResourcesByTagResponse response = client.listResourcesByTag(request); System.out.println(response.toString()); } catch (ConnectionException e) { e.printStackTrace(); } catch (RequestTimeoutException e) { e.printStackTrace(); } catch (ServiceResponseException e) { e.printStackTrace(); System.out.println(e.getHttpStatusCode()); System.out.println(e.getRequestId()); System.out.println(e.getErrorCode()); System.out.println(e.getErrorMsg()); } } } |
Querying Instances by Tag
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 |
# coding: utf-8 import os from huaweicloudsdkcore.auth.credentials import GlobalCredentials from huaweicloudsdkconfig.v1.region.config_region import ConfigRegion from huaweicloudsdkcore.exceptions import exceptions from huaweicloudsdkconfig.v1 import * if __name__ == "__main__": # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security. # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment ak = os.environ["CLOUD_SDK_AK"] sk = os.environ["CLOUD_SDK_SK"] credentials = GlobalCredentials(ak, sk) client = ConfigClient.new_builder() \ .with_credentials(credentials) \ .with_region(ConfigRegion.value_of("<YOUR REGION>")) \ .build() try: request = ListResourcesByTagRequest() request.limit = <limit> request.offset = <offset> listMatchesbody = [ Match( key="resource_name", value="resource1" ) ] listValuesTags = [ "value1", "value2" ] listValuesTags1 = [ "value1", "value2" ] listTagsbody = [ Tag( key="key1", values=listValuesTags1 ), Tag( key="key2", values=listValuesTags ) ] request.body = ResourceInstancesReq( matches=listMatchesbody, tags=listTagsbody, without_any_tag=False ) response = client.list_resources_by_tag(request) print(response) except exceptions.ClientRequestException as e: print(e.status_code) print(e.request_id) print(e.error_code) print(e.error_msg) |
Querying Instances by Tag
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 |
package main import ( "fmt" "github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/global" config "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/config/v1" "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/config/v1/model" region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/config/v1/region" ) func main() { // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security. // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment ak := os.Getenv("CLOUD_SDK_AK") sk := os.Getenv("CLOUD_SDK_SK") auth := global.NewCredentialsBuilder(). WithAk(ak). WithSk(sk). Build() client := config.NewConfigClient( config.ConfigClientBuilder(). WithRegion(region.ValueOf("<YOUR REGION>")). WithCredential(auth). Build()) request := &model.ListResourcesByTagRequest{} limitRequest:= int32(<limit>) request.Limit = &limitRequest offsetRequest:= int32(<offset>) request.Offset = &offsetRequest var listMatchesbody = []model.Match{ { Key: model.GetMatchKeyEnum().RESOURCE_NAME, Value: "resource1", }, } var listValuesTags = []string{ "value1", "value2", } var listValuesTags1 = []string{ "value1", "value2", } var listTagsbody = []model.Tag{ { Key: "key1", Values: listValuesTags1, }, { Key: "key2", Values: listValuesTags, }, } withoutAnyTagResourceInstancesReq:= false request.Body = &model.ResourceInstancesReq{ Matches: &listMatchesbody, Tags: &listTagsbody, WithoutAnyTag: &withoutAnyTagResourceInstancesReq, } response, err := client.ListResourcesByTag(request) if err == nil { fmt.Printf("%+v\n", response) } else { fmt.Println(err) } } |
For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.
Status Codes
Status Code |
Description |
---|---|
200 |
Succeeded. |
400 |
Invalid parameter. |
401 |
Unauthorized. |
403 |
Forbidden. |
404 |
Resources not found. |
500 |
Internal server error. |
Error Codes
See Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot