Querying an Instance by Tag

Function

This API is used to query a specified instance by tag.

Constraints

• This API supports the following types of instances:
  • GeminiDB Cassandra
  • GeminiDB Mongo
  • GeminiDB Influx
  • GeminiDB Redis
• A maximum of 20 tags can be added to a DB instance. The tag key must be unique.

URI

• URI format

  POST https://{Endpoint}/v3/{project_id}/instances/resource_instances/action

• URI example

  https://gaussdb-nosql.ap-southeast-1.myhuaweicloud.com/v3/375d8d8fad1f43039e23d3b6c0f60a19/instances/resource_instances/action

• Required parameters

  Table 1 Parameter description

  Parameter	Mandatory	Description
  project_id	Yes	Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID.

Request Parameters

• Required parameters

  Table 2 Parameter description

  Parameter	Mandatory	Type	Description
  offset	No	String	Index position. The query starts from the next piece of data indexed by this parameter. If action is set to count, this parameter does not need to be transferred. If action is set to filter, the parameter value must be a positive integer. The default value is 0, indicating that the query starts from the first piece of data.
  limit	No	String	Number of records to be queried. If action is set to count, this parameter does not need to be transferred. If action is set to filter, the value ranges from 1 to 100. If this parameter is not transferred, the first 100 instances are queried by default.
  action	Yes	String	Operation identifier. If action is set to filter, instances are queried based on tag filters. If action is set to count, only the total number of records is returned.
  matches	No	Array of objects	Search parameter. If this parameter is not specified, the query is not based on the instance name or ID. If the parameter is specified, see parameter values in Table 4.
  tags	No	Array of objects	Included tags. Each tag contains up to 20 keys. For more information, see Table 3.

  Table 3 Data structure description of parameter tags

  Parameter	Mandatory	Type	Description
  key	Yes	String	Tag key. It can contain a maximum of 36 Unicode characters. The key value cannot be null, an empty string, or spaces. Before using key, delete spaces before and after the value. NOTE: The character set of this parameter is not verified during search.
  values	Yes	Array of strings	Tag values. Each tag value can contain a maximum of 43 Unicode characters and cannot contain spaces. Before using values, delete spaces before and after the value. If the values is not specified, any parameter value can be queried. All values are in the OR relationship.

  Table 4 Data structure description of parameter matches

  Parameter	Mandatory	Type	Description
  key	Yes	String	Query criteria. The value can be instance_name or instance_id, indicating that the query is based on the instance name or instance ID.
  value	Yes	String	Name or ID of the instance to be queried

• Example request body

  Querying an instance by tag:

  {
    "offset": "100",
    "limit": "100",
    "action": "filter",
    "matches": [
      {
        "key": "instance_name",
        "value": "test-af07"
      }
    ],
    "tags": [
      {
        "key": "key1",
        "values": [
          "value1",
          "value2"
        ]
      }
    ]
  }

  Querying the total number of records:

  {
    "action": "count",
    "tags": [
      {
        "key": "key1",
        "values": [
          "value1",
          "value2"
        ]
      },
      {
        "key": "key2",
        "values": [
          "value1",
          "value2"
        ]
      }
    ],
    "matches": [
      {
        "key": "instance_name",
        "value": "test-af07"
      },
       {
        "key": "instance_id",
        "value": "958693039f284d6ebfb177375711072ein06"
      }
    ]
  }

Response Parameters

• Normal response

  Table 5 Parameter description

  Parameter	Type	Description
  instances	Array of objects	All instances
  total_count	Integer	Total number of records

  Table 6 Data structure description of parameter instance

  Parameter	Type	Description
  instance_id	String	Instance ID
  instance_name	String	Instance name
  tags	Array of objects	All tags. If there are no tags, tags is taken as an empty array by default. For more information, see Table 7.

  Table 7 Data structure description of parameter tags

  Parameter	Type	Description
  key	String	Tag key. The tag key can contain a maximum of 36 Unicode characters and must be specified. It is case-sensitive and can contain digits, letters, underscores (_), and hyphens (-).
  value	String	Tag value. The tag value can contain a maximum of 43 Unicode characters and can be an empty string. It is case-sensitive and can contain digits, letters, underscores (_), periods (.), and hyphens (-).

• Example normal response

  Returning a specified instance by tag:

  {
    "instances": [
      {
        "instance_id": "2acbf2223caf3bac3c33c6153423c3ccin06",
        "instance_name": "test-single",
        "tags": [
          {
            "key": "key1",
            "value": "value1"
          },
          {
            "key": "key2",
            "value": "value1"
          }
        ]
      }
    ]
  }

  Returning total records:

  {
    "total_count": 4
  }

• Abnormal response

  For details, see Abnormal Request Results.

Status Codes

For more information, see Status Codes.

Error Codes

For more information, see Error Codes.