DescribeImages - Elastic Compute Service

指定 ImageId、映像被使用場景、Filter 過濾等參數，查詢您可以使用的映像資源列表。

介面說明

您可以查詢的映像資源包括您的自訂映像、阿里雲端提供的公用映像、雲端市場映像以及其他阿里雲端使用者主動共享給您的共享映像。
支援分頁查詢，查詢結果包括可使用的映像資源總數和當前頁的映像資源。每頁的數量預設為 10 筆。
透過阿里雲端 CLI 呼叫 API 時，不同資料類型的請求參數取值必須遵循格式要求。更多資訊，請參見 CLI 參數格式說明。
當查詢阿里雲端官方提供的映像或共享映像（ImageOwnerAlias 指定 system 或 others）時，本次請求可忽略 RAM 鑑權規則。更多資訊，請參見鑑權規則。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

操作：是指具體的許可權點。
存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。
資源類型：是指操作中支援授權的資源類型。具體說明如下：
- 對於必選的資源類型，用前面加 * 表示。
- 對於不支援資源級授權的操作，用全部資源表示。
條件關鍵字：是指雲產品自身定義的條件關鍵字。
關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

ecs:DescribeImages

get

Image

acs:ecs:{#regionId}:{#accountId}:image/*

Image

acs:ecs:{#regionId}:{#accountId}:image/{#imageId}

無

請求參數

名稱	類型	必填	描述	樣本值
RegionId	string	是	映像所屬的地域 ID。您可以呼叫 DescribeRegions 查看最新的阿里雲端地域列表。	cn-hangzhou
Status	string	否	查詢指定狀態的映像，如果不設定此參數，預設只返回 Available 狀態的映像。取值範圍： Creating：映像正在建立中。 Waiting：多任務排隊中。 Available（預設）：您可以使用的映像。 UnAvailable：您不能使用的映像。 CreateFailed：建立失敗的映像。 Deprecated：已棄用的映像。預設值：Available。當前參數支援同時取多個值，值之間以半形逗號（,）隔開。	Available
ImageId	string	否	映像 ID。映像 ID 的命名規則公用映像：以作業系統版本號碼、架構、語言和發布日期命名。例如，Windows Server 2008 R2 企業版、64 位元英文系統的映像 ID 為 win2008r2_64_ent_sp1_en-us_40G_alibase_20190318.vhd。自訂映像、共享映像、雲端市場映像、社群映像的映像：以 m 開頭。	m-bp1g7004ksh0oeuc****
ShowExpired	boolean	否	訂閱型映像是否已經超過使用期限。	false
SnapshotId	string	否	根據某一快照 ID 建立的自訂映像。	s-bp17ot2q7x72ggtw****
ImageName	string	否	映像名稱。支援模糊搜尋。	testImageName
ImageFamily	string	否	映像族系名稱，查詢映像時可透過設定該參數來過濾當前族系對應的映像。預設值：空。說明阿里雲端官方映像關聯的映像族系資訊請參見公用映像概述。	hangzhou-daily-update
ImageOwnerAlias	string	否	映像來源。取值範圍： system：阿里雲端官方提供的，且不是透過雲端市場發布的映像，和控制台中的「公用映像」概念不同。 self：您建立的自訂映像。 others：包含共享映像（其他阿里雲端使用者直接共享給您的映像）和社群映像（任意阿里雲端使用者將其自訂映像完全公開共享後的映像）。您需要注意：尋找社群映像時，IsPublic 必須為 true。尋找共享映像時，IsPublic 需要設定為 false 或者不傳值。 marketplace：阿里雲端或者第三方供應商 ISV 在雲端市場發布的映像，需要和 ECS 一起購買。請自行留意雲端市場映像的收費詳情。預設值：空。說明空表示返回取值為 system、self 以及 others 的結果。	self
InstanceType	string	否	為指定的執行個體規格查詢可以使用的映像。	ecs.g5.large
IsSupportIoOptimized	boolean	否	映像是否可以運行在 I/O 最佳化執行個體上。	true
IsSupportCloudinit	boolean	否	映像是否支援 cloud-init。	true
OSType	string	否	映像的作業系統類型。取值範圍： windows。 linux。	linux
Architecture	string	否	映像的體系架構。取值範圍： i386。 x86_64。 arm64。	i386
PageNumber	integer	否	映像資源列表的頁碼。起始值：1。預設值：1。	1
PageSize	integer	否	分頁查詢時設定的每頁行數。最大值：100。預設值：10。	10
Usage	string	否	映像是否已經運行在 ECS 執行個體中。取值範圍： instance：映像處於運行狀態，有 ECS 執行個體使用。 none：映像處於閒置狀態，暫無 ECS 執行個體使用。	instance
DryRun	boolean	否	是否只預檢此次請求。 true：發送檢查請求，不會查詢資源狀況。檢查項包括 AccessKey 是否有效、RAM 使用者的授權情況和是否填寫了必需參數。如果檢查不通過，則返回對應錯誤。如果檢查通過，會返回錯誤碼 DryRunOperation。 false：發送正常請求，通過檢查後返回 2XX HTTP 狀態碼並直接查詢資源狀況。預設值：false。	false
ActionType	string	否	映像需要被使用到的場景。取值範圍： CreateEcs（預設）：建立執行個體。 ChangeOS：更換系統磁碟/更換作業系統。	CreateEcs
ResourceGroupId	string	否	自訂映像所在的企業資源群組 ID。使用該參數過濾資源時，資源數量不能超過 1000 個。說明不支援預設資源群組過濾。	rg-bp67acfmxazb4p****
Tag	array<object>	否	標籤列表。
	object	否	標籤資訊。
key	string	否	映像的標籤鍵。說明該參數即將被棄用，為提高相容性，建議您使用另一個 `Tag.N.Key` 參數。	null
Key	string	否	映像的標籤鍵。N 的取值範圍：1~20。使用一個標籤過濾資源，查詢到該標籤下的資源數量不能超過 1000 個；使用多個標籤過濾資源，查詢到同時綁定了多個標籤的資源數量不能超過 1000 個。如果資源數量超過 1000 個，請使用 ListTagResources 介面進行查詢。	TestKey
Value	string	否	映像的標籤值。N 的取值範圍：1~20。	TestValue
value	string	否	映像的標籤值。說明該參數即將被棄用，為提高相容性，建議您使用另一個 `Tag.N.Value` 參數。	null
Filter	array<object>	否	查詢資源時的篩選條件列表。
	object	否	查詢資源時的篩選條件。
Key	string	否	查詢資源時的篩選鍵。取值範圍：當該參數取值為 `CreationStartTime` 時，可以查詢在指定時間點（`Filter.N.Value`）後建立的資源資訊。當該參數取值為 `CreationEndTime` 時，可以查詢在指定時間點（`Filter.N.Value`）前建立的資源資訊。當該參數取值為 `NetworkType` 時，可以查詢指定網路類型的資源資訊。當該參數取值為 `CpuOnlineUpgrade`、`CpuOnlineDowngrade`、`MemoryOnlineUpgrade`、`MemoryOnlineDowngrade` 中的任何一個值時，可以查詢指定映像的 CPU 或記憶體的熱插拔支援情況。預設值：null。	CreationStartTime
Value	string	否	查詢資源時的篩選值。當（`Filter.N.Key`）為 `CreationStartTime` 或 `CreationEndTime` 時，格式為：`yyyy-MM-ddTHH:mmZ`，採用 UTC+0 時區。當（`Filter.N.Key`）為 `NetworkType` 時，可以指定網路類型的值有：`vpc`、`classic` 等。當（`Filter.N.Key`）取值為 `CpuOnlineUpgrade`、`CpuOnlineDowngrade`、`MemoryOnlineUpgrade`、`MemoryOnlineDowngrade` 時，該值可以取 `supported` 或 `unsupported`。預設值：null。	2017-12-05T22:40Z
IsPublic	boolean	否	是否查詢已發布的社群映像。取值範圍： true：查詢已發布的社群映像。當您指定該參數值為 true 時，ImageOwnerAlias 必須為 others。 false：查詢除社群映像的其他映像類型，具體以 ImageOwnerAlias 參數值為準。預設值：false。	false
ImageOwnerId	integer	否	映像所屬的阿里雲端帳號 ID。該參數僅在查詢共享映像以及社群映像時生效。	20169351435666****

返回參數

名稱	類型	描述	樣本值
	object
PageSize	integer	當前分頁包含多少條目。	1
PageNumber	integer	當前頁碼。	1
RequestId	string	請求 ID。	66189103-EDB2-43E2-BB60-BFF2B62F4EB8
TotalCount	integer	映像總數。	1
RegionId	string	映像所屬地域 ID。	cn-hangzhou
Images	object
Image	array<object>	映像資訊 Images 組成的集合。
	array<object>	映像資訊。
CreationTime	string	映像的建立時間。	2019-11-15T06:07:05Z
Status	string	映像的狀態。可能值： UnAvailable：不可用。 Available：可用。 Creating：建立中。 CreateFailed：建立失敗。	Available
ImageFamily	string	映像族系名稱。	hangzhou-daily-update
Progress	string	映像完成的進度，單位為百分比。	100%
IsCopied	boolean	是否是拷貝的映像。	false
IsSupportIoOptimized	boolean	是否可以在 I/O 優化執行個體上運行。	true
ImageOwnerAlias	string	映像來源。可能值： system：阿里雲提供的公共映像。 self：您建立的自訂映像。 others：其他阿里雲使用者提供的共享映像或社區映像。 marketplace：雲端市場映像提供的映像。	self
IsSupportCloudinit	boolean	是否支援 Cloud Init。	true
ImageVersion	string	映像版本。	2
Usage	string	有引用關係的資源類型。可能值： instance：建立了一台或多台 ECS 執行個體。 none：未建立過 ECS 執行個體。	none
IsSelfShared	string	是否共享過該自訂映像給其他使用者。	true
Description	string	描述資訊。	Archive log for Oracle
Size	integer	映像大小，單位：GiB。重要如果映像包含資料磁碟，此參數僅代表映像關聯的系統磁碟快照大小。	60
ResourceGroupId	string	映像所在的企業資源群組 ID。	rg-bp67acfmxazb4p****
Platform	string	作業系統平台。	Windows Server 2016
OSNameEn	string	作業系統的英文顯示名稱。	Windows Server 2016 Data Center Edition 64bit Chinese Edition
ImageName	string	映像的名稱。	testImageName
OSName	string	作業系統的中文顯示名稱。	Windows Server 2016 数据中心版 64位中文版
ImageId	string	映像 ID。	m-bp1g7004ksh0oeuc****
OSType	string	作業系統類型。可能值： windows。 linux。	windows
IsSubscribed	boolean	是否訂閱了該映像的商品碼對應的映像商品的服務條款。	false
ProductCode	string	雲端市場映像中的映像商品標識。	test000****
Architecture	string	映像系統架構類型。可能值： i386。 x86_64。 arm64。	x86_64
BootMode	string	映像的啟動模式。可能值： BIOS：BIOS 啟動模式。 UEFI：UEFI 啟動模式。 UEFI-Preferred：雙啟動模式。更多關於映像的啟動模式說明，請參見映像啟動模式。	BIOS
DiskDeviceMappings	object
DiskDeviceMapping	array<object>	映像下包含雲端硬碟和快照的對應關係集合。
	object	映像下包含雲端硬碟和快照的對應關係。
Type	string	映像的類型。	system
ImportOSSBucket	string	匯入映像所屬 OSS 的 bucket。	testEcsImport
Progress	string	對於複製中的映像，返回複製任務的進度。	32%
SnapshotId	string	快照 ID。	s-bp17ot2q7x72ggtw****
ImportOSSObject	string	匯入映像所屬 OSS 的 object。	imageImport
Device	string	雲端硬碟的裝置資訊，例如/dev/xvdb。	/dev/xvda
Size	string	雲端硬碟的大小。單位為 GiB。	60
RemainTime	integer	對於複製中的映像，返回複製任務的剩餘時間，單位：秒。	233
Format	string	映像格式。	qcow2
Encrypted	boolean	說明該參數正在邀測中。	true
Tags	object
Tag	array<object>	映像的標籤對資訊列表。
	object	映像的標籤對資訊。
TagValue	string	映像的標籤值。	Oracle
TagKey	string	映像的標籤鍵。	DTS
IsPublic	boolean	是否為公開映像。公開映像包括阿里雲提供的公共映像以及您已發佈為社區映像的自訂映像。可能值： true：公開映像。 false：非公開映像。	false
ImageOwnerId	integer	映像所屬的阿里雲帳號 ID。該參數僅在查詢共享映像以及社區映像時生效。	1234567890
LoginAsNonRootSupported	boolean	當前映像是否支援非 root 使用者登入。可能值： true：支援。 false：不支援。	false
SupplierName	string	社區映像認證企業名稱。	TestName
DetectionOptions	object	映像檢測相關結果。
Status	string	映像檢測任務狀態。可能值： Processing：檢測中。 Finished：檢測完成。	Processing
Items	object
Item	array<object>	映像檢測項列表。
	object	映像檢測項。
Name	string	映像檢測項名稱。	Nvme
Value	string	映像檢測項結果。	Supported
RiskLevel	string	匯入的自訂映像檢測項是否存在風險，如果存在風險返回此欄位，不存在風險則不返回。風險等級可能值： High：嚴重，影響執行個體能否啟動成功，強烈建議修復。 Medium：重要，影響執行個體啟動效能或者執行個體配置等，建議最佳化。	High
RiskCode	string	檢測項可能存在的缺陷。	NVMe.NotInstalled
Features	object	映像特性相關屬性。
NvmeSupport	string	映像是否支援 NVMe。可能值： supported：支援。表示以該映像建立的執行個體支援 NVMe 協定。 unsupported：不支援。表示以該映像建立的執行個體不支援 NVMe 協定。	supported
ImdsSupport	string	映像的中繼資料存取模式，可能值： v1：透過該映像建立 ECS 執行個體時，不支援將中繼資料存取模式設定為「僅加固模式」。 v2：透過該映像建立 ECS 執行個體時，支援將中繼資料存取模式設定為「僅加固模式」。執行個體中繼資料概述。	v2
CpuOnlineUpgrade	string	是否支援 CPU 熱升配。可能值： supported：支援。 unsupported ：不支援。	supported
CpuOnlineDowngrade	string	是否支援 CPU 熱降配。可能值： supported：支援。 unsupported ：不支援。	supported
MemoryOnlineUpgrade	string	是否支援記憶體熱升配。可能值： supported：支援。 unsupported ：不支援。	unsupported
MemoryOnlineDowngrade	string	是否支援記憶體熱降配。可能值： supported：支援。 unsupported ：不支援。	unsupported
LicenseType	string	許可證類型。該屬性決定了基於此映像建立 ECS 執行個體的計費方式和啟用邏輯，僅對 Windows Server 類型映像具有業務參考意義。可能值： Aliyun：阿里雲官方許可。基於此映像建立的執行個體，將包含 Windows Server 許可費用，執行個體啟動後由阿里雲自動啟用。 BYOL：自帶許可（Bring Your Own License）。基於此映像建立的執行個體，不包含 Windows Server 許可費用。執行個體啟動後不會被自動啟用，需使用自有合法許可手動啟用。	BYOL

樣本

正常返回樣本

JSON格式

{
  "PageSize": 1,
  "PageNumber": 1,
  "RequestId": "66189103-EDB2-43E2-BB60-BFF2B62F4EB8",
  "TotalCount": 1,
  "RegionId": "cn-hangzhou",
  "Images": {
    "Image": [
      {
        "CreationTime": "2019-11-15T06:07:05Z",
        "Status": "Available",
        "ImageFamily": "hangzhou-daily-update",
        "Progress": "100%",
        "IsCopied": false,
        "IsSupportIoOptimized": true,
        "ImageOwnerAlias": "self",
        "IsSupportCloudinit": true,
        "ImageVersion": "2",
        "Usage": "none",
        "IsSelfShared": "true",
        "Description": "Archive log for Oracle",
        "Size": 60,
        "ResourceGroupId": "rg-bp67acfmxazb4p****",
        "Platform": "Windows Server 2016",
        "OSNameEn": "Windows Server  2016 Data Center Edition 64bit Chinese Edition",
        "ImageName": "testImageName",
        "OSName": "Windows Server  2016 数据中心版 64位中文版",
        "ImageId": "m-bp1g7004ksh0oeuc****",
        "OSType": "windows",
        "IsSubscribed": false,
        "ProductCode": "test000****",
        "Architecture": "x86_64",
        "BootMode": "BIOS",
        "DiskDeviceMappings": {
          "DiskDeviceMapping": [
            {
              "Type": "system",
              "ImportOSSBucket": "testEcsImport",
              "Progress": "32%",
              "SnapshotId": "s-bp17ot2q7x72ggtw****",
              "ImportOSSObject": "imageImport",
              "Device": "/dev/xvda",
              "Size": "60",
              "RemainTime": 233,
              "Format": "qcow2",
              "Encrypted": true
            }
          ]
        },
        "Tags": {
          "Tag": [
            {
              "TagValue": "Oracle",
              "TagKey": "DTS"
            }
          ]
        },
        "IsPublic": false,
        "ImageOwnerId": 1234567890,
        "LoginAsNonRootSupported": false,
        "SupplierName": "TestName",
        "DetectionOptions": {
          "Status": "Processing",
          "Items": {
            "Item": [
              {
                "Name": "Nvme",
                "Value": "Supported",
                "RiskLevel": "High",
                "RiskCode": "NVMe.NotInstalled"
              }
            ]
          }
        },
        "Features": {
          "NvmeSupport": "supported",
          "ImdsSupport": "v2",
          "CpuOnlineUpgrade": "supported",
          "CpuOnlineDowngrade": "supported",
          "MemoryOnlineUpgrade": "unsupported",
          "MemoryOnlineDowngrade": "unsupported"
        },
        "LicenseType": "BYOL"
      }
    ]
  }
}

錯誤碼

HTTP status code	錯誤碼	錯誤資訊	描述
400	InvalidImageOwnerAlias.ValueNotSupported	The specified ImageOwnerAlias value is not supported.	無效的映像擁有者別名，請您檢查該參數是否正確。
400	InvalidParamter	Invalid Parameter.	輸入的參數無效。
400	InvalidTag.Mismatch	The specified Tag.n.Key and Tag.n.Value are not match.	指定的 Tag.N.Key 和 Tag.N.Value 不匹配。
400	InvalidTagCount	The specified tags are beyond the permitted range.	指定的標記超出取值範圍。
400	InvalidInstanceType.ValueNotSupported	The specified instance type %s does not exist. You can use the DescribeInstanceTypes API to query the available instance types.	指定的執行個體規格不支援目前執行個體掛載的資料磁碟規格。
400	InvalidFilterValue.NetworkType	The specified networkType value in the Filter is invalid.	篩選器中指定的網路類型值無效。
400	InvalidOperation.ImageOwnerIdUnsupported	The parameter "ImageOwnerId" is not supported in this context, it is only valid when querying shared images or community images.	此處不支援 ImageOwnerId 參數，該參數僅在查詢共享映像或社群映像時有效。
400	InvalidImageOwnerAlias.PublicImageUnsupported	When querying images, the parameter ImageOwnerAlias should be others while specified parameter IsPublic is true.	查詢映像時，參數 IsPublic 是 true，則參數 ImageOwnerAlias 必須是 others。
400	MissingParameter.Status	The specified parameter Status is not supplied.
500	InternalError	The request processing has failed due to some unknown error.
403	CurrentAccount.NotSupportPublicImage	Public image is not supported for current account.	目前使用者不支援使用公用映像。
404	InvalidFilterKey.NotFound	The specified Filter Key is not found.	指定的 Filter.N.Key 無效。
404	InvalidFilterValue	The specified Filter Value is not valid.	Filter 中的 Value 無效。
404	InvalidUsage	The specified Usage is not valid.	Usage 參數無效。
404	InvalidOSType	The specified OSType is not valid.	OSType 參數無效。
404	InvalidArchitecture	The specified Architecture is not valid.	輸入的架構參數無效。

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。