本地镜像列表查询 - ListImageLocal

功能介绍

本地镜像列表查询

调用方法

请参见如何调用API。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

如果使用角色与策略授权，具体权限要求请参见权限和授权项。
如果使用身份策略授权，当前API调用无需身份策略权限。

URI

GET /v5/{project_id}/image/local-repositories

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	参数解释: 项目ID，用于明确项目归属，配置后可通过该ID查询项目下资产。获取方式请参见获取项目ID。约束限制: 不涉及取值范围: 字符长度1-256位默认取值: 不涉及

表2 Query参数
参数	是否必选	参数类型	描述
enterprise_project_id	否	String	参数解释: 企业项目ID，用于过滤不同企业项目下的资产。获取方式请参见获取企业项目ID。如需查询所有企业项目下的资产请传参“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。约束限制: 不涉及取值范围: 字符长度1-32768位默认取值: 不涉及

响应参数

状态码：200

表4 响应Body参数
参数	参数类型	描述
total_num	Integer	参数解释符合所有筛选条件的本地镜像总记录数，用于分页计算总页数取值范围取值0-2147483647
data_list	Array of ImageLocalInfo objects	参数解释包含查询到的本地镜像详情，每个元素对应一个本地镜像的完整信息取值范围数组长度0-limit（每页显示个数），元素结构符合ImageLocalInfo定义，数组为空表示无匹配结果

表5 ImageLocalInfo
参数	参数类型	描述
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代码示例如下。

 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("<YOUR REGION>"))
                .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());
        }
    }
}
 

 # 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("<YOUR REGION>")) \
        .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)
 

 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 := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        WithProjectId(projectId).
        Build()

    client := hss.NewHssClient(
        hss.HssClientBuilder().
            WithRegion(region.ValueOf("<YOUR REGION>")).
            WithCredential(auth).
            Build())

    request := &model.ListImageLocalRequest{}
	response, err := client.ListImageLocal(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}
 