# 按标签查询镜像 - ListImageByTags #### 功能介绍 该接口用于按标签或其他条件对镜像进行过滤或者计数使用。 #### 约束与限制 为兼容遗留数据，使用tags、not_tags、tags_any、not_tags_any参数时，不对查询条件中标签的key、value进行字符集校验。 #### 调试 您可以在[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/doc?locale=zh-cn&consoleCurrentProductId=ims&consoleCurrentProductshort=&product=IMS&api=ListImageByTags)中调试该接口。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-ims/ims_03_appendix_03.html)。 #### URI POST /v2/{project_id}/images/resource_instances/action 参数说明请参见[表1]。 表1参数说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | 项目ID | #### 请求消息 - 请求参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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]。 | 表2tags字段数据结构说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | 标签的键。最大长度128个unicode字符，key不能为空。 | | values | 是 | Array of strings | 标签的值列表。每个值最大长度255个unicode字符，如果values为空列表，则标签的值可以是任意值。值列表中的值之间为或的关系。 | 表3tags_any字段数据结构说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | 标签的键。最大长度128个unicode字符，key不能为空。 | | values | 是 | Array of strings | 标签的值列表。每个值最大长度255个unicode字符，如果values为空列表，则标签的值可以是任意值。值列表中的值之间为或的关系。 | 表4not_tags字段数据结构说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | 标签的键。最大长度128个unicode字符，key不能为空。 | | values | 是 | Array of strings | 标签的值列表。每个值最大长度255个unicode字符，如果values为空列表，则标签的值可以是任意值。值列表中的值之间为或的关系。 | 表5not_tags_any字段数据结构说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | 标签的键。最大长度128个unicode字符，key不能为空。 | | values | 是 | Array of strings | 标签的值列表。每个值最大长度255个unicode字符，如果values为空列表，则标签的值可以是任意值。值列表中的值之间为或的关系。 | 表6matches字段数据结构说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | 搜索的字段名称。 约束限制： 当字段名称为resource_name时，如果value为空字符串，做精确查询，否则按镜像名称全模糊查询。当字段名称为resource_id时，按镜像ID精确查询。 取值范围： resource_name：镜像名称 resource_id：镜像ID | | value | 是 | String | 搜索的字段名称的对应值，不允许为空。每个值最大长度255个unicode字符。 | #### 请求示例 - 按照标签和总条数返回查询条件，查询镜像。 ``` 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"] }] } ``` - 按照标签和分页查询条件，查询镜像。 ``` 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 | 总记录数 | 表7resource字段数据结构说明 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | resource_id | String | 镜像ID | | resource_detail | [ResourceDetail] object | 镜像详情 | | tags | Array of [Tags] objects | 镜像的标签列表 | | resource_name | String | 镜像名称 | 表8ResourceDetail object | 名称 | 类型 | 必选 | 描述 | |:---|:---|:---|:---| | status | string | 是 | 镜像状态。 取值范围： - queued：表示镜像元数据已经创建成功，等待上传镜像文件。 - saving：表示镜像正在上传文件到后端存储。 - deleted：表示镜像已经删除。 - killed：表示镜像上传错误。 - active：表示镜像可以正常使用。 | 表9resource_tag字段数据结构说明 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | key | String | 标签的键 | | value | String | 标签的值 | - 响应样例 - action为count时的响应示例 ``` STATUS CODE 200 ``` ``` { "total_count": 36 } ``` - action为filter时的响应示例 ``` STATUS CODE 200 ``` ``` { "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 | 服务不可用。 |