按标签查询镜像

功能介绍

该接口用于按标签或其他条件对镜像进行过滤或者计数使用。

约束与限制

为兼容遗留数据，使用tags、not_tags、tags_any、not_tags_any参数时，不对查询条件中标签的key、value进行字符集校验。

URI

POST /v2/{project_id}/images/resource_instances/action

请求消息

• 请求参数

  参数	是否必选	参数类型	描述
  action	是	String	操作标识（区分大小写），支持filter、count。filter就是分页查询；count是只需按照条件将总条数返回即可。
  tags	否	Array of objects	包含标签，最多包含10个key，每个key对应的values最多包含10个值，且key和values都不能重复。不能为空列表。 详情请参见表2。
  tags_any	否	Array of objects	包含任意标签，最多包含10个key，每个key对应的values最多包含10个值，且key和values都不能重复。不允许为空列表，但可以不传递参数。 详情请参见表3。
  not_tags	否	Array of objects	不包含标签，最多包含10个key，每个key对应的values最多包含10个值，且key和values都不能重复。不能为空列表。 详情请参见表4。
  not_tags_any	否	Array of objects	不包含任意标签，最多包含10个key，每个key对应的values最多包含10个值，且key和values都不能重复。不能为空列表。 详情请参见表5。
  without_any_tag	否	Boolean	不包含任意一个标签，该字段为true时查询所有不带标签的资源，此时忽略tag、not_tags、tags_any、not_tags_any字段。
  limit	否	String	最大查询记录数（action为count时，此参数无效）。如果action为filter，则limit默认为10，最多为1000，不能为负数，最小值为1。
  offset	否	String	索引位置， 从offset指定的下一条数据开始查询。 查询第一页数据时，不需要传入此参数（action为count时，此参数无效），如果action为filter，offset默认为0，不能为负数。
  matches	否	Array of objects	搜索字段，key为要匹配的字段，如resource_name、resource_id等。value为匹配的值。多个matches的key不允许重复。不允许为空列表，但可以不传递参数。 详情请参见表6。

  表2 tags字段数据结构说明

  参数	是否必选	参数类型	描述
  key	是	String	标签的键。最大长度127个unicode字符，key不能为空。
  values	是	Array of strings	标签的值列表。每个值最大长度255个unicode字符，如果values为空列表，则标签的值可以是任意值。值列表中的值之间为或的关系。

  表3 tags_any字段数据结构说明

  参数	是否必选	参数类型	描述
  key	是	String	标签的键。最大长度127个unicode字符，key不能为空。
  values	是	Array of strings	标签的值列表。每个值最大长度255个unicode字符，如果values为空列表，则标签的值可以是任意值。值列表中的值之间为或的关系。

  表4 not_tags字段数据结构说明

  参数	是否必选	参数类型	描述
  key	是	String	标签的键。最大长度127个unicode字符，key不能为空。
  values	是	Array of strings	标签的值列表。每个值最大长度255个unicode字符，如果values为空列表，则标签的值可以是任意值。值列表中的值之间为或的关系。

  表5 not_tags_any字段数据结构说明

  参数	是否必选	参数类型	描述
  key	是	String	标签的键。最大长度127个unicode字符，key不能为空。
  values	是	Array of strings	标签的值列表。每个值最大长度255个unicode字符，如果values为空列表，则标签的值可以是任意值。值列表中的值之间为或的关系。

  表6 matches字段数据结构说明

  参数	是否必选	参数类型	描述
  key	是	String	搜索的字段名称。合法值为resource_name、resource_id。 当字段名称为resource_name时，如果value为空字符串，做精确查询，否则按镜像名称全模糊查询。当字段名称为resource_id时，按镜像ID精确查询。
  value	是	String	搜索的字段名称的对应值，不允许为空。每个值最大长度255个unicode字符。

请求示例

• 按照标签和总条数返回查询条件，查询镜像。

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

  POST https://{Endpoint}/v2/fd73a4a14a4a4dfb9771a8475e5198ea/images/resource_instances/action { "action": "count", "matches": [{ "key": "resource_name", "value": "test100" }], "tags": [ { "key": "key3", "values": ["valueXX"] }], "tags_any": [ { "key": "key0", "values": ["valueXX"] }], "not_tags": [ { "key": "key9", "values": ["value9"] }], "not_tags_any": [{ "key": "key7", "values": ["value7"] }] }

• 按照标签和分页查询条件，查询镜像。

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29

  POST https://{Endpoint}/v2/fd73a4a14a4a4dfb9771a8475e5198ea/images/resource_instances/action { "action": "filter", "limit": "1", "offset": "0", "matches": [{ "key": "resource_name", "value": "test100" }], "tags": [ { "key": "key3", "values": ["valueXX"] }], "tags_any": [ { "key": "key0", "values": ["valueXX"] }], "not_tags": [ { "key": "key9", "values": ["value9"] }], "not_tags_any": [{ "key": "key7", "values": ["value7"] }] }

响应消息

• 响应参数

  参数	参数类型	描述
  resources	Array of resource objects	镜像信息列表
  total_count	Integer	总记录数

  表7 resource字段数据结构说明

  参数	参数类型	描述
  resource_id	String	镜像ID
  resource_detail	ResourceDetail object	镜像详情
  tags	Array of Tags objects	镜像的标签列表
  resource_name	String	镜像名称

  表8 ResourceDetail object

  名称	类型	必选	描述
  status	string	是	镜像状态

  表9 resource_tag字段数据结构说明

  参数	参数类型	描述
  key	String	标签的键
  value	String	标签的值

• 响应样例
  • action为count时的响应示例

    STATUS CODE 200

    1 2 3

    { "total_count": 36 }

  • action为filter时的响应示例

    STATUS CODE 200

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48

    { "total_count": 36, "resources": [{ "resource_name": "test10002", "resource_detail": {"status": "active"}, "tags": [{ "value": "value4", "key": "key4" }, { "value": "valueXX", "key": "key3" }, { "value": "value2", "key": "key2" }, { "value": "value5", "key": "key5" }, { "value": "value8", "key": "key8" }, { "value": "valueXX", "key": "key6" }, { "value": "valueXX", "key": "key0" }, { "value": "value1", "key": "key1" }, { "value": "value7", "key": "key7" }, { "value": "valueXX", "key": "key9" }], "resource_id": "8693187d-1590-4f9f-ae34-eb9e3037cf68" }] }

返回值

• 正常

  200

• 异常

  返回值	说明
  400 Bad Request	请求错误。
  401 Unauthorized	鉴权失败。
  403 Forbidden	没有操作权限。
  404 Not Found	找不到资源。
  500 Internal Server Error	服务内部错误。
  503 Service Unavailable	服务不可用。