Querying Backup Resources by Tag¶
Function¶
This API is used to filter resources by tag.
Tag Management Service (TMS) uses this API to filter and list resources of each service by tag. These services must have the query capabilities.
URI¶
URI format
POST https://{endpoint}/v1/{project_id}/csbs_backup/resource_instances/action
Request header
Table 1 Request header¶ Parameter
Mandatory
Type
Description
Content-type
Yes
MIME type of the body in the request
application/json
X-Auth-Token
Yes
User token
-
Parameter description
Table 2 Parameter description¶ Parameter
Mandatory
Type
Description
project_id
Yes
String
Project ID
Request¶
Parameter description
Table 3 Parameter description¶ Parameter
Mandatory
Type
Description
tags
No
List<tag>
List of included tags. Backups with these tags will be filtered.
This list cannot be an empty list.
The list can contain up to 10 keys.
Keys in this list must be unique.
Keys in this list are in an AND relationship.
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 is in an OR relationship.
tags_any
No
List<tag>
List of tags. Backups with any tags in this list will be filtered.
This list cannot be an empty list.
The list can contain up to 10 keys.
Keys in this list must be unique.
The response returns resources containing any tags in this list. Keys in this list are in an OR relationship while values in each key-value structure is in an OR relationship.
not_tags
No
List<tag>
List of excluded tags. Backups without these tags will be filtered.
This list cannot be an empty list.
The list can contain up to 10 keys.
Keys in this list 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 is in an OR relationship.
not_tags_any
No
List<tag>
List of tags. Backups without any tags in this list will be filtered.
This list cannot be an empty list.
The list can contain up to 10 keys.
Keys in this list must be unique.
The response returns resources without any tags in this list. Keys in this list are in an OR relationship while values in each key-value structure is in an OR relationship.
limit
No
String
Query count (This parameter is not displayed if action is set to count.)
If action is set to filter, the value defaults to 1000. The value ranges from 1 to 1000. If you set a value out of this range, an error will be reported. The number of returned records does not exceed the value of limit.
offset
No
String
Query index (This parameter is not displayed if action is set to count.)
If action is set to filter, the value defaults to 0 (minimum value). The first record in the query result is the offset+1 record that meets the query criteria.
action
Yes
String
Operation type
Possible values are filter and count.
filter indicates pagination query and count indicates that a specified number of queried records will be returned.
matches
No
List<match>
List of query criteria supported by resources
This list cannot be an empty list.
Keys in this list must be unique.
Parameter description of field tag
Table 4 Parameter description of field tag¶ Parameter
Mandatory
Type
Description
key
Yes
String
Tag key
A tag key consists of up to 127 characters.
A tag key cannot be an empty string.
Spaces before and after a key will be deprecated.
values
Yes
List<String>
List of tag values
The list can contain up to 10 values.
A tag value consists of up to 255 characters.
Spaces before and after a key will be deprecated.
Values in this list must be unique.
Values in this list are in an OR relationship.
This list can be empty and each value can be an empty character string.
If this list is left blank, it indicates that all values are included.
Parameter description of field match
Table 5 Parameter description of field match¶ Parameter
Mandatory
Type
Description
key
Yes
String
Tag key
Possible values are:
resource_name: indicates the resource name.
value
Yes
String
Tag value
A tag value consists of up to 255 characters.
If key is set to resource_name, an empty character string indicates exact matching and any non-empty string indicates fuzzy matching.
Example request
POST https://{endpoint}/v1/{project_id}/csbs_backup/resource_instances/action
When action is set to filter:
{ "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" ] } ] }
When action is set to count:
{ "action": "count", "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" ] } ], "matches": [{ "key": "resource_name", "value": "resource1" } ] }
Response¶
Parameter description
Table 6 Parameter description¶ Parameter
Type
Description
resources
List<resource>
List of matched resources (This parameter is not displayed if action is set to count.)
total_count
Integer
Total number of matched resources
Parameter description of field resource
Table 7 Parameter description of field resource¶ Parameter
Type
Description
resource_id
String
Resource ID
resource_detail
Object
Resource details
Backup details, including tags
tags
List<resource_tag>
Tag list
resource_name
String
Resource name
Parameter description of field resource_detail
Table 8 Parameter description of field resource_detail¶ Parameter
Type
Description
checkpoint_id
String
Backup record ID
created_at
String
Creation time, for example, 2017-04-18T01:21:52.701973
extend_info
Dict
Extension information
id
String
Backup ID
name
String
Backup name
resource_id
String
Backup object ID
status
String
Backup status
Value range: waiting_protect, protecting, available, waiting_restore, restoring, error, waiting_delete, deleting, and deleted
updated_at
String
Modification time, for example, 2017-04-18T01:21:52.701973
backup_data
Dict
VM metadata
description
string
Backup description
tags
List<resource_tag>
Tag list
resource_type
String
Backup object type
Parameter description of field extend_info
Table 9 Parameter description of field extend_info¶ Parameter
Type
Description
auto_trigger
Boolean
Whether automatic trigger is enabled
average_speed
Integer
Average speed
copy_from
String
This parameter is left blank by default.
copy_status
String
This parameter is left blank by default.
fail_code
fail_code
Error code
fail_op
String
Type of the failed operation
Enum: [backup, restore, delete, verify, copy]
fail_reason
String
Description of the failure cause
image_type
String
Backup type
incremental
Boolean
Whether incremental backup is used
progress
Integer
Backup progress. The value is an integer ranging from 0 to 100.
resource_az
String
AZ to which the backup resource belongs
resource_name
String
Backup object name
resource_type
String
Backup object type
size
Integer
Backup capacity
space_saving_ratio
Integer
Space saving rate
volume_backups
List<volume_backup>
Disk backup list
finished_at
String
Backup completion time, for example, 2017-04-18T01:21:52.701973
supported_restore_mode
String
Restoration mode. Possible values are na, snapshot, and backup.
snapshot: Data is restored from snapshots of the disks of the server.
backup: Data is restored from backups of the disks of the server.
na: Restoration is not supported.
tags
List<resource_tag>
Tag list
Parameter description of field backup_data
Table 10 Parameter description of field backup_data¶ Parameter
Type
Description
__openstack_region_name
String
Name of the AZ where the ECS resides
cloudservicetype
String
ECS type
disk
String
System disk size corresponding to the ECS specifications
imagetype
String
Image type. Possible values are gold (public image), private (private image), and market (market image).
Enum: [gold, private, market]
ram
String
Memory size of the ECS, in MB
vcpus
String
CPU cores corresponding to the ECS
eip
String
Elastic IP address of the ECS
private_ip
String
Internal IP address of the ECS
Parameter description of field image_data
Table 11 Parameter description of field image_data¶ Parameter
Type
Description
image_id
String
Image ID
Parameter description of field fail_code
Table 12 Parameter description of field fail_code¶ Parameter
Type
Description
Code
Long
Error code
Description
String
Error description
Parameter description of field volume_backup
Table 13 Parameter description of field volume_backup¶ Parameter
Type
Description
average_speed
Integer
Average speed
bootable
Boolean
Whether the disk functions as a system disk
id
String
Cinder backup ID
image_type
String
Backup set type
Enum:[ backup]
incremental
Boolean
Whether incremental backup is used
name
String
Disk backup name
size
Integer
Accumulated size (MB) of backups
source_volume_id
String
Source disk ID
source_volume_size
Integer
Source disk size in GB
space_saving_ratio
Integer
Space saving rate
status
String
Status
source_volume_name
String
Source disk name
snapshot_id
String
ID of the snapshot from which the backup is generated
Parameter description of field resource_tag
Table 14 Parameter description of field resource_tag¶ Parameter
Type
Description
key
String
Tag key
It consists of up to 36 characters.
It cannot be an empty string.
It can contain only letters, digits, hyphens (-), and underscores (_).
value
String
Tag value
It consists of up to 43 characters.
It can be an empty string.
It can contain only letters, digits, hyphens (-), and underscores (_).
Example response
When action is set to filter:
{ "status":"aviable", "backup_data":{ "eip":"", "cloudservicetype":"QEMU", "ram":1024, "__openstack_region_name":"", "vcpus":1, "private_ip":"", "disk":0, "imagetype":"gold" }, "periodic_type":null, "name":"manualbk_ea67", "resource_id":"58482e0b-a357-4125-bdad-102f796b0e0c", "created_at":"2020-02-11T06:34:43.897750", "checkpoint_id":"ee45c782-71f8-4265-8392-e31fc701836c", "replication_records":[ ], "updated_at":"2020-02-11T06:38:29.765609", "protected_at":"2020-02-11T06:30:26.000000", "tags":[ ], "extend_info":{ "auto_trigger":false, "finished_at":"2020-02-11T06:38:29.748932", "volume_backups":[ ], "incremental":true, "copy_from":null, "dec_size":0, "size":0, "resource_az":"br-iaas-odin1b", "copy_status":"na", "image_type":"backup", "average_speed":0, "taskid":"e9c97c75-59fa-4b99-8b4b-1dd991dbba33", "progress":8, "resource_type":"OS::Nova::Server" }, "progress":null, "expired_at":null, "id":"a6d04e0e-0121-41d1-8371-eaeab14482f8", "resource_type":"OS::Nova::Server", "description":"--" }
When action is set to count:
{ total_count": 1000 }
Status Codes¶
Normal
Status Code
Description
200
OK
Abnormal
Status Code
Description
400
Invalid parameters.
401
Authentication failed.
403
You do not have permission to perform this operation.
404
The requested resource was not found.
500
A system exception occurs.
Error Codes¶
For details, see Error Codes.