查询资源实例

接口说明

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

约束说明

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

URI

• URI格式

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

• URI样例

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

请求消息

• 参数说明

  表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文档中对应语言类型的【使用】目录下。

状态码

详情请参见状态码。

错误码

详情请参见错误码。