查看镜像列表

说明：

当前页面接口为旧版 API，未来可能停止维护，目前不展示在左侧导航。云服务器 API 3.0 版本接口定义更加规范，访问时延下降显著，建议使用 云服务器 API 3.0。

1. 接口描述

本接口(DescribeImages) 用于查看镜像列表。
接口请求域名：image.api.qcloud.com

• 可以通过指定镜像 ID 来查询指定镜像的详细信息，或通过设定过滤器来查询满足过滤条件的镜像的详细信息。
• 指定偏移(Offset)和限制(Limit)来选择结果中的一部分，默认返回满足条件的前20个镜像信息。

2. 输入参数

以下请求参数列表仅列出了接口请求参数，其它参数可参考 公共请求参数。

参数名称	类型	是否必选	描述
Version	String	是	表示API版本号，主要用于标识请求的不同 API 版本。 本接口第一版本可传：2017-03-12。
ImageIds.N	array of Strings	否	镜像 ID 列表 。镜像 ID 如：img-gvbnzy6f。array型参数的格式可以参考 API 简介。镜像 ID 可以通过如下方式获取： 通过 DescribeImages 接口返回的ImageId获取。 通过 镜像控制台 获取。
Filters.N	array of Filter objects	否	过滤条件，详见下表-镜像过滤条件表。其中 Filters 的上限为10，Filters.Values 的上限为5。 注意：不可以同时指定 ImageIds 和 Filters。可选值包括 image-id, image-type。
Offset	Integer	否	偏移量，默认为0。
Limit	Integer	否	数量限制，默认为20，最大值为100。

镜像过滤条件表

参数名称	类型	描述
image-id	String	(过滤条件)，按镜像 ID 过滤，形如img-gvbnzy6f。
image-type	String	(过滤条件)，按镜像类型过滤。
image-name	String	(过滤条件)，按镜像名称过滤。

3. 输出参数

参数名称	类型	描述
RequestId	String	唯一请求 ID。每次请求都会返回一个唯一的 RequestId，当客户调用接口失败需要后台研发人员处理时需提供该 RequestId。
ImageSet	array of Images	一个关于镜像详细信息的结构体，主要包括镜像的主要状态与属性。
TotalCount	Integer	符合要求的镜像数量。

4. 错误码

以下错误码表仅列出了该接口的业务逻辑错误码，更多错误码详见 公共错误码。

错误码	描述
InvalidFilter	无效的过滤器。
InvalidParameter.InvalidParameterCoexistImageIdsFilters	不能同时指定ImageIds和Filters。
InvalidParameterValue.InvalidParameterValueLimit	参数值错误。

5. 示例

示例1

按镜像 ID 查询镜像：已经知道镜像ID，查询镜像相关信息

请求参数

https://image.api.qcloud.com/v2/index.php?Action=DescribeImages
&Version=2017-03-12
&ImageIds.0=img-pmqg1cw7
&<公共请求参数>

返回参数

{
    "Response": {
        "ImageSet": [
            {
                "ImageId": "img-pmqg1cw7",
                "ImageOsName": "centos6.6x86_32",
                "ImageType": "PUBLIC_IMAGE",
                "ImageCreateTime": "1970-01-01T00:00:00+00:00",
                "ImageStatus": "NORMAL",
                "ImageName": "CentOS 6.6 32位",
                "ImageDescription": "CentOS 6.6 32位",
                "Platform": "CentOS",
                "Architecture": "x86_64",
                "Creator": "PUBLIC"
            }
        ],
        "TotalCount": 1,
        "RequestID": "5920380e-277a-420a-a221-0caac3eb7159"
    }
}

示例2

按镜像类型查询镜像：查询账户下所有私有镜像。

请求参数

https://image.api.qcloud.com/v2/index.php?Action=DescribeImages
&Version=2017-03-12
&Filters.1.Name=image-type
&Filters.1.Values.1=PRIVATE_IMAGE
&<公共请求参数>

返回参数

{
    "Response": {
        "ImageSet": [
            {
                "ImageId": "img-pmqg1cw7",
                "ImageOsName": "centos6.6x86_32",
                "ImageType": "PUBLIC_IMAGE",
                "ImageCreateTime": "1970-01-01T00:00:00+00:00",
                "ImageStatus": "NORMAL",
                "ImageName": "CentOS 6.6 32位",
                "ImageDescription": "CentOS 6.6 32位",
                "Platform": "CentOS",
                "Architecture": "x86_64",
                "Creator": "PUBLIC"
            }
        ],
        "TotalCount": 1,
        "RequestID": "5920380e-277a-420a-a221-0caac3eb7159"
    }
}