DescribeSnapshots - Elastic Compute Service

查詢雲端硬碟的快照列表資訊。例如快照狀態、正在建立的快照剩餘完成時間、自動快照保留天數等。

介面說明

InstanceId、DiskId和SnapshotIds不是必需的請求參數，但是可以構建過濾器邏輯，參數之間為邏輯與（And）關係。

透過阿里雲 CLI 呼叫 API 時，不同資料類型的請求參數取值必須遵循一定的格式要求，詳情請參見 CLI 參數格式說明。

請求示例：

查詢杭州地域下 ECS 執行個體所有雲端硬碟的快照資訊列表

。

RegionId:  cn-hangzhou,   //設定華東 1（杭州）地域。
InstanceId:  i-bp1fh7by6d9mw7zr****   //設定待查詢的執行個體 ID。

。

查詢杭州地域下某一雲端硬碟的快照資訊

。

RegionId:  cn-hangzhou,   //設定華東 1（杭州）地域。
DiskId:   d-bp10e7ej8z743dmu****   //設定待查詢的雲端硬碟 ID。

。

根據快照 ID 查詢杭州地域下兩個快照的資訊

。

RegionId:  cn-hangzhou,   //設定華東 1（杭州）地域。
SnapshotIds:   ["d-bp10e7ej8z743dmu****", "s-bp19vd1lorzgzt2s****"]   //設定待查詢的快照 ID 陣列。

。

查詢杭州地域下某一時間節點後建立的快照資訊

。

RegionId:  cn-hangzhou,   //設定華東 1（杭州）地域。
Filter.1.Key:   CreationStartTime,   //設定待查詢的快照 ID 陣列。
Filter.1.Value:   2024-11-27T00:00Z。

。

調試

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

調試

授權資訊

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

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

操作

存取層級

資源類型

條件關鍵字

關聯操作

ecs:DescribeSnapshots

get

Snapshot

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

Snapshot

acs:ecs:{#regionId}:{#accountId}:snapshot/{#snapshotId}

無

請求參數

名稱	類型	必填	描述	樣本值
InstanceId	string	否	指定的執行個體 ID，即需要查詢執行個體下雲端硬碟的快照資訊。	i-bp67acfmxazb4p****
DiskId	string	否	指定的雲端硬碟裝置 ID。	d-bp67acfmxazb4p****
SnapshotLinkId	string	否	快照鏈 ID。	sl-bp1grgphbcc9brb5****
RegionId	string	是	雲端硬碟所屬的地域 ID。您可以呼叫 DescribeRegions 查看最新的阿里雲地域列表。	cn-hangzhou
SnapshotIds	string	否	快照標識編碼。取值可以由多個快照 ID 組成一個 JSON 陣列，最多支援 100 個 ID，ID 之間用半形逗號（,）隔開。	["s-bp67acfmxazb4p**", "s-bp67acfmxazb5p", … "s-bp67acfmxazb6p**"]
PageNumber	integer	否	說明該參數即將下線，建議您使用參數 NextToken 與 MaxResults 完成分頁查詢操作。	1
PageSize	integer	否	說明該參數即將下線，建議您使用 NextToken 與 MaxResults 完成分頁查詢操作。	10
NextToken	string	否	查詢起始標誌。由上一次的請求結果中取得。	caeba0bbb2be03f84eb48b699f0a4883
MaxResults	integer	否	分頁查詢時每頁行數。最大值：100。預設值：10。	10
SnapshotName	string	否	快照名稱。	testSnapshotName
Status	string	否	快照狀態。取值範圍： progressing：正在建立的快照。 accomplished：建立成功的快照。 failed：建立失敗的快照。 all（預設）：所有快照狀態。	all
SnapshotType	string	否	快照建立類型。取值範圍： auto：自動建立快照。 user：手動建立快照。 all（預設）：所有的快照建立類型。	all
Filter.1.Key	string	否	查詢資源時的篩選鍵，取值必須為`CreationStartTime`。同時設定`Filter.1.Key`和`Filter.1.Value`可以查詢在指定時間點後建立的資源資訊。	CreationStartTime
Filter.2.Key	string	否	查詢資源時的篩選鍵，取值必須為`CreationEndTime`。同時設定`Filter.2.Key`和`Filter.2.Value`可以查詢在指定時間點前建立的資源資訊。	CreationEndTime
Filter.1.Value	string	否	查詢資源時的篩選值。指定該參數時必須同時指定`Filter.1.Key`參數，格式為：`yyyy-MM-ddTHH:mmZ`，採用 UTC +0 時區。	2019-12-13T17:00Z
Filter.2.Value	string	否	查詢資源時的篩選值。指定該參數時必須同時指定`Filter.2.Key`參數，格式為：`yyyy-MM-ddTHH:mmZ`，採用 UTC +0 時區。	2019-12-13T22:00Z
Usage	string	否	快照是否被用作建立映像或雲端硬碟。取值範圍： image：使用快照建立了自訂映像。 disk：使用快照建立了雲端硬碟。 image_disk：使用快照建立了資料磁碟和自訂映像。 none：暫未使用。	none
SourceDiskType	string	否	快照來源雲端硬碟的雲端硬碟類型。取值範圍： system：系統磁碟。 data：資料磁碟。說明取值不區分大小寫。	system
Encrypted	boolean	否	是否過濾加密快照。預設值：false 。	false
ResourceGroupId	string	否	資源群組 ID。使用該參數過濾資源時，資源數量不能超過 1000 個。說明不支援預設資源群組過濾。	rg-bp67acfmxazb4p****
DryRun	boolean	否	是否只預檢此次請求。 true：傳送檢查請求，不會查詢資源狀況。檢查項包括 AccessKey 是否有效、RAM 使用者的授權情況和是否填寫了必需參數。如果檢查不通過，則傳回對應錯誤。如果檢查通過，會傳回錯誤碼 DryRunOperation。 false（預設）：傳送正常請求，通過檢查後傳回 2XX HTTP 狀態碼並直接查詢資源狀況。	false
KMSKeyId	string	否	資料磁碟對應的 KMS 密鑰 ID。	0e478b7a-4262-4802-b8cb-00d3fb40****
Category	string	否	快照類型。取值範圍： Standard：標準快照。 Flash：本地快照。該參數取值即將被棄用，原本地快照更替為快照極速可用功能。該參數說明如下：如果您在 2020 年 12 月 14 日之前使用過本地快照。您可以正常使用該參數。如果您在 2020 年 12 月 14 日之前未使用過本地快照。您不能使用該參數。 archive：歸檔快照。。	Standard
Tag	array<object>	否	標籤列表。
	object	否
key	string	否	資源的標籤鍵。說明為提高相容性，建議您盡量使用 Tag.N.Key 參數。	SnapshotTest
Key	string	否	快照的標籤鍵。N 的取值範圍：1~20。使用一個標籤過濾資源，查詢到該標籤下的資源數量不能超過 1000 個；使用多個標籤過濾資源，查詢到同時繫結了多個標籤的資源數量不能超過 1000 個。如果資源數量超過 1000 個，請使用 ListTagResources 介面進行查詢。	TestKey
Value	string	否	快照的標籤值。N 的取值範圍：1~20。	TestValue
value	string	否	資源的標籤值。說明為提高相容性，建議您盡量使用 Tag.N.Value 參數。	SnapshotTest

返回參數

名稱	類型	描述	樣本值
	object
NextToken	string	下一個查詢起始標誌。	caeba0bbb2be03f84eb48b699f0a4883
PageSize	integer	說明該參數即將下線，建議您使用 NextToken 與 MaxResults 完成分頁查詢操作。	10
PageNumber	integer	說明該參數即將下線，建議您使用 NextToken 與 MaxResults 完成分頁查詢操作。	1
RequestId	string	請求 ID。	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E
TotalCount	integer	快照總個數。說明使用`MaxResults`和`NextToken`參數進行分頁查詢時，傳回的`TotalCount`參數值無效。	1
Snapshots	object
Snapshot	array<object>	快照詳情集合。
	array<object>
Status	string	快照狀態。可能值： progressing：正在建立。 accomplished：建立成功。 failed：建立失敗。	accomplished
CreationTime	string	建立時間。按照ISO 8601標準表示，並使用 UTC +0 時間，格式為 yyyy-MM-ddTHH:mm:ssZ。	2020-08-20T14:52:28Z
Progress	string	快照建立進度，單位為百分比。	100%
InstantAccess	boolean	是否開啟了快照極速可用能力。可能值： true：開啟。ESSD 雲端硬碟、ESSD Entry 雲端硬碟預設開啟該能力。 false：關閉。即快照為未開啟極速可用能力的標準快照。說明該參數已棄用。ESSD 雲端硬碟標準快照已升級為預設極速可用，您無需額外配置，且不產生額外花銷。	false
Available	boolean	快照是否可用於建立雲端硬碟、復原雲端硬碟、共用快照。可能值： true：可用。 false：不可用。	false
RemainTime	integer	正在建立的快照剩餘完成時間，單位為秒。	38
SourceDiskSize	string	源雲端硬碟容量，單位：GiB。	40
RetentionDays	integer	自動快照保留天數。	30
SourceDiskType	string	源雲端硬碟屬性。可能值： system data	system
SourceStorageType	string	原雲端硬碟類型。說明該參數即將被棄用，為提高相容性，建議您盡量使用其他參數。	disk
Usage	string	快照是否被用作建立鏡像或雲端硬碟。可能值： image：自訂鏡像。 disk：雲端硬碟。 image_disk：自訂鏡像和資料盤。 none：暫未使用。	image
LastModifiedTime	string	快照的最後變更時間。按照ISO 8601標準表示，並使用 UTC +0 時間，格式為 yyyy-MM-ddTHH:mm:ssZ。	2020-08-25T14:18:09Z
Encrypted	boolean	該快照是否加密。可能值： true：是。 false：否。	false
SnapshotType	string	快照建立類型。可能值： auto 或者 timer：自動建立快照。 user：手動建立快照。 all：所有的快照建立類型。	all
SourceDiskId	string	源雲端硬碟 ID。如果快照的源雲端硬碟已經被釋放，該欄位仍舊保留。	d-bp67acfmxazb4ph****
SnapshotName	string	快照顯示名稱。如果建立時指定了快照顯示名稱，則返回。	testSnapshotName
InstantAccessRetentionDays	integer	設定快照極速可用功能的保留時間，保留時間到期後自動關閉快照極速可用功能。預設與參數`RetentionDays`的值一致。說明該參數已棄用。ESSD 雲端硬碟標準快照已升級為預設極速可用，您無需額外配置，且不產生額外花銷。	30
Description	string	描述資訊。	testDescription
SnapshotId	string	快照 ID。	s-bp67acfmxazb4p****
RegionId	string	快照所屬的地區 ID。	cn-hangzhou
ResourceGroupId	string	資源群組 ID。	rg-bp67acfmxazb4p****
Category	string	快照類型。可能值： Standard：標準快照。 Flash：本地快照。該參數取值即將被棄用，原本地快照更替為快照極速可用功能。 archive：歸檔快照。	standard
KMSKeyId	string	資料盤對應的 KMS 金鑰識別碼。	0e478b7a-4262-4802-b8cb-00d3fb40****
SnapshotSN	string	快照序號。	64472-116742336-61976****
ProductCode	string	從雲市場鏡像繼承的產品編號。	jxsc000****
SourceSnapshotId	string	源快照。	s-bp67acfmxazb4p****
SourceRegionId	string	源快照地區。	cn-hangzhou
FullSnapshotSizeInBytes	integer		65535
Tags	object
Tag	array<object>	標籤。
	object
TagValue	string	快照的標籤值。	TestValue
TagKey	string	快照的標籤鍵。	TestKey
SnapshotLinkId	string	快照關聯的快照鏈 ID。	sl-bp1grgphbcc9brb5****

樣本

正常返回樣本

JSON格式

{
  "NextToken": "caeba0bbb2be03f84eb48b699f0a4883",
  "PageSize": 10,
  "PageNumber": 1,
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "TotalCount": 1,
  "Snapshots": {
    "Snapshot": [
      {
        "Status": "accomplished",
        "CreationTime": "2020-08-20T14:52:28Z",
        "Progress": "100%",
        "InstantAccess": false,
        "Available": false,
        "RemainTime": 38,
        "SourceDiskSize": "40",
        "RetentionDays": 30,
        "SourceDiskType": "system",
        "SourceStorageType": "disk",
        "Usage": "image",
        "LastModifiedTime": "2020-08-25T14:18:09Z",
        "Encrypted": false,
        "SnapshotType": "all",
        "SourceDiskId": "d-bp67acfmxazb4ph****",
        "SnapshotName": "testSnapshotName",
        "InstantAccessRetentionDays": 30,
        "Description": "testDescription",
        "SnapshotId": "s-bp67acfmxazb4p****",
        "RegionId": "cn-hangzhou",
        "ResourceGroupId": "rg-bp67acfmxazb4p****",
        "Category": "standard",
        "KMSKeyId": "0e478b7a-4262-4802-b8cb-00d3fb40****",
        "SnapshotSN": "64472-116742336-61976****",
        "ProductCode": "jxsc000****",
        "SourceSnapshotId": "s-bp67acfmxazb4p****",
        "SourceRegionId": "cn-hangzhou",
        "FullSnapshotSizeInBytes": 65535,
        "Tags": {
          "Tag": [
            {
              "TagValue": "TestValue",
              "TagKey": "TestKey"
            }
          ]
        },
        "SnapshotLinkId": "sl-bp1grgphbcc9brb5****"
      }
    ]
  }
}

錯誤碼

HTTP status code	錯誤碼	錯誤資訊
400	InvalidTag.Mismatch	The specified Tag.n.Key and Tag.n.Value are not match.
400	InvalidTagCount	The specified tags are beyond the permitted range.
500	InternalError	The request processing has failed due to some unknown error.
403	InvalidSnapshotIds.Malformed	The amount of specified specified snapshot Ids exceeds the limit.
403	InvalidSnapshotCategory.Malformed	The specified Category is not valid.
403	InvalidCategory.SnapshotLinkMismatch	The specified category does not match the actual category of the snapshot link.
404	InvalidFilterKey.NotFound	The specified FilterKey is not found.
404	InvalidFilterValue	The specified FilterValue exceeds the limit.
404	InvalidUsage	The specifed Usage is not valid.
404	InvalidSourceDiskType	The specifed SourceDiskType is not valid.
404	InvalidStatus.NotFound	The specified Status is not found.
404	InvalidSnapshotType.NotFound	The specfied SnapshotType is not found.
404	InvalidSnapshotLinkId.NotFound	The specified snapshot link is not found.

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

變更歷史

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