接口功能介绍

根据规格名称、镜像可见类型等，查询可以使用的镜像资源。
准备：
1. 在调用前需了解如何构造请求，可参见：如何调用 API - 构造请求。
2. OpenAPI 请求需进行加密调用，可参见：如何调用 API - 认证鉴权。
注意：
1. 推荐使用查询物理机镜像接口来查询物理机镜像。
2. 在调用前，请您认真阅读此文档，包括但不限于参数描述中的“注意”部分。

接口约束

接口请求成功需至少满足：
1. 您具有调用此接口的权限。
2. 传入的有取值范围的参数的值在取值范围内。
3. 传入的 azName 参数所指定的可用区对您而言是存在的。
4. 传入的 flavorName 参数所指定的规格对您而言是存在的。
5. 传入的 projectID 参数所指定的企业项目对您而言是存在的。
6. 传入的 regionID 参数所指定的资源池对您而言是存在的。

URI

GET /v4/image/list

路径参数
无

Query参数

参数	是否必填	参数类型	说明	示例
regionID	是	String	资源池 ID。可使用资源池列表查询接口来查询您可见的资源池的列表。	88f8888888dd88ec888888888d888d8b
azName	否	String	可用区名称。注意： 1. 仅在多可用区资源池下对物理机镜像生效，在单可用区资源池下无需指定此参数。 2. 可使用资源池可用区查询接口查询多可用区资源池的可用区信息。若响应的 returnObj 中的 zoneList 是空的可用区列表，则所指定的资源池是单可用区资源池。	cn-huadong1-jsnj1A-public-ctcloud
flavorName	否	String	规格名称。注意： 1. 可使用查询一个或多个云主机规格资源接口来查询您可以使用的云主机规格（如 s7.small.1）。 2. 可使用查询轻量型云主机的规格套餐资源接口来查询您可以使用的轻量型云主机规格（如 lite1.fix.small.1）。	s7.small.1
imageScene	否	String	镜像场景。取值范围（值：描述）： dev：开发工具。 ecommerce：电商。 gaming：游戏。 website：网站。注意：仅在 imageVisibilityCode/visibility 参数值为 5（应用镜像）时用于筛选应用镜像，未指定镜像场景时不启用此筛选。	dev
imageStatus	否	String	镜像状态。取值范围（值：描述）： accepted：已接受共享镜像。 rejected：已拒绝共享镜像。 waiting：等待接受/拒绝共享镜像。注意：仅在 imageVisibilityCode/visibility 参数值为 2（共享镜像）时生效，未指定镜像状态时默认显示镜像状态为 accepted 或 waiting 的共享镜像。	rejected
imageSubcategory	否	String	镜像子种类。取值范围（值：描述）： app：云主机应用镜像。 thin_app：轻量型云主机应用镜像。注意：仅在 imageVisibilityCode/visibility 参数值为 5（应用镜像）时用于筛选应用镜像，未指定镜像子种类时不启用此筛选。	app
imageVisibilityCode	否	Integer	镜像可见类型代码。取值范围（值：描述）： 1：公共镜像（默认值）。 0：私有镜像。 2：共享镜像。 3：安全产品镜像。 4：甄选镜像。 5：应用镜像。	0
pageNo	否	Integer	页码。取值范围：最小 1（默认值）。	1
pageSize	否	Integer	每页记录数目。取值范围：最小 1，最大 50，默认 10。	10
projectID	否	String	企业项目 ID。可使用查询企业项目列表接口来查询您可以使用的企业项目 ID。注意：仅在 imageVisibilityCode/visibility 参数值为 0（私有镜像）时生效。	0
queryContent	否	String	查询内容。基于镜像名称的搜索，大小写不敏感。	CTyunOS
status	否	String	镜像状态（同 imageStatus 参数）。注意： 1. status 参数已弃用，目前仍可使用，但会在合适的时机移除，因此请您尽快切换至 imageStatus 参数。 2. 若使用此弃用参数，则应传入在取值范围内的值。 3. 若同时使用了推荐的参数和此弃用参数，则推荐的参数的值将优先。	rejected
visibility	否	Integer	镜像可见类型代码（同 imageVisibilityCode 参数）。注意： 1. visibility 参数已弃用，目前仍可使用，但会在合适的时机移除，因此请您尽快切换至 imageVisibilityCode 参数。 2. 若使用此弃用参数，则应传入在取值范围内的值。 3. 若同时使用了推荐的参数和此弃用参数，则推荐的参数的值将优先。	0

请求参数

请求头header参数
无

请求体body参数
无

响应参数

参数	参数类型	说明	示例	下级对象
statusCode	Integer	状态码。取值范围（值：描述）： 800：成功。 900：失败。	800
error	String	错误码（product.module.code 三段式码）。	Openapi.PatternCheck.NotValid
errorCode	String	同 error 参数。	Openapi.PatternCheck.NotValid
message	String	响应状态描述（一般为英文）。	SUCCESS
description	String	响应状态描述（一般为中文）。	成功
returnObj	Object	成功时返回的数据。		returnObj

表 returnObj

参数	参数类型	说明	示例	下级对象
images	Array of Objects	镜像列表。		image
currentPage	Integer	当前页码。	1
pageNo	Integer	当前页码（同 currentPage 参数）。注意：pageNo 参数已弃用，目前仍会返回，但会在合适的时机移除，因此请您尽快切换至 currentPage 参数。	1
currentCount	Integer	当前页记录数。	10
pageSize	Integer	当前页记录数（同 currentCount 参数）。注意：pageSize 参数已弃用，目前仍会返回，但会在合适的时机移除，因此请您尽快切换至 currentCount 参数。	10
totalPage	Integer	总页数。	1
totalCount	Integer	总记录数。	10

表 image

参数	参数类型	说明	示例
appVersion	String	应用版本。	19.03.9
architecture	String	系统架构。取值范围（值：描述）： aarch64：AArch64 架构。 loongarch64：LoongArch64 架构。 sw_64：sw_64 架构。 x86_64：x86_64 架构。	x86_64
azName	String	在多可用区资源池下物理机镜像的可用区名称。	cn-huadong1-jsnj1A-public-ctcloud
bootMode	String	x86_64 架构非数据盘镜像的启动方式。取值范围（值：描述）： bios：BIOS 启动方式。 uefi：UEFI 启动方式。	bios
chargeableImage	Boolean	用于表示是否是收费镜像的标识。	false
containerFormat	String	容器格式。	bare
createdTime	Integer	创建时间戳。	1698145871
createdTimeStr	String	创建时间。	2023-10-24T11:11:11Z
description	String	描述信息。	Test CTyunOS
destinationUser	String	共享镜像的接受人。	test@test.com
diskFormat	String	磁盘格式。取值范围（值：描述）： qcow2：QCOW2 格式。 raw：RAW 格式。 vhd：VHD 格式。 vmdk：VMDK 格式。	raw
diskID	String	私有镜像来源的系统盘/数据盘 ID。	8888a888-b888-8888-a888-baee8d8ce88c
diskSize	Integer	磁盘容量。单位为 GiB。	40
imageClass	String	镜像类别。取值范围（值：描述）： BMS：物理机。 ECS：云主机。	ECS
imageID	String	镜像 ID。	8d8e8888-8ed8-88b8-88cb-888f8b8cf8fa
imageName	String	镜像名称。	CTyunOS-test
imageScene	String	镜像场景。取值范围（值：描述）： dev：开发工具。 ecommerce：电商。 gaming：游戏。 website：网站。注意：镜像可适用于多场景，多个镜像场景之间以英文逗号（,）分隔，如 ecommerce,website。	dev
imageShareCount	Integer	私有镜像的共享数量。可使用查询私有镜像的共享列表接口来查询指定私有镜像的共享列表。	0
imageSize	Long	镜像大小。单位为 byte。	42949672960
imageStatus	String	镜像状态。取值范围（值：描述）： accepted：已接受共享镜像。 active：正常。 deactivated：已弃用。 deactivating：弃用中。 deleted：已删除。 deleting：删除中。 error：错误。 queued：排队中/创建中。 reactivating：取消弃用中。 rejected：已拒绝共享镜像。 waiting：等待接受/拒绝共享镜像。	rejected
imageSubcategory	String	镜像子种类。取值范围（值：描述）： app：云主机应用镜像。 thin_app：轻量型云主机应用镜像。	app
imageType	String	镜像类型。取值范围（值：描述）：（空，即 null）：系统盘镜像。 data_disk_image：数据盘镜像。 full_ecs_image：整机镜像。 iso_image：ISO 镜像。	data_disk_image
imageVisibility	String	镜像可见类型。取值范围（值：描述）： private：私有镜像。 public：公共镜像。 shared：共享镜像。 safe：安全产品镜像。 community：甄选镜像。 app：应用镜像。	private
maximumRAM	Integer	最大内存。单位为 GiB。	0
minimumRAM	Integer	最小内存。单位为 GiB。	0
osDistro	String	操作系统发行版。	CTyunOS
osType	String	操作系统类型。取值范围（值：描述）： linux：Linux 系操作系统。 windows：Windows 系操作系统。	linux
osVersion	String	操作系统版本。	23.01
projectID	String	企业项目 ID。	0
sharedListLength	Integer	私有镜像的共享数量（同 imageShareCount 参数）。注意：sharedListLength 参数已弃用，目前仍会返回，但会在合适的时机移除，因此请您尽快切换至 imageShareCount 参数。	0
size	Long	镜像大小（同 imageSize 参数）。注意：size 参数已弃用，目前仍会返回，但会在合适的时机移除，因此请您尽快切换至 imageSize 参数。	42949672960
sourceServerID	String	私有镜像来源的云主机/物理机 ID。	88f888ea-88ff-88ec-a8bc-888888888fe8
sourceUser	String	共享镜像的发起人。	ims-test@test.com
status	String	镜像状态（同 imageStatus 参数）。注意：status 参数已弃用，目前仍会返回，但会在合适的时机移除，因此请您尽快切换至 imageStatus 参数。	rejected
supportOneClickSFSMount	Boolean	用于表示是否支持一键挂载文件系统的标识。	false
supportXSSD	Boolean	用于表示是否支持 XSSD 类型盘的标识。	false
updatedTime	Integer	更新时间戳。	1698145871
updatedTimeStr	String	更新时间。	2023-10-24T11:11:11Z
visibility	String	镜像可见类型（同 imageVisibility 参数）。注意：visibility 参数已弃用，目前仍会返回，但会在合适的时机移除，因此请您尽快切换至 imageVisibility 参数。	private

枚举参数

无

请求示例

请求url

示例 1：若您在华东 1 欲查询第 1 页（每页最多 10 份镜像）公共镜像，则参考如下形式查询可以使用的镜像资源。
GET .../v4/image/list?regionID=bb9fdb42056f11eda1610242ac110002

示例 2：若您在华东 1 欲查询第 1 页（每页最多 10 份镜像）适用于云主机规格 s7.small.1 的公共镜像，则参考如下形式查询可以使用的镜像资源。
GET .../v4/image/list?flavorName=s7.small.1&regionID=bb9fdb42056f11eda1610242ac110002

示例 3：若您在华东 1 欲查询第 2 页（每页最多 20 份镜像）公共镜像，则参考如下形式查询可以使用的镜像资源。
GET .../v4/image/list?pageNo=2&pageSize=20&regionID=bb9fdb42056f11eda1610242ac110002

示例 4：若您在华东 1 欲查询第 1 页（每页最多 10 份镜像）属于默认企业项目的私有镜像，则参考如下形式查询可以使用的镜像资源。
GET .../v4/image/list?imageVisibilityCode=0&projectID=0&regionID=bb9fdb42056f11eda1610242ac110002

示例 5：若您在华东 1 欲在设定查询内容为 CTyunOS 的情况下查询第 1 页（每页最多 10 份镜像）私有镜像，则参考如下形式查询可以使用的镜像资源。
GET .../v4/image/list?imageVisibilityCode=0&queryContent=CTyunOS&regionID=bb9fdb42056f11eda1610242ac110002

示例 6：若您在华东 1 欲查询第 1 页（每页最多 10 份镜像）已拒绝的共享镜像，则参考如下形式查询可以使用的镜像资源。
GET .../v4/image/list?imageStatus=rejected&imageVisibilityCode=2&regionID=bb9fdb42056f11eda1610242ac110002

示例 7：若您在华东 1 欲查询适用于开发场景的轻量型云主机应用镜像，则参考如下形式查询可以使用的镜像资源。
GET .../v4/image/list?extendedImageProperty=thin_app&imageScene=dev&imageVisibilityCode=5&regionID=bb9fdb42056f11eda1610242ac110002

请求头header

无

请求体body

无

响应示例

{
  "returnObj": {
    "images": [
      {
        "appVersion": null,
        "architecture": "x86_64",
        "azName": null,
        "bootMode": "bios",
        "chargeableImage": false,
        "containerFormat": "bare",
        "createdTime": 1698145871,
        "createdTimeStr": "2023-10-24T11:11:11Z",
        "description": "Test CTyunOS",
        "destinationUser": null,
        "diskFormat": "raw",
        "diskID": "8888a888-b888-8888-a888-baee8d8ce88c",
        "diskSize": 40,
        "imageClass": "ECS",
        "imageID": "8d8e8888-8ed8-88b8-88cb-888f8b8cf8fa",
        "imageName": "CTyunOS-test",
        "imageScene": null,
        "imageShareCount": 0,
        "imageSize": 42949672960,
        "imageStatus": "active",
        "imageSubcategory": null,
        "imageType": null,
        "imageVisibility": "private",
        "maximumRAM": 0,
        "minimumRAM": 0,
        "osDistro": "CTyunOS",
        "osType": "linux",
        "osVersion": "23.01",
        "projectID": "0",
        "sharedListLength": 0,
        "size": 42949672960,
        "sourceServerID": "88f888ea-88ff-88ec-a8bc-888888888fe8",
        "sourceUser": null,
        "status": "active",
        "supportOneClickSFSMount": false,
        "supportXSSD": false,
        "updatedTime": 1698145871,
        "updatedTimeStr": "2023-10-24T11:11:11Z",
        "visibility": "private"
      }
    ],
    "currentPage": 1,
    "pageNo": 1,
    "currentCount": 1,
    "pageSize": 1,
    "totalPage": 1,
    "totalCount": 1
  },
  "errorCode": "",
  "message": "SUCCESS",
  "description": "成功",
  "statusCode": 800
}

状态码

请参考状态码

错误码

请参考错误码

应用商城

合作伙伴

开发者

支持与服务

了解天翼云

查看所有产品

镜像服务

镜像服务

接口功能介绍

接口约束

URI

请求参数

响应参数

枚举参数

请求示例

响应示例

状态码

错误码

活动

应用商城

合作伙伴

开发者

支持与服务

了解天翼云

查看所有产品

镜像服务

镜像服务

接口功能介绍

接口约束

URI

请求参数

响应参数

枚举参数

请求示例

响应示例

状态码

错误码