Updated on 2024-05-11 GMT+08:00

Querying Vault Resources

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.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

URI

POST /v3/{project_id}/vault/resource_instances/action

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

without_any_tag

No

Boolean

If this parameter is set to true, all resources without tags are queried. In this case, the tag, not_tags, tags_any, and not_tags_any fields are ignored.

tags

No

Array of TagsReq objects

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.

The response returns resources containing any 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.

If no tag filtering condition is specified, full data is returned.

tags_any

No

Array of TagsReq objects

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.

If no tag filtering condition is specified, full data is returned.

not_tags

No

Array of TagsReq objects

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.

If no tag filtering condition is specified, full data is returned.

not_tags_any

No

Array of TagsReq objects

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.

If no tag filtering condition is specified, full data is returned.

sys_tags

No

Array of SysTags objects

Only users with the op_service permission can use this field to filter resources.

Currently, TMS calls can only one tag structure.

key: _sys_enterprise_project_id

values: List of enterprise project IDs

Currently, key contains only one value. 0 indicates the default enterprise project.

sys_tags and tenant tag filtering conditions (tags, tags_any, not_tags, and not_tags_any) cannot be used at the same time.

If no sys_tags exists, use other tag APIs for filtering. If no tag filtering condition is specified, full data is returned.

This list cannot be an empty list.

limit

No

String

Query count. (This parameter is not displayed when 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 not within this range, an error will be reported. The number of returned records does not exceed the value of limit.

offset

No

String

Index position. (This parameter is not displayed when action is set to count.) If action is set to filter, the value defaults to 0 and the minimum value of offset is 0. The first record in the query result is the offset+1 record that meets the query criteria.

action

Yes

String

Operation identifier. Possible values are filter and count. The value filter indicates pagination query. The value count indicates that the total number of query results meeting the search criteria will be returned.

matches

No

Array of Match objects

Search criteria supported by resources

Keys in this list must be unique.

Only one key is supported currently. Multiple-key support will be available later.

Array Length: 0 - 1

cloud_type

No

String

Cloud type

Enumeration values:

  • public

  • hybrid

object_type

No

String

Resource type

Enumeration values:

  • server

  • disk

Table 3 TagsReq

Parameter

Mandatory

Type

Description

key

Yes

String

Key

It contains a maximum of 127 Unicode characters.

A tag key cannot be an empty string.

Spaces before and after a key will be deprecated.

values

Yes

Array of strings

List of values

The list can contain up to 10 values.

A tag value contains up to 255 Unicode 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.

The asterisk (*) is a reserved character in 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.

Table 4 SysTags

Parameter

Mandatory

Type

Description

key

Yes

String

Key Key of the system tag, which is obtained from the whitelist and cannot be defined randomly. Currently, only the _sys_enterprise_project_id field is supported, and the corresponding value indicates the enterprise project ID.

values

Yes

Array of strings

List of values Currently, only the enterprise project ID is used. The default enterprise project ID is 0.

Table 5 Match

Parameter

Mandatory

Type

Description

key

Yes

String

Key A key can only be set to resource_name, indicating the resource name.

value

Yes

String

Value A value consists of up to 255 characters If key is set to resource_name, an empty character string indicates exact match and any non-empty string indicates fuzzy match.

Response Parameters

Status code: 200

Table 6 Response body parameters

Parameter

Type

Description

resources

Array of TagResource objects

List of matched resources (This parameter is not displayed if action is set to count.)

total_count

Integer

Total number of matched resources

Table 7 TagResource

Parameter

Type

Description

resource_id

String

Resource ID

resource_detail

InstancesResourceDetail object

Resource details

tags

Array of Tag objects

Tag list If there is no tag, an empty array is used by default.

resource_name

String

Resource name

sys_tags

Array of SysTag objects

Only users with the op_service permission can obtain this field.

Currently, only resource_tag is included.

key: _sys_enterprise_project_id

value: enterprise project ID. Value 0 indicates the default enterprise project.

This field is not returned in the non-op_service scenario.

Table 8 InstancesResourceDetail

Parameter

Type

Description

vault

Vault object

Vaults

Table 9 Vault

Parameter

Type

Description

billing

Billing object

Operation info

description

String

User-defined vault description

Minimum: 0

Maximum: 255

id

String

Vault ID

name

String

Vault name

Minimum: 1

Maximum: 64

project_id

String

Project ID

provider_id

String

ID of the vault resource type

resources

Array of ResourceResp objects

Vault resources

tags

Array of Tag objects

Vault tags

enterprise_project_id

String

Enterprise project ID. Its default value is 0.

auto_bind

Boolean

Indicates whether automatic association is enabled. Its default value is false (not enabled).

bind_rules

VaultBindRules object

Association rule

user_id

String

User ID

created_at

String

Creation time, for example, 2020-02-05T10:38:34.209782

auto_expand

Boolean

Whether to enable auto capacity expansion for the vault. Only pay-per-use vaults support auto capacity expansion.

smn_notify

Boolean

Exception notification function

Default: true

threshold

Integer

Vault capacity threshold. If the vault capacity usage exceeds this threshold, an exception notification is sent.

Minimum: 1

Maximum: 100

Default: 80

sys_lock_source_service

String

Used to identify the SMB service. You can set it to SMB or leave it empty.

Minimum: 0

Maximum: 32

Enumeration values:

  • SMB

  • ''

Table 10 Billing

Parameter

Type

Description

allocated

Integer

Allocated capacity, in GB.

charging_mode

String

Billing mode, which can be post_paid (pay-per-use) or pre_paid (yearly/monthly). The default value is post_paid.

cloud_type

String

Cloud type, which can be public or hybrid

consistent_level

String

Vault specification, which can be crash_consistent (crash consistent backup) or app_consistent (application consistency backup)

object_type

String

Object type, which can be server, disk, turbo, workspace, vmware, rds, or file

order_id

String

Order ID

product_id

String

Product ID

protect_type

String

Protection type, which can be backup or replication

size

Integer

Capacity, in GB

Minimum: 1

Maximum: 10485760

spec_code

String

Specification codeServer backup vault: vault.backup.server.normal; Disk backup vault: vault.backup.volume.normal; File system backup vault: vault.backup.turbo.normal

status

String

Vault status

Enumeration values:

  • available

  • lock

  • frozen

  • deleting

  • error

storage_unit

String

Name of the bucket for the vault

used

Integer

Used capacity, in MB.

frozen_scene

String

Scenario when an account is frozen

is_multi_az

Boolean

Multi-AZ attribute of a vault

Default: false

Table 11 ResourceResp

Parameter

Type

Description

extra_info

ResourceExtraInfo object

Extra information of the resource

id

String

ID of the resource to be backed up

name

String

Name of the resource to be backed up

Minimum: 0

Maximum: 255

protect_status

String

Protection status

Enumeration values:

  • available

  • error

  • protecting

  • restoring

  • removing

size

Integer

Allocated capacity for the associated resource, in GB

type

String

Type of the resource to be backed up, which can be OS::Nova::Server, OS::Cinder::Volume, OS::Ironic::BareMetalServer, OS::Native::Server, OS::Sfs::Turbo, or OS::Workspace::DesktopV2

backup_size

Integer

Backup size

backup_count

Integer

Number of backups

Table 12 ResourceExtraInfo

Parameter

Type

Description

exclude_volumes

Array of strings

IDs of the disks that will not be backed up. This parameter is used when servers are added to a vault, which include all server disks. But some disks do not need to be backed up. Or in case that a server was previously added and some disks on this server do not need to be backed up.

Table 13 VaultBindRules

Parameter

Type

Description

tags

Array of BindRulesTags objects

Filters automatically associated resources by tag.

Minimum length: 0 characters

Maximum length: 5 characters

Array Length: 0 - 5

Table 14 BindRulesTags

Parameter

Type

Description

key

String

The key cannot contain non-printable ASCII characters (0–31) and the following characters: =*<>,|/

The key can contain only letters, digits, hyphens (-), and underscores (_).

value

String

The value cannot contain non-printable ASCII characters (0–31) and the following characters: =*<>,|/

The value can contain only letters, digits, periods (.), hyphens (-), and underscores (_).

Table 15 Tag

Parameter

Type

Description

key

String

Key

It can contain a maximum of 36 characters.

It cannot be an empty string.

Spaces before and after a key will be discarded.

It cannot contain non-printable ASCII characters (0–31) and the following characters: =*<>,|/

It can contain only letters, digits, hyphens (-), and underscores (_).

value

String

Value

It is mandatory when a tag is added and optional when a tag is deleted.

It can contain a maximum of 43 characters.

It can be an empty string.

Spaces before and after a value will be discarded.

It cannot contain non-printable ASCII characters (0–31) and the following characters: =*<>,|/

It can contain only letters, digits, hyphens (-), underscores (_), and periods (.).

Table 16 SysTag

Parameter

Type

Description

key

String

Key Key of the system tag, which is obtained from the whitelist and cannot be defined randomly. Currently, only the _sys_enterprise_project_id field is supported, and the corresponding value indicates the enterprise project ID.

value

String

Value Currently, only the enterprise project ID is used. The default enterprise project ID is 0.

Status code: 400

Table 17 Response body parameters

Parameter

Type

Description

error_code

String

For details, see Error Codes.

error_msg

String

Error message

Example Requests

Querying vault resources by tag

POST  https://{endpoint}/v3/{project_id}/vault/resource_instances/action

{
  "tags" : [ {
    "key" : "string",
    "values" : [ "vaule" ]
  } ],
  "action" : "filter"
}

Example Responses

Status code: 200

OK

{
  "total_count" : 7,
  "resources" : [ {
    "resource_id" : "e54f7854-8de8-4f98-acf1-65f330bfe877",
    "resource_name" : "vault-7698-api-test",
    "resource_detail" : {
      "vault" : {
        "id" : "e54f7854-8de8-4f98-acf1-65f330bfe877",
        "name" : "vault-7698-api-test",
        "resources" : [ ],
        "provider_id" : "0daac4c5-6707-4851-97ba-169e36266b66",
        "created_at" : "2023-04-21T08:20:43.022+00:00",
        "project_id" : "667230ba418f48f1996329f174693053",
        "enterprise_project_id" : 0,
        "auto_bind" : false,
        "bind_rules" : { },
        "auto_expand" : false,
        "smn_notify" : true,
        "threshold" : 80,
        "user_id" : "0ae13f012b80d2d81f11c0129285d34b",
        "billing" : {
          "allocated" : 0,
          "cloud_type" : "public",
          "consistent_level" : "crash_consistent",
          "charging_mode" : "pre_paid",
          "order_id" : "CS23042116192E6CZ",
          "product_id" : "00301-231151-0--0",
          "protect_type" : "backup",
          "object_type" : "server",
          "spec_code" : "vault.backup.server.normal",
          "used" : 0,
          "status" : "available",
          "size" : 100
        },
        "tags" : [ ]
      }
    },
    "tags" : [ ]
  } ]
}

Status Codes

Status Code

Description

200

OK

400

Bad Request

Error Codes

See Error Codes.