调用 DescribeImages 接口，查询镜像信息。 ## 请求说明调用该接口时，使用`TagFilters.N.Key`和`TagFilters.N.Values.N`查询到的镜像数量不能超过1000个。若超过1000个，请使用 [DesribeTags](https://www.volcengine.com/docs/6396/130888) 接口进行查询。 ## 调试 [去调试](https://api.volcengine.com/api-explorer/?action=DescribeImages&groupName=%E9%95%9C%E5%83%8F&serviceCode=ecs&version=2020-04-01) ## 请求参数下方仅列出该接口特有的请求参数和部分公共参数。更多信息请见[公共参数](https://www.volcengine.com/docs/6369/67268)。 **Action** string 必选 `示例值：DescribeImages` 要执行的操作，取值：DescribeImages。 **Version** string 必选 `示例值：2020-04-01` API的版本，取值：2020\-04\-01。 **ImageIds.N** string[] `可选` `示例值：ImageIds.1=image-3tksv4n6ay3vj0******& ImageIds.2=image-2asdv4n6ay3vj0******` 镜像的ID，最多支持100个ID。您可以调用[CreateImage](https://www.volcengine.com/docs/6396/132240)、[ImportImage](https://www.volcengine.com/docs/6396/120263)接口获取自定义镜像ID，或调用本接口查询获取。 * 参数 \- N：表示镜像ID的序号。 * 多个镜像ID之间用`&`分隔。 **ImageName** string `可选` `示例值：testImage` 镜像名称。 **InstanceTypeId** string `可选` `示例值：ecs.c1.xlarge` 实例的规格ID，传入本参数时，将返回该规格可用的镜像ID列表。 **IsLTS** boolean `可选` `示例值：false` 公共镜像是否长期维护。取值： * true：长期维护的公共镜像。 * false（默认）：本参数不生效。

说明

本参数仅传true时生效，表示查询长期维护的公共镜像；传false或不传值时，本参数不生效。

**IsSupportCloudInit** boolean `可选` `示例值：true` 镜像是否支持Cloud\-init。取值： * true：支持 * false：不支持 **MaxResults** integer `可选` `示例值：15` 分页查询时设置的每页行数。 * 取值范围：1 ~ 100 * 默认值：15 **NextToken** string `可选` `示例值：--` 分页查询凭证，用于标记分页的位置，初次调用该接口时无需设置。下次查询时，取值为上一次API调用返回的`NextToken`参数值。 **OsType** string `可选` `示例值：Linux` 操作系统类型。取值： * Linux * Windows **Platform** string `可选` `示例值：CentOS` 镜像操作系统的发行版本。取值： * CentOS * Debian * veLinux * Windows Server * Fedora * OpenSUSE * Ubuntu **ProjectName** string `可选` `示例值：default` 资源所属项目。 **Status.N** string[] `可选` `示例值：Status.1=available&Status.2=creating` 镜像状态，最多支持10个。若不配置本参数，默认仅返回`available`状态的镜像。取值： * available（默认）：可用 * creating：创建中 * error：错误

说明

参数 \- N：表示镜像状态的序号。

多个镜像状态之间用&分隔。

**TagFilters.N.Key** string[] `可选` `示例值：TagFilters.1.Key=k1` 镜像标签的标签键。参数 \- N：表示标签键的序号。 * 取值范围：1～10，多个标签键之间用&分隔。 * 不允许重复。 **TagFilters.N.Values.N** string[] `可选` `示例值：TagFilters.1.Values.1=v1&TagFilters.1.Values.2=v2` 镜像标签的标签值。 * 第一个N：表示标签键的序号，取值范围：1～10。 * 第二个N：表示标签值的序号，同一标签键最多支持同时查询3个标签值。取值范围：1～3。 * 多个标签值之间用&分隔。

说明

如果传入该参数，则必须先传入TagFilters.N.Key。

不传则表示查询同一标签键下的所有标签值。

传入空字符串时，表示查询标签值为空的标签。

**Visibility** string `可选` `示例值：public` 镜像的可见性。取值： * public：公共镜像 * private：自定义镜像 * shared：共享镜像 ## 返回参数下方仅列出本接口特有的返回参数。更多信息请参见[返回结构](https://www.volcengine.com/docs/6369/80336)。 **Images** object[] `示例值：--` 镜像信息。 **MarketplaceImageBillType** integer `示例值：1` 市场镜像支持的计费方式，取值： * `0`：仅支持按量计费 * `1`：仅支持包年包月 * `2`：同时支持包年包月和按量计费两种方式

说明

仅查询市场镜像时返回本参数。

**Architecture** string `示例值：amd64` 镜像的架构类型。取值： * amd64：x86计算 * arm64：ARM计算 **BootMode** string `示例值：UEFI` 镜像的启动模式。 **CreatedAt** string `示例值：2021-07-26T21:55:12+08:00` 镜像创建时间，需满足RFC3339格式。 **Description** string `示例值：testdescription` 镜像描述。 **DetectionResults** object `示例值：--` 镜像的检测结果。 **DetectionStatus** string `示例值：Finished` 镜像检测状态。取值： * Finished：表示已检测完成 * Processing：表示正在检测中 **Items** object[] `示例值：--` 镜像检测项详情。 **Name** string `示例值：Virtio1.1` 检测项名称。支持的检测项详情可查看[检测项说明](https://www.volcengine.com/docs/6396/1217560)。 **Result** string `示例值：Unsupported` 该检测项对应结果。 **RiskCode** string `示例值：Virtio110.NotInstalled` 风险描述码，详情可查看[检测项说明](https://www.volcengine.com/docs/6396/1217560)。 **RiskLevel** string `示例值：High` 风险等级，详情可查看[检测项说明](https://www.volcengine.com/docs/6396/1217560)。

说明

若该参数返回值为空，表示无风险。

**ImageId** string `示例值：image-3tksv4n6ay3vj******` 镜像ID。 **ImageName** string `示例值：testImage` 镜像名称。 **ImageOwnerId** string `示例值：210005****` 镜像所属的账号ID。

说明

该参数仅在查询共享镜像时生效。

**IsInstallRunCommandAgent** boolean `示例值：false` 镜像中是否安装了云助手Agent。取值： * true：已安装 * false：未安装

说明

该参数仅对公共镜像生效。

**IsLTS** boolean `示例值：true` 公共镜像是否长期维护。

说明

本参数仅对公共镜像生效，对自定义镜像无意义。

**IsSupportCloudInit** boolean `示例值：true` 镜像是否支持Cloud\-init。 **Kernel** string `示例值：3.10.0-1160.80.1.el7.x86_64` 镜像的内核版本。 **LicenseType** string `示例值：VolcanoEngine` 镜像许可证类型。取值： * VolcanoEngine：默认，根据您设置的`platform`，采用火山引擎官方渠道的许可证 * BYOL：自带许可证（BYOL） **OsName** string `示例值：CentOS 7.9 64 bit` 镜像操作系统的名称。 **OsType** string `示例值：Linux` 操作系统类型。 **Platform** string `示例值：CentOS` 镜像操作系统的发行版本。取值： * CentOS * Debian * veLinux * Windows Server * Fedora * OpenSUSE * Ubuntu **PlatformVersion** string `示例值：7.9` 镜像的发行版本。 **ProductCode** string `示例值：cm015022` 市场镜像的商品码。 **ProjectName** string `示例值：210005****` 资源所属项目。 **ShareStatus** string `示例值：HasShared` 镜像共享状态。取值： * HasShared：自定义镜像已被共享给其他用户 * 当自定义镜像未被共享或使用公共镜像时，`ShareStatus`返回为空 **Size** integer `示例值：40` 镜像大小，单位为GiB。 **Snapshots** object[] `示例值：--` 镜像关联快照的信息。 **Size** integer `示例值：8` 快照大小，单位为GiB。 **SnapshotId** string `示例值：vol-bp1s5fnvk4gn2tws0****` 快照ID。 **VolumeKind** string `示例值：system` 云盘种类，取值： * system：系统盘 * data：数据盘 **Status** string `示例值：available` 镜像的状态。 **Tags** object[] `示例值：--` 镜像的标签信息。 **Key** string `示例值：image-tag-key-1` 镜像的标签键。 **Value** string `示例值：image-tag-value-1` 镜像的标签值。 **UpdatedAt** string `示例值：2021-07-26T21:55:12+08:00` 镜像更新时间，需满足RFC3339格式。 **VirtualSize** double `示例值：42949672960` 镜像大小，单位为Byte。 **Visibility** string `示例值：public` 镜像的可见性。 **NextToken** string `示例值：bHpwdXJja2RxemU1eG5sb3NzdGcW1-RCEq******` 本次调用返回的查询凭证值，返回为空表示该页为末页。 ## 请求示例 ```text GET /?Action=DescribeImages&Version=2020-04-01&ImageId=image-ebgy1og99tfct0gw**** HTTP/1.1 Host: ecs.cn-beijing.volcengineapi.com Region: cn-beijing Service: ecs ``` ## 返回示例 ```json { "ResponseMetadata": { "RequestId": "20240306165859006BB5E*****", "Action": "DescribeImages", "Version": "2020-04-01", "Service": "ecs", "Region": "cn-beijing" }, "Result": { "Images": [ { "ImageId": "image-ebgy1og99tfct0gw****", "ImageName": "CentOS7.9-pal", "Description": "", "VirtualSize": 8589934592, "Size": 8, "OsType": "Linux", "Platform": "CentOS", "ReleaseVersion": "0", "Status": "available", "Visibility": "private", "Architecture": "amd64", "UpdatedAt": "2024-03-04T15:44:39+08:00", "CreatedAt": "2024-02-21T14:43:42+08:00", "OsName": "CentOS 7.9 64 bit", "PlatformVersion": "7.9", "ProductCode": "cm015022", "IsSupportCloudInit": true, "LicenseType": "VolcanoEngine", "ShareStatus": "", "ImageOwnerId": "", "ProjectName": "default", "Snapshots": [ { "SnapshotId": "snap-3vgp9debs*****", "Size": 8, "VolumeKind": "system" } ], "BootMode": "UEFI", "Tags": [], "IsLTS": true, "DetectionResults": { "DetectionStatus": "Processing", "Items": [] } } ], "NextToken": "" } } ``` ## 错误码下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见[公共错误码](https://www.volcengine.com/docs/6396/70462)文档。 |状态码 |错误码 |错误信息 |说明 | |---|---|---|---| |400 |InvalidArgument |The specified argument is invalid. |指定的参数不合法。 | |400 |InvalidOsType.Malformed |The specified OsType is malformed. |指定的操作系统不合法。 | |400 |InvalidTagFilterKey.Malformed |The specified TagFilterKey is malformed. |指定的查询标签的键格式错误。 | |400 |InvalidTagFilterValue.Malformed |The specified TagFilterValue is malformed. |指定的查询标签的值格式错误。 | |400 |InvalidVisibility.Malformed |The specified Visibility is malformed. |指定的Visibility不合法。 | |400 |LimitExceeded.MaximumImageIds |You've reached the limit on the number of ImageIds that you can set. |指定的镜像ID数量超过限制。 | |400 |LimitExceeded.MaximumStatus |You've reached the limit on the number of Status that you can set. |指定的状态数量超过限制。 | |400 |LimitExceeded.MaximumTagFilterKeys |You've reached the limit on the number of TagFilterKeys that you can set. |指定的查询标签键超出取值范围。 | |400 |LimitExceeded.MaximumTagFilterResults |You've reached the limit on the number of resources that you can describe by TagFilters. |通过标签过滤出的资源数量超过上限。 | |400 |LimitExceeded.MaximumTagFilterValues |You've reached the limit on the number of TagFilterValues that you can set. |指定的查询标签值超出取值范围。 | |404 |InvalidInstanceType.NotFound |The specified InstanceType does not exist. |指定的实例规格不存在。 | |409 |InvalidTagFilterKey.Conflict |The specified TagFilterKey already exists. |指定的过滤标签键已存在。 | |500 |InternalError |An internal error has occurred. |内部错误，请重试。如果多次尝试失败，请提交工单。 |

云服务器