The following steps describe how to use the EBS direct APIs to read snapshots:
-
Use the ListSnapshotBlocks action to view all block indexes and block tokens of blocks in a snapshot. Or use the ListChangedBlocks action to view only the block indexes and block tokens of blocks that are different between two snapshots of the same volume and snapshot lineage. These actions help you identify the block tokens and block indexes of blocks for which you might want to get data.
-
Use the GetSnapshotBlock action, and specify the block index and block token of the block for which you want to get data.
Note
You can't use EBS direct APIs with archived snapshots.
The following examples show how to read snapshots using the EBS direct APIs.
Topics
List blocks in a snapshot
The following list-snapshot-blockssnap-0987654321. The --starting-block-index parameter
limits the results to block indexes greater than 1000, and the
--max-results parameter limits the results to the first 100
blocks.
aws ebs list-snapshot-blocks --snapshot-idsnap-0987654321--starting-block-index1000--max-results100
The following example response for the previous command lists the block indexes and
block tokens in the snapshot. Use the get-snapshot-block command and
specify the block index and block token of the block for which you want to get data. The
block tokens are valid until the expiry time listed.
{
"Blocks": [
{
"BlockIndex": 1001,
"BlockToken": "AAABAV3/PNhXOynVdMYHUpPsetaSvjLB1dtIGfbJv5OJ0sX855EzGTWos4a4"
},
{
"BlockIndex": 1002,
"BlockToken": "AAABATGQIgwr0WwIuqIMjCA/Sy7e/YoQFZsHejzGNvjKauzNgzeI13YHBfQB"
},
{
"BlockIndex": 1007,
"BlockToken": "AAABAZ9CTuQtUvp/dXqRWw4d07eOgTZ3jvn6hiW30W9duM8MiMw6yQayzF2c"
},
{
"BlockIndex": 1012,
"BlockToken": "AAABAQdzxhw0rVV6PNmsfo/YRIxo9JPR85XxPf1BLjg0Hec6pygYr6laE1p0"
},
{
"BlockIndex": 1030,
"BlockToken": "AAABAaYvPax6mv+iGWLdTUjQtFWouQ7Dqz6nSD9L+CbXnvpkswA6iDID523d"
},
{
"BlockIndex": 1031,
"BlockToken": "AAABATgWZC0XcFwUKvTJbUXMiSPg59KVxJGL+BWBClkw6spzCxJVqDVaTskJ"
},
...
],
"ExpiryTime": 1576287332.806,
"VolumeSize": 32212254720,
"BlockSize": 524288
}List blocks that are different between two snapshots
Keep the following in mind when making paginated requests to list the changed blocks between two snapshots:
-
The response can include one or more empty
ChangedBlocksarrays. For example:-
Snapshot 1 — full snapshot with 1000 blocks with block indexes
0-999. -
Snapshot 2 — incremental snapshot with only one changed block with block index
999.
Listing the changed blocks for these snapshots with
StartingBlockIndex = 0andMaxResults = 100returns an empty array ofChangedBlocks. You must request the remaining results usingnextTokenuntil the changed block is returned in the tenth result set, which includes blocks with block indexes900-999. -
-
The response can skip unwritten blocks in the snapshots. For example:
-
Snapshot 1 — full snapshot with 1000 blocks with block indexes
2000-2999. -
Snapshot 2 — incremental snapshot with only one changed block with block index
2000.
Listing the changed blocks for these snapshots with
StartingBlockIndex = 0andMaxResults = 100, the response skips block indexes0-1999and includes block index2000. The response will not include emptyChangedBlocksarrays. -
The following list-changed-blockssnap-1234567890 and snap-0987654321. The
--starting-block-index parameter limits the results to block indexes
greater than 0, and the --max-results parameter limits the
results to the first 500 blocks..
aws ebs list-changed-blocks --first-snapshot-idsnap-1234567890--second-snapshot-idsnap-0987654321--starting-block-index0--max-results500
The following example response for the previous command shows that block indexes 0, 6000, 6001, 6002, and 6003 are different between the two snapshots. Additionally, block indexes 6001, 6002, and 6003 exist only in the first snapshot ID specified, and not in the second snapshot ID because there is no second block token listed in the response.
Use the get-snapshot-block command and specify the block index and
block token of the block for which you want to get data. The block tokens are valid
until the expiry time listed.
{
"ChangedBlocks": [
{
"BlockIndex": 0,
"FirstBlockToken": "AAABAVahm9SO60Dyi0ORySzn2ZjGjW/KN3uygGlS0QOYWesbzBbDnX2dGpmC",
"SecondBlockToken": "AAABAf8o0o6UFi1rDbSZGIRaCEdDyBu9TlvtCQxxoKV8qrUPQP7vcM6iWGSr"
},
{
"BlockIndex": 6000,
"FirstBlockToken": "AAABAbYSiZvJ0/R9tz8suI8dSzecLjN4kkazK8inFXVintPkdaVFLfCMQsKe",
"SecondBlockToken": "AAABAZnqTdzFmKRpsaMAsDxviVqEI/3jJzI2crq2eFDCgHmyNf777elD9oVR"
},
{
"BlockIndex": 6001,
"FirstBlockToken": "AAABASBpSJ2UAD3PLxJnCt6zun4/T4sU25Bnb8jB5Q6FRXHFqAIAqE04hJoR"
},
{
"BlockIndex": 6002,
"FirstBlockToken": "AAABASqX4/NWjvNceoyMUljcRd0DnwbSwNnes1UkoP62CrQXvn47BY5435aw"
},
{
"BlockIndex": 6003,
"FirstBlockToken": "AAABASmJ0O5JxAOce25rF4P1sdRtyIDsX12tFEDunnePYUKOf4PBROuICb2A"
},
...
],
"ExpiryTime": 1576308931.973,
"VolumeSize": 32212254720,
"BlockSize": 524288,
"NextToken": "AAADARqElNng/sV98CYk/bJDCXeLJmLJHnNSkHvLzVaO0zsPH/QM3Bi3zF//O6Mdi/BbJarBnp8h"
}Get block data from a snapshot
The following get-snapshot-block6001 with block token
AAABASBpSJ2UAD3PLxJnCt6zun4/T4sU25Bnb8jB5Q6FRXHFqAIAqE04hJoR, in snapshot
snap-1234567890. The binary data is output to the
data file in the C:\Temp directory on a Windows
computer. If you run the command on a Linux or Unix computer, replace the output path
with /tmp/data to output the data to the data file in
the /tmp directory.
aws ebs get-snapshot-block --snapshot-idsnap-1234567890--block-index6001--block-tokenAAABASBpSJ2UAD3PLxJnCt6zun4/T4sU25Bnb8jB5Q6FRXHFqAIAqE04hJoRC:/Temp/data
The following example response for the previous command shows the size of the data returned, the checksum to validate the data, and the algorithm of the checksum. The binary data is automatically saved to the directory and file you specified in the request command.
{
"DataLength": "524288",
"Checksum": "cf0Y6/Fn0oFa4VyjQPOa/iD0zhTflPTKzxGv2OKowXc=",
"ChecksumAlgorithm": "SHA256"
}