Querying Protected Instances by Tag¶
Function¶
This API is used to query protected instances by tag.
URI¶
URI format
POST /v1/{project_id}/protected-instances/resource_instances/action
Parameter description
Parameter
Mandatory
Type
Description
project_id
Yes
String
Specifies the project ID.
Request¶
Parameter description
Parameter
Mandatory
Type
Description
offset
No
String
Specifies the index position. This parameter is unavailable when action is set to count. If offset 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 offset value must be a number and cannot be a negative number.
limit
No
String
Specifies the number of limited queries. This parameter is unavailable when action is set to count. The default value is 1000 when action is set to filter. The maximum value is 1000, and the minimum value is 1. The value cannot be a negative number.
action
Yes
String
Specifies the operation to be performed. The value can be filter (filtering) or count (querying the total number).
If action is set to filter, the query is performed based on the filter conditions. If action is set to count, only the total number of records is returned.
matches
No
Array of objects
Specifies the search field. The tag key is the field to be matched, for example, resource_name. The tag value indicates the value to be matched. The key is a fixed dictionary value and cannot contain duplicate keys or unsupported keys.
Determine whether fuzzy match is required based on the keys. For example, if key is resource_name, fuzzy search (case insensitive) is used by default. If value is an empty string, exact match is used. Currently, only resource_name for key is supported. Other key values will be available later.
For details, see Table 2.
not_tags
No
Array of objects
The resources to be queried do not contain tags listed in not_tags. Each resource to be queried contains a maximum of 20 keys. Each tag key can have a maximum of 20 tag values. The tag value corresponding to each tag key can be an empty array but the structure cannot be missing. Each tag key must be unique, and each tag value in a tag must be unique. The response returns resources containing no tags in this list. Keys in this list are in an AND relationship while values in each key-value structure are in an OR relationship. If no tag filtering condition is specified, full data is returned.
For details, see Table 1.
tags
No
Array of objects
The resources to be queried contain tags listed in tags. Each resource to be queried contains a maximum of 20 keys. Each tag key can have a maximum of 20 tag values. The tag value corresponding to each tag key can be an empty array but the structure cannot be missing. Each tag key must be unique, and each tag value in a tag must be unique. The response returns resources containing all tags in this list. Keys in this list are in an AND relationship while values in each key-value structure are in an OR relationship. If no tag filtering condition is specified, full data is returned.
For details, see Table 1.
tags_any
No
Array of objects
The resources to be queried contain any tags listed in tags_any. Each resource to be queried contains a maximum of 20 keys. Each tag key can have a maximum of 20 tag values. The tag value corresponding to each tag key can be an empty array but the structure cannot be missing. Each tag key must be unique, and each tag value in a tag must be unique. The response returns resources containing the tags in this list. Keys in this list are in an OR relationship and values in each key-value structure are also in an OR relationship. If no tag filtering condition is specified, full data is returned.
For details, see Table 1.
not_tags_any
No
Array of objects
The resources to be queried do not contain any tags listed in not_tags_any. Each resource to be queried contains a maximum of 20 keys. Each tag key can have a maximum of 20 tag values. The tag value corresponding to each tag key can be an empty array but the structure cannot be missing. Each tag key must be unique, and each tag value in a tag must be unique. The response returns resources containing no tags in this list. Keys in this list are in an OR relationship and values in each key-value structure are also in an OR relationship. If no tag filtering condition is specified, full data is returned.
For details, see Table 1.
Table 1 tag field description¶ Parameter
Mandatory
Type
Description
key
Yes
String
Specifies the tag key. It contains a maximum of 127 Unicode characters. It cannot be left blank. key cannot be empty, an empty string, or spaces. Before using key, delete spaces of single-byte character (SBC) before and after the value.
values
Yes
Array of strings
Lists the tag values. Each value contains a maximum of 255 Unicode characters. Before using values, delete SBC spaces before and after the value.
The asterisk (
*
) is reserved for the system. If the value starts with *, it indicates that fuzzy match is performed based on the value following *. The value cannot contain only asterisks (*
).If the values are null, it indicates any_value (querying any value). The resources containing one or more values listed in values will be found and displayed.
Table 2 Description of the match field¶ Parameter
Mandatory
Type
Description
key
Yes
String
Specifies the tag key.
Currently, only resource_name for key is supported. Other key values will be available later.
value
Yes
String
Specifies the tag value.
Each value can contain a maximum of 255 Unicode characters.
Sample request when action is set to filter
POST https://{Endpoint}/v1/{project_id}/protected-instances/resource_instances/action
{ "offset": "100", "limit": "100", "action": "filter", "matches": [ { "key": "resource_name", "value": "resource1" } ], "not_tags": [ { "key": "key1", "values": [ "*value1", "value2" ] } ], "tags": [ { "key": "key1", "values": [ "*value1", "value2" ] } ], "tags_any": [ { "key": "key1", "values": [ "value1", "value2" ] } ], "not_tags_any": [ { "key": "key1", "values": [ "value1", "value2" ] } ] }
Sample request when action is set to count
POST https://{Endpoint}/v1/{project_id}/protected-instances/resource_instances/action
{ "action": "count", "not_tags": [ { "key": "key1", "values": [ "value1", "*value2" ] } ], "tags": [ { "key": "key1", "values": [ "value1", "value2" ] }, { "key": "key2", "values": [ "value1", "value2" ] } ], "tags_any": [ { "key": "key1", "values": [ "value1", "value2" ] } ], "not_tags_any": [ { "key": "key1", "values": [ "value1", "value2" ] } ], "matches": [ { "key": "resource_name", "value": "resource1" } ] }
Response¶
Parameter description
Parameter
Mandatory
Type
Description
resources
Yes
Array of objects
Specifies the returned protected instances.
For details, see Table 3.
total_count
Yes
Integer
Specifies the total number of resources.
The value is not affected by the filtering criteria.
Table 3 Description of field resource¶ Parameter
Mandatory
Type
Description
resource_id
Yes
String
Specifies the ID of a protected instance.
resource_name
Yes
String
Specifies the protected instance name. This parameter is left blank by default if there is no name.
resource_detail
Yes
Object
Specifies the details of a protected instance.
For details, see Table 4.
tags
Yes
Array of objects
Specifies the tag list. If there is no tag in the list, tags is taken as an empty array.
For details, see Table 8.
Table 4 protected_instances field description¶ Parameter
Type
Description
id
String
Specifies the ID of a protected instance.
name
String
Specifies the name of a protected instance.
description
String
Specifies the description of a protected instance.
server_group_id
String
Specifies the ID of a protection group.
status
String
Specifies the status of a protected instance.
For details, see Protected Instance Status.
progress
Integer
Specifies the synchronization progress of a protected instance.
Unit: %
source_server
String
Specifies the production site server ID.
target_server
String
Specifies the DR site server ID.
created_at
String
Specifies the time when a protected instance was created.
The default format is as follows: "yyyy-MM-dd HH:mm:ss.SSS", for example, 2019-04-01 12:00:00.000.
updated_at
String
Specifies the time when a protected instance was updated.
The default format is as follows: "yyyy-MM-dd HH:mm:ss.SSS", for example, 2019-04-01 12:00:00.000.
priority_station
String
Specifies the current production site AZ of the protection group containing the protected instance.
source: indicates that the current production site AZ is the source_availability_zone value.
target: indicates that the current production site AZ is the target_availability_zone value.
attachment
Array of objects
Specifies the attached replication pairs.
For details, see Table 2.
tags
Array of objects
Specifies the tag list.
For details, see Table 3.
metadata
Object
Specifies the metadata of a protected instance.
For details, see Table 4.
Table 5 attachment field description¶ Parameter
Type
Description
replication
String
Specifies the ID of a replication pair.
device
String
Specifies the device name.
Table 6 tags field description¶ Parameter
Type
Description
key
String
Specifies the tag key.
value
String
Specifies the tag value.
Table 7 Field metadata description¶ Parameter
Type
Description
__system__frozen
String
Specifies whether the resource is frozen.
true: indicates that the resource is frozen.
Empty: indicates that the resource is not frozen.
Table 8 resource_tag field description¶ Parameter
Mandatory
Type
Description
key
Yes
String
Specifies the tag key. The tag key of a resource must be unique.
value
Yes
String
Specifies the value.
Example response
Example response when action is set to filter
{ "resources": [ { "resource_id": "d5a00c87-6b82-414a-a09e-59c37fff44d0", "resource_name": "Protected-Instance-c801", "resource_detail": { "id": "d5a00c87-6b82-414a-a09e-59c37fff44d0", "name": "Protected-Instance-c801", "description": null, "server_group_id": "525fbd01-d4d1-44fc-b341-6d734bcce245", "status": "protected", "progress": 100, "source_server": "73aff1d7-48d2-494e-a9f1-a7d3ffad31ff", "target_server": "0f6bc56b-a3bb-4707-a4fb-ccd4db5fac59", "created_at": "2019-05-28 08:17:50.066", "updated_at": "2019-05-30 01:40:00.74", "priority_station": "source", "attachment": [ { "replication": "42e2016e-b96e-4f75-aa57-1377a9cb45e4", "device": "/dev/vda" } ], "tags": [ { "key": "GH1111113fffffKdddddd", "value": "aaappppppppddddddd" } ], "metadata": {} }, "tags": [ { "key": "GH1111113fffffKdddddd", "value": "aaappppppppddddddd" } ] } ], "total_count": 1 }
Example response when action is set to count
{ "total_count": 1000 }
Returned Value¶
Normal
Returned Value
Description
200
OK
Abnormal
Returned Value
Description
400
Invalid parameters.
401
Authentication failed.
403
Insufficient permission.
404
The requested resource was not found.
500
Internal service error.