DescribeImages - 查询镜像列表--云服务器-火山引擎

文档中心

立即注册

导航

DescribeImages - 查询镜像列表

最近更新时间：2024.09.19 09:56:35首次发布时间：2021.07.31 07:48:16

调用 DescribeImages 接口，查询镜像信息。

请求说明

调用该接口时，使用TagFilters.N.Key和TagFilters.N.Values.N查询到的镜像数量不能超过1000个。若超过1000个，请使用 DesribeTags 接口进行查询。

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

参数	类型	是否必填	示例值	描述
Action	String	是	DescribeImages	要执行的操作，取值：DescribeImages。
Version	String	是	2020-04-01	API的版本，取值：2020-04-01。
ImageIds.N	Array of String	否	ImageIds.1=image-3tksv4n6ay3vj0****& ImageIds.2=image-2asdv4n6ay3vj0****	镜像的ID，最多支持100个ID。您可以调用CreateImage、ImportImage接口获取自定义镜像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	Array of String	否	Status.1=available&Status.2=creating	镜像状态，最多支持10个。取值： available（默认）：可用 creating：创建中 error：错误说明参数 - N：表示镜像状态的序号。多个镜像状态之间用&分隔。
TagFilters.N.Key	Array of String	否	TagFilters.1.Key=k1	镜像标签的标签键。参数 - N：表示标签键的序号。取值范围：1～10，多个标签键之间用&分隔。不允许重复。
TagFilters.N.Values.N	Array of 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：共享镜像

返回参数

下表仅列出本接口特有的返回参数。更多信息请参见返回结构。

参数	类型	示例值	描述
Images	Array of Object	--	镜像信息。
NextToken	String	bHpwdXJja2RxemU1eG5sb3NzdGcW1-RCEq******	本次调用返回的查询凭证值，返回为空表示该页为末页。

请求示例

GET /?Action=DescribeImages&Version=2020-04-01&ImageId=image-ebgy1og99tfct0gw**** HTTP/1.1
Host: open.volcengineapi.com
Region: cn-beijing
Service: ecs

返回示例

{
  "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位",
        "PlatformVersion": "7.9",
        "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": ""
  }
}

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

状态码	错误码	错误信息	说明
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.	内部错误，请重试。如果多次尝试失败，请提交工单。