更新时间:2022-08-17 GMT+08:00

查询资源实例

功能介绍

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

接口约束

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

URI

  • URI格式

    POST /v3/{project_id}/instances/action

  • 参数说明
    表1 参数说明

    名称

    是否必选

    描述

    project_id

    租户在某一region下的project 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

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

    表3 tags字段数据结构说明

    名称

    是否必选

    参数类型

    描述

    key

    String

    标签键。最大长度36个unicode字符,key不能为空或者空字符串,不能为空格,校验和使用之前先排除前后半角空格。

    说明:

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

    values

    Array of strings

    标签值列表。最大长度43个unicode字符,不能为空格,校验和使用之前先排除前后半角空格。

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

    表4 matches字段数据结构说明

    名称

    是否必选

    参数类型

    描述

    key

    String

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

    value

    String

    待匹配的实例名称或实例ID。

  • 请求头
    POST https://DDS的Endpoint/v3/{project_id}/instances/action
  • 请求体样例

    根据标签查询指定实例:

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

响应消息

  • 要素说明
    表5 要素说明

    名称

    参数类型

    描述

    instances

    Array of objects

    实例列表。

    total_count

    Integer

    总记录数。

    表6 instance字段数据结构说明

    名称

    参数类型

    描述

    instance_id

    String

    实例ID。

    instance_name

    String

    实例名称。

    tags

    Array of objects

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

    表7 tags字段数据结构说明

    名称

    参数类型

    描述

    key

    String

    标签键。最大长度36个unicode字符,key不能为空。

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

    value

    String

    标签值。最大长度43个unicode字符,可以为空字符串。

    字符集: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
    }

状态码

详情请参见状态码

错误码

详情请参见错误码