更新时间:2023-11-24 GMT+08:00

查询资源实例

接口说明

根据标签查询指定的数据库实例。

约束说明

一个文档数据库实例具有20个标签配额,且标签key唯一。

URI

  • URI格式

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

  • URI样例

    https://dds.ap-southeast-1.myhuaweicloud.com/v3/0549b4a43100d4f32f51c01c2fe4acdb/instances/action

表1 请求参数

名称

类型

IN

是否必选

描述

X-Auth-Token

string

header

从IAM服务获取的用户Token。请参考认证鉴权

project_id

string

path

租户在某一Region下的项目ID。请参考获取项目ID章节获取项目编号。

请求消息

  • 参数说明
    表2 参数说明

    名称

    参数类型

    是否必选

    描述

    offset

    String

    索引位置偏移量,表示从第一条数据偏移offset条数据后开始查询。

    • “action”值为“count”时,不传该参数。
    • “action”值为“filter”时,取值必须为数字,不能为负数。默认取0值,表示从第一条数据开始查询。

    limit

    String

    查询记录数。

    • “action”值为“count”时,不传该参数。
    • “action”值为“filter”时,取值范围:1~100。不传该参数时,默认查询前100条实例信息。

    action

    String

    操作标识。

    • 取值为“filter”,表示根据标签过滤条件查询实例。
    • 取值为“count”,表示仅返回总记录数,禁止返回其他字段。

    matches

    Array of objects

    搜索字段。

    • 该字段值为空,表示不按照实例名称或实例ID查询。
    • 该字段值不为空,具体值请参见表4

    tags

    Array of objects

    包含标签,最多包含20个key。详情请参见表3

    表3 tags字段数据结构说明

    名称

    参数类型

    是否必选

    描述

    key

    String

    标签键。

    • key不能为空,长度1~128个半角字符。
    • 可用 UTF-8 格式表示的字母(包含中文)、数字和空格,以及以下字符: _ . : / = + - @。
    • _sys_开头属于系统标签,租户不能输入。
    说明:

    搜索时不对该参数做字符集校验。

    values

    Array of strings

    标签值列表。

    • 可用 UTF-8 格式表示的字母(包含中文)、数字和空格,以及以下字符: _ . : / = + - @。
    • 可以为空(empty or null),长度0~255个半角字符。

    如果values为空列表,则表示查询任意value。value之间为或的关系。

    表4 matches字段数据结构说明

    名称

    参数类型

    是否必选

    描述

    key

    String

    取值为“instance_name”或“instance_id”,分别表示按实例名称或按实例ID匹配查询。

    value

    String

    待匹配的实例名称或实例ID,可以调用“查询实例列表”接口获取。如果未申请实例,可以调用“创建实例”接口创建。

请求示例

  • 根据标签,按实例名称查询1~100条指定实例信息
    {
      "offset": "100",
      "limit": "100",
      "action": "filter",
      "matches": [
        {
          "key": "instance_name",
          "value": "test-single"
        }
      ],
      "tags": [
        {
          "key": "key1",
          "values": [
            "value1",
            "value2"
          ]
        }
      ]
    }
  • 按照实例名称或按实例ID查询总记录数
    {
      "action": "count",
      "tags": [
        {
          "key": "key1",
          "values": [
            "value1",
            "value2"
          ]
        },
        {
          "key": "key2",
          "values": [
            "value1",
            "value2"
          ]
        }
      ],
      "matches": [
        {
          "key": "instance_name",
          "value": "test-single"
        },
         {
          "key": "instance_id",
          "value": "958693039f284d6ebfb177375711072ein02"
        }
      ]
    }

响应消息

  • 参数说明
    表5 参数说明

    名称

    参数类型

    描述

    instances

    Array of objects

    实例列表。详情请参见表6

    total_count

    Integer

    总记录数。

    表6 instance字段数据结构说明

    名称

    参数类型

    描述

    instance_id

    String

    实例ID,可以调用“查询实例列表”接口获取。如果未申请实例,可以调用“创建实例”接口创建。

    instance_name

    String

    实例名称。

    tags

    Array of objects

    标签列表。如果没有标签,默认为空数组。详情请参见表7

    表7 tags字段数据结构说明

    名称

    参数类型

    描述

    key

    String

    标签键。

    • key不能为空,长度1~128个半角字符。
    • 可用 UTF-8 格式表示的字母(包含中文)、数字和空格,以及以下字符: _ . : / = + - @。
    • _sys_开头属于系统标签,租户不能输入。

    字符集:0-9,A-Z,a-z,“_”,“-”,中文。

    value

    String

    标签值。

    • 可用 UTF-8 格式表示的字母(包含中文)、数字和空格,以及以下字符: _ . : / = + - @。
    • 可以为空(empty or null),长度0~255个半角字符。

    字符集:0-9,A-Z,a-z,“_”,“.”,“-”,中文。

  • 响应示例

    根据标签返回指定实例:

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

    返回总记录数:

    {
      "total_count": 4
    }

SDK

单击文档数据库服务 DDS SDK,下载SDK或查看SDK文档。SDK的安装、认证方式等在SDK文档中对应语言类型的【使用】目录下。

状态码

详情请参见状态码

错误码

详情请参见错误码