• Distributed Message Service

dms
  1. Help Center
  2. Distributed Message Service
  3. API Reference
  4. APIs for Managing Queue Tags
  5. Searching for Queues by Tag

Searching for Queues by Tag

Function

This API is used to search for queues by tag.

URI

URI format: POST /v1.0/{project_id}/queue/resource_instances/action

Table 1 Request header

Parameter

Description

Mandatory or Not

Example

Content-type

Indicates the MIME types of a request body.

Yes

application/json

X-Auth-Token

Indicates the user token.

Yes

-

Table 2 Parameter description

Parameter

Mandatory or Not

Type

Description

project_id

Yes

String

Indicates the ID of a project.

Example

 /v1.0/67c01b92944144a19d2da968ef34a912/queue/resource_instances/action

Request

Table 3 Parameter description

Parameter

Mandatory or Not

Type

Description

tags

No

Array

Indicates a tag list in which all tags are matched.

A maximum of 10 tag keys can be specified for each search operation. The tag key cannot be left blank or set to an empty string. Each tag key can have a maximum of 10 values.

Each tag key and each value of a tag key must be unique.

tags_any

No

Array

Indicates a tag list in which any tag is matched.

A maximum of 10 tag keys can be specified for each search operation. The tag key cannot be left blank or set to an empty string. Each tag key can have a maximum of 10 values.

Each tag key and each value of a tag key must be unique.

not_tags

No

Array

Indicates a tag list in which no tags are matched.

A maximum of 10 tag keys can be specified for each search operation. The tag key cannot be left blank or set to an empty string. Each tag key can have a maximum of 10 values.

Each tag key and each value of a tag key must be unique.

not_tags_any

No

Array

Indicates a tag list in which any tag is not matched.

A maximum of 10 tag keys are allowed in each search operation. The tag key cannot be left blank or set to an empty string. The structure is required. Each tag key can have a maximum of 10 values. Each tag key and each value of a tag key must be unique.

action

Yes

String

Indicates an operation.

count: queries only the total number of queues.

filter: queries the details about queues and tags.

When this parameter is set to filter, a search is performed by page. When this parameter is set to count, only the total number of queues is returned based on the search criteria.

limit

No

String

This parameter is valid only when action is set to filter.

This parameter indicates the number of matches in a single search operation.

Default value: 1000

Value range: 1–1000.

offset

No

String

This parameter is valid only when action is set to filter.

This parameter indicates the index position. The search starts from the next data record of the specified offset position.

This parameter is not required when data on the first page is queried.

Default value: 0

Value range: an integer that is greater than or equals to zero

matches

No

Array

Indicates a search criterion for fuzzy queue name match.

Table 4 tags parameter description

Parameter

Mandatory or Not

Type

Description

key

Yes

String

Indicates the tag key, which can contain a maximum of 127 Unicode characters

and cannot be left blank.

values

Yes

Array

Indicates a list of tag values. A tag value can contain a maximum of 255 Unicode characters.

If the value of this parameter is null, it indicates all the values.

All values of a tag key are in the OR relationship.

Table 5 matches parameter description

Parameter

Mandatory or Not

Type

Description

key

Yes

String

It must be resource_name.

value

Yes

String

Indicates a queue name for fuzzy match. The value can contain a maximum of 255 Unicode characters.

Example request

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"
      ]
},
{
      "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

Response parameters

Table 6 Parameter description

Parameter

Type

Description

resources

Array

Indicates the queue list.

By default, both resources and resource tags are sorted by the time when they are created.

total_count

Integer

Indicates the total number of records.

Table 7 resources parameter description

Parameter

Type

Description

resource_id

String

Indicates the queue ID.

resouce_detail

JSON object

Indicates resource details.

tags

Array

Indicates a tag list. This parameter is an empty array by default if there is no tag.

Resource tags are sorted by the time when they are created.

resource_name

String

Indicates the resource name. This parameter is an empty string by default if there is no resource name.

Table 8 tags parameter description

Parameter

Type

Description

key

String

Indicates the tag key, which can contain a maximum of 36 Unicode characters. It cannot be left blank, and cannot be left blank, and cannot contain nonprintable ASCII (0–31) characters and the following special characters: *<>\=

value

String

Indicates a tag value. A tag value can contain a maximum of 43 Unicode characters. It can be an empty string, but cannot contain the following characters: ASCII (0-31), equal signs (=), asterisks (*), left angle brackets (<), right angle brackets (>), backslashes (\), commas (,), vertical bars (|), and slashes (/).

Example response

When action is set to filter:

    { 
      "resources": [
         {
            "resource_detail": null, 
            "resource_id": "cdfs_cefs_wesas_12_dsad", 
            "resource_name": "resouece1", 
            "tags": [
                {
                   "key": "key1",
                   "value": "value1"
                },
                {
                   "key": "key2",
                   "value": "value1"
                }
             ]
         }
       ], 
      "total_count": 1000
}

When action is set to count:

{
    "total_count": 1000
}

Status Code

Status Code

Description

200

OK

400

Invalid parameter.

401

Authentication failed.

403

Insufficient permission.

404

No queue found.

500

System error.