查询资源实例

功能介绍

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

接口约束

一个文档数据库实例具有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
  }

状态码

详情请参见状态码。

错误码

详情请参见错误码。