文档首页/文档数据库服务 DDS/API参考（联盟区域）/API v3（推荐）/标签管理/查询资源实例
更新时间：2026-01-07 GMT+08:00
查看PDF
分享

查询资源实例

接口说明

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

约束说明

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

URI

  • URI格式

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

表1 路径参数

名称

类型

IN

是否必选

描述

project_id

string

path

是

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

请求参数

表2 请求Header参数

名称

类型

IN

是否必选

描述

X-Auth-Token

string

header

是

用户Token。

表3 参数说明

名称

参数类型

是否必选

描述

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查询。
  • 该字段值不为空，具体值请参见表5。

tags

Array of objects

否

包含标签，最多包含10个key。详情请参见表4。

表4 tags字段数据结构说明

名称

参数类型

是否必选

描述

key

String

是

标签键。

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

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

values

Array of strings

是

标签值列表。

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

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

表5 matches字段数据结构说明

名称

参数类型

是否必选

描述

key

String

是

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

value

String

是

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

  • 请求示例

    根据标签查询指定实例：

    {
  "offset": "100",
  "limit": "100",
  "action": "filter",
  "matches": [
    {
      "key": "instance_name",
      "value": "test-single"
    }
  ],
  "tags": [
    {
      "key": "key1",
      "values": [
        "value1",
        "value2"
      ]
    }
  ]
}
    查询总记录数： 
    {
  "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"
    }
  ]
}

响应参数

表6 参数说明

名称

参数类型

描述

instances

Array of objects

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

total_count

Integer

总记录数。

表7 instance字段数据结构说明

名称

参数类型

描述

instance_id

String

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

instance_name

String

实例名称。

tags

Array of objects

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

表8 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
}

状态码

详情请参见状态码。

错误码

详情请参见错误码。

父主题：标签管理