# 本地镜像列表查询 - ListImageLocal #### 功能介绍 本地镜像列表查询 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-hss2.0/hss_02_0007.html)。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-hss2.0/hss_02_0022.html)。 - 如果使用身份策略授权，当前API调用无需身份策略权限。 #### URI GET /v5/{project_id}/image/local-repositories 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释**: 项目ID，用于明确项目归属，配置后可通过该ID查询项目下资产。获取方式请参见[获取项目ID](https://support.huaweicloud.com/api-hss2.0/hss_02_0024.html)。 **约束限制**: 不涉及 **取值范围**: 字符长度1-256位 **默认取值**: 不涉及 | 表2Query参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | enterprise_project_id | 否 | String | **参数解释**: 企业项目ID，用于过滤不同企业项目下的资产。获取方式请参见[获取企业项目ID](https://support.huaweicloud.com/api-hss2.0/hss_02_0027.html)。 如需查询所有企业项目下的资产请传参"all_granted_eps"。 **约束限制**: 开通企业项目功能后才需要配置企业项目ID参数。 **取值范围**: 字符长度1-256位 **默认取值**: 0，表示默认企业项目（default）。 | | offset | 否 | Integer | **参数解释**: 偏移量：指定返回记录的开始位置 **约束限制**: 不涉及 **取值范围**: 最小值0，最大值2000000 **默认取值**: 默认为0 | | limit | 否 | Integer | **参数解释**: 每页显示个数 **约束限制**: 不涉及 **取值范围**: 取值10-200 **默认取值**: 10 | | image_name | 否 | String | **参数解释** 本地镜像的名称，用于模糊筛选指定名称的本地镜像列表 **约束限制** 支持部分匹配（如传入'web'可匹配所有名称含'web'的镜像），区分大小写 **取值范围** 字符长度1-256位，支持字母、数字、短横线、下划线、点号，禁止含@#$%等特殊字符 **默认取值** 无 | | image_version | 否 | String | **参数解释** 本地镜像的版本标识，用于筛选指定版本的本地镜像，需与image_name配合使用 **约束限制** 仅当指定image_name时传参有效，否则筛选条件不生效 **取值范围** 字符长度1-128位，支持字母、数字、短横线、下划线、点号、冒号 **默认取值** 无 | | scan_status | 否 | String | **参数解释** 本地镜像的安全扫描状态，用于筛选指定扫描状态的镜像列表 **约束限制** 取值必须在指定范围内，否则返回空结果，区分大小写 **取值范围** - unscan : 未扫描 - success : 扫描完成 - scanning : 扫描中 - failed : 扫描失败 - waiting_for_scan : 等待扫描 **默认取值** 无 | | local_image_type | 否 | String | **参数解释** 本地镜像的存储来源类型，用于筛选不同来源的本地镜像 **约束限制** 取值必须在指定范围内，否则返回空结果，区分大小写 **取值范围** - other_image : 非SWR镜像 - swr_image : SWR镜像 **默认取值** 无 | | image_size | 否 | Long | **参数解释** 本地镜像的大小（单位字节），用于筛选指定大小的镜像（精确匹配） **约束限制** 仅支持精确匹配，如需范围筛选需结合业务层处理 **取值范围** 取值0-9223372036854775807（约9EB） **默认取值** 无 | | start_latest_update_time | 否 | Long | **参数解释** 本地镜像版本最后更新时间的查询起始值（Unix时间戳，单位ms），与end_latest_update_time配合筛选时间范围 **时间格式** Unix时间戳（如1697509433000表示2023-10-16 10:23:53） **约束限制** 需与end_latest_update_time同时使用，且小于end_latest_update_time，否则筛选无效 **取值范围** 取值0-9223372036854775807 **默认取值** 无 | | end_latest_update_time | 否 | Long | **参数解释** 本地镜像版本最后更新时间的查询结束值（Unix时间戳，单位ms），与start_latest_update_time配合筛选时间范围 **时间格式** Unix时间戳（如1709973506292表示2024-03-08 15:18:26） **约束限制** 需与start_latest_update_time同时使用，且大于start_latest_update_time，否则筛选无效 **取值范围** 取值0-9223372036854775807 **默认取值** 无 | | start_latest_scan_time | 否 | Long | **参数解释** 本地镜像最近一次扫描完成时间的查询起始值（Unix时间戳，单位ms），与end_latest_scan_time配合筛选时间范围 **时间格式** Unix时间戳（精确到毫秒） **约束限制** 仅对scan_status为success的镜像有效，需与end_latest_scan_time同时使用 **取值范围** 取值0-9223372036854775807 **默认取值** 无 | | end_latest_scan_time | 否 | Long | **参数解释** 本地镜像最近一次扫描完成时间的查询结束值（Unix时间戳，单位ms），与start_latest_scan_time配合筛选时间范围 **时间格式** Unix时间戳（精确到毫秒） **约束限制** 仅对scan_status为success的镜像有效，且需大于start_latest_scan_time **取值范围** 取值0-9223372036854775807 **默认取值** 无 | | has_vul | 否 | Boolean | **参数解释** 用于筛选是否存在软件漏洞的本地镜像，true表示筛选有漏洞的镜像，false表示筛选无漏洞的镜像 **约束限制** 仅对scan_status为success的镜像有效，未扫描镜像不会被筛选 **取值范围** true（存在漏洞）、false（不存在漏洞） **默认取值** 无（不筛选漏洞状态） | | host_name | 否 | String | **参数解释** 本地镜像所关联的云服务器名称，用于筛选关联指定服务器的本地镜像 **约束限制** 支持模糊匹配，区分大小写，仅对关联了服务器的镜像有效 **取值范围** 字符长度1-64位，支持中文、英文、数字、短横线、下划线，禁止含特殊字符 **默认取值** 无 | | host_id | 否 | String | **参数解释** 本地镜像所关联的云服务器唯一标识（ECS实例ID），用于精准筛选关联指定服务器的本地镜像 **约束限制** 精确匹配，仅对关联了该服务器的镜像有效 **取值范围** 字符长度1-64位，支持字母、数字、短横线 **默认取值** 无 | | host_ip | 否 | String | **参数解释** 本地镜像所关联服务器的公网或私网IP地址，用于筛选关联指定IP服务器的本地镜像 **约束限制** 支持IPv4格式，精确匹配，多个IP需通过业务层分批查询 **取值范围** 符合IPv4格式的字符串（如 **默认取值** 无 | | container_id | 否 | String | **参数解释** 本地镜像所关联的容器唯一标识（Docker容器ID），用于精准筛选关联指定容器的本地镜像 **约束限制** 精确匹配，仅对关联了容器的镜像有效 **取值范围** 字符长度1-64位，支持字母、数字、短横线、下划线 **默认取值** 无 | | container_name | 否 | String | **参数解释** 本地镜像所关联的容器名称，用于筛选关联指定名称容器的本地镜像 **约束限制** 支持模糊匹配，区分大小写，仅对关联了容器的镜像有效 **取值范围** 字符长度1-64位，支持字母、数字、短横线、下划线、点号 **默认取值** 无 | | pod_id | 否 | String | **参数解释** 本地镜像所关联的Kubernetes Pod唯一标识，用于精准筛选关联指定Pod的本地镜像 **约束限制** 精确匹配，仅对K8s环境中关联了Pod的镜像有效 **取值范围** 字符长度1-64位，支持字母、数字、短横线 **默认取值** 无 | | pod_name | 否 | String | **参数解释** 本地镜像所关联的Kubernetes Pod名称，用于筛选关联指定名称Pod的本地镜像 **约束限制** 支持模糊匹配，区分大小写，仅对K8s环境中关联了Pod的镜像有效 **取值范围** 字符长度1-63位，支持字母、数字、短横线，不能以短横线开头或结尾 **默认取值** 无 | | app_name | 否 | String | **参数解释** 本地镜像中部署的应用软件名称（如Nginx、MySQL），用于筛选包含指定应用的本地镜像 **约束限制** 支持模糊匹配，区分大小写，仅对已识别应用的镜像有效 **取值范围** 字符长度1-64位，支持中文、英文、数字、短横线、下划线 **默认取值** 无 | | has_container | 否 | Boolean | **参数解释** 用于筛选是否关联了容器的本地镜像 **取值范围**: - true：关联容器的镜像 - false：未关联容器的镜像 **默认取值** 无（不筛选容器关联状态） | #### 请求参数 表3请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释**: 用户Token，包含了用户的身份、权限等信息，在调用API接口时，可通过Token进行身份认证。获取方式请参见[获取用户Token](https://support.huaweicloud.com/api-hss2.0/hss_02_0009.html)。 **约束限制**: 不涉及 **取值范围**: 字符长度1-32768位 **默认取值**: 不涉及 | #### 响应参数 **状态码：200** 表4响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | total_num | Integer | **参数解释** 符合所有筛选条件的本地镜像总记录数，用于分页计算总页数 **取值范围** 取值0-2147483647 | | data_list | Array of [ImageLocalInfo] objects | **参数解释** 包含查询到的本地镜像详情，每个元素对应一个本地镜像的完整信息 **取值范围** 数组长度0-limit（每页显示个数），元素结构符合ImageLocalInfo定义，数组为空表示无匹配结果 | 表5ImageLocalInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | image_name | String | **参数解释** 镜像名称 **取值范围** 字符长度0-256位 | | image_id | String | **参数解释** 本地镜像的唯一标识，用于后续查询镜像详情、执行扫描等操作 **取值范围** 字符长度1-64位，支持字母、数字、短横线，符合UUID格式 | | image_digest | String | **参数解释** 本地镜像的加密摘要（SHA-256算法），用于唯一标识镜像内容，避免篡改 **取值范围** 字符长度64-128位，以'sha256:'开头，后跟十六进制字符串（如sha256:ce0b5d91b072730d0bc9518f11efd07eb7fdb9f43251e11a96cab5b1918b7044） | | image_version | String | **参数解释** 镜像版本 **取值范围** 字符长度0-256位 | | local_image_type | String | **参数解释** 本地镜像的存储来源类型，标识镜像是否来自华为云SWR仓库 **取值范围** swr_image：华为云SWR仓库镜像 other_image：非SWR仓库镜像 | | scan_status | String | **参数解释** 本地镜像的安全扫描状态，反映当前镜像是否完成安全检测 **取值范围** 扫描状态，包含如下： - unscan：未扫描 - success：扫描完成 - scanning：正在扫描 - failed：扫描失败 - waiting：等待扫描 | | image_size | Long | **参数解释** 本地镜像的实际存储大小，单位为字节（B） **取值范围** 取值0-9223372036854775807（约9EB） | | latest_update_time | Long | **参数解释** 本地镜像版本的最后更新时间，即镜像创建或更新的时间戳 **取值范围** Unix时间戳（单位ms），取值0-9223372036854775807 | | latest_scan_time | Long | **参数解释** 本地镜像最近一次完成安全扫描的时间戳，未扫描时该字段可能为0或空 **取值范围** Unix时间戳（单位ms），取值0-9223372036854775807，未扫描时为0 | | vul_num | Long | **参数解释** 本地镜像中检测到的软件漏洞总数，包含高、中、低危漏洞 **取值范围** 取值0-9223372036854775807 | | unsafe_setting_num | Long | **参数解释** 本地镜像在安全基线扫描中未通过的检查项数量，反映镜像配置合规性 **取值范围** 取值0-9223372036854775807 | | malicious_file_num | Long | **参数解释** 本地镜像中检测到的恶意文件（如病毒、木马）总数 **取值范围** 取值0-9223372036854775807 | | host_num | Long | **参数解释** 当前本地镜像所关联的云服务器总数 **取值范围** 取值0-9223372036854775807 | | container_num | Long | **参数解释** 当前本地镜像所创建或关联的容器总数 **取值范围** 取值0-9223372036854775807 | | component_num | Long | **参数解释** 本地镜像中包含的软件组件（如依赖库、应用程序）总数 **取值范围** 取值0-9223372036854775807 | | scan_failed_desc | String | **参数解释** 当scan_status为failed时，该字段说明扫描失败的具体原因，未失败时为空字符串 **取值范围** - unknown_error：未知错误 - failed_to_match_agent：对应主机未开启容器版防护或agent离线 - create_container_failed：创建容器失败 - get_container_info_failed：获取容器信息失败 - docker_offline：docker引擎不在线 - get_docker_root_failed：获取容器根文件系统失败 - image_not_exist_or_docker_api_fault：镜像不存在或docker接口错误 - huge_image：超大镜像 - docker_root_in_nfs：容器根目录位于网络挂载 - response_timed_out：响应超时 | | severity_level | String | **参数解释** 根据镜像的漏洞、基线违规、恶意文件情况综合评定的风险等级 **取值范围** - Security：安全 - Low：低危 - Medium：中危 - High：高危 | | host_name | String | **参数解释** 应用防护事件所属云服务器的名称，用于标识事件来源主机 **取值范围** 字符长度1-64位，支持中文、英文、数字、短横线、下划线，符合华为云ECS命名规范 | | host_id | String | **参数解释**: 主机id **取值范围**: 字符长度1-128位 | | agent_id | String | **参数解释** 本地镜像所在服务器上安装的HSS Agent唯一标识，用于关联Agent相关操作 **取值范围** 字符长度1-128位，支持字母、数字、短横线、下划线 | | non_scan_reason | String | **参数解释** 说明本地镜像无法进行安全扫描的具体原因（如镜像格式不支持、权限不足等），为空表示支持扫描 **取值范围** 字符长度0-1024位，支持中文、英文、数字、常用标点符号 | #### 请求示例 查询前10条本地镜像信息列表 ``` GET https://{endpoint}/v5/{project_id}/image/local-repositories?offset=0&limit=10 ``` #### 响应示例 **状态码：200** 请求已成功 ``` { "data_list" : [ { "image_id" : "f757deea-781e-45ec-90ec-f199249890df", "image_name" : "webshell-ljx", "image_version" : "v1", "image_digest" : "sha256:ce0b5d91b072730d0bc9518f11efd07eb7fdb9f43251e11a96cab5b1918b7044", "local_image_type" : "swr_image", "scan_status" : "success", "image_size" : 215304488, "latest_update_time" : 1697509433000, "latest_scan_time" : 1709973506292, "host_num" : 0, "container_num" : 5, "component_num" : 146, "vul_num" : 77, "host_name" : "myhost", "host_id" : "9ad79426-992c-4be4-a2d1-dfd3a75b7c14", "agent_id" : "1c1d073c5fc403eb0d9c3088bc49da4e015586fd4864513a2fd81afedce282d4", "severity_level" : "High" } ], "total_num" : 1 } ``` #### SDK代码示例 SDK代码示例如下。 - [Java] ``` package com.huaweicloud.sdk.test; import com.huaweicloud.sdk.core.auth.ICredential; import com.huaweicloud.sdk.core.auth.BasicCredentials; import com.huaweicloud.sdk.core.exception.ConnectionException; import com.huaweicloud.sdk.core.exception.RequestTimeoutException; import com.huaweicloud.sdk.core.exception.ServiceResponseException; import com.huaweicloud.sdk.hss.v5.region.HssRegion; import com.huaweicloud.sdk.hss.v5.*; import com.huaweicloud.sdk.hss.v5.model.*; public class ListImageLocalSolution { public static void main(String[] args) { // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security. // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment String ak = System.getenv("CLOUD_SDK_AK"); String sk = System.getenv("CLOUD_SDK_SK"); String projectId = "{project_id}"; ICredential auth = new BasicCredentials() .withProjectId(projectId) .withAk(ak) .withSk(sk); HssClient client = HssClient.newBuilder() .withCredential(auth) .withRegion(HssRegion.valueOf("")) .build(); ListImageLocalRequest request = new ListImageLocalRequest(); try { ListImageLocalResponse response = client.listImageLocal(request); System.out.println(response.toString()); } catch (ConnectionException e) { e.printStackTrace(); } catch (RequestTimeoutException e) { e.printStackTrace(); } catch (ServiceResponseException e) { e.printStackTrace(); System.out.println(e.getHttpStatusCode()); System.out.println(e.getRequestId()); System.out.println(e.getErrorCode()); System.out.println(e.getErrorMsg()); } } } ``` - [Python] ``` # coding: utf-8 import os from huaweicloudsdkcore.auth.credentials import BasicCredentials from huaweicloudsdkhss.v5.region.hss_region import HssRegion from huaweicloudsdkcore.exceptions import exceptions from huaweicloudsdkhss.v5 import * if __name__ == "__main__": # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security. # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment ak = os.environ["CLOUD_SDK_AK"] sk = os.environ["CLOUD_SDK_SK"] projectId = "{project_id}" credentials = BasicCredentials(ak, sk, projectId) client = HssClient.new_builder() \ .with_credentials(credentials) \ .with_region(HssRegion.value_of("")) \ .build() try: request = ListImageLocalRequest() response = client.list_image_local(request) print(response) except exceptions.ClientRequestException as e: print(e.status_code) print(e.request_id) print(e.error_code) print(e.error_msg) ``` - [Go] ``` package main import ( "fmt" "github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic" hss "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/hss/v5" "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/hss/v5/model" region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/hss/v5/region" ) func main() { // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security. // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment ak := os.Getenv("CLOUD_SDK_AK") sk := os.Getenv("CLOUD_SDK_SK") projectId := "{project_id}" auth, err := basic.NewCredentialsBuilder(). WithAk(ak). WithSk(sk). WithProjectId(projectId). SafeBuild() if err != nil { fmt.Println(err) return } hcClient, err := hss.HssClientBuilder(). WithRegion(region.ValueOf("")). WithCredential(auth). SafeBuild() if err != nil { fmt.Println(err) return } client := hss.NewHssClient(hcClient) request := &model.ListImageLocalRequest{} response, err := client.ListImageLocal(request) if err == nil { fmt.Printf("%+v\n", response) } else { fmt.Println(err) } } ``` - [更多] 更多编程语言的SDK代码示例，请参见[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/HSS/sdk?api=ListImageLocal&version=v5)的代码示例页签，可生成自动对应的SDK代码示例。 #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 请求已成功 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-hss2.0/ErrorCode.html)。