EBS direct APIs

(1)

EBS direct APIs

API Reference

API Version 2019-11-02

(2)

EBS direct APIs: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

You can use the Amazon Elastic Block Store (Amazon EBS) direct APIs to create Amazon EBS snapshots, write data directly to your snapshots, read data on your snapshots, and identify the differences or changes between two snapshots. If you’re an independent software vendor (ISV) who offers backup services for Amazon EBS, the EBS direct APIs make it more efficient and cost-effective to track

incremental changes on your Amazon EBS volumes through snapshots. This can be done without having to create new volumes from snapshots, and then use Amazon Elastic Compute Cloud (Amazon EC2) instances to compare the diﬀerences.

You can create incremental snapshots directly from data on-premises into volumes and the cloud to use for quick disaster recovery. With the ability to write and read snapshots, you can write your on-premises data to an snapshot during a disaster. Then after recovery, you can restore it back to AWS or on-premises from the snapshot. You no longer need to build and maintain complex mechanisms to copy data to and from Amazon EBS.

This API reference provides detailed information about the actions, data types, parameters, and errors of the EBS direct APIs. For more information about the elements that make up the EBS direct APIs, and examples of how to use them eﬀectively, see Accessing the Contents of an Amazon EBS Snapshot in the Amazon Elastic Compute Cloud User Guide. For more information about the supported AWS Regions, endpoints, and service quotas for the EBS direct APIs, see Amazon Elastic Block Store Endpoints and Quotas in the AWS General Reference.

This document was last published on March 6, 2022.

(6)

Actions

The following actions are supported:

• CompleteSnapshot (p. 3)

• GetSnapshotBlock (p. 6)

• ListChangedBlocks (p. 9)

• ListSnapshotBlocks (p. 13)

• PutSnapshotBlock (p. 16)

• StartSnapshot (p. 20)

(7)

CompleteSnapshot

Seals and completes the snapshot after all of the required blocks of data have been written to it.

Completing the snapshot changes the status to completed. You cannot write new blocks to a snapshot after it has been completed.

Request Syntax

POST /snapshots/completion/snapshotId HTTP/1.1 x-amz-ChangedBlocksCount: ChangedBlocksCount x-amz-Checksum: Checksum

x-amz-Checksum-Algorithm: ChecksumAlgorithm

x-amz-Checksum-Aggregation-Method: ChecksumAggregationMethod

URI Request Parameters

The request uses the following URI parameters.

ChangedBlocksCount (p. 3)

The number of blocks that were written to the snapshot.

Valid Range: Minimum value of 0.

Required: Yes Checksum (p. 3)

An aggregated Base-64 SHA256 checksum based on the checksums of each written block.

To generate the aggregated checksum using the linear aggregation method, arrange the checksums for each written block in ascending order of their block index, concatenate them to form a single string, and then generate the checksum on the entire string using the SHA256 algorithm.

Length Constraints: Maximum length of 64.

Pattern: ^[A-Za-z0-9+/=]+$

ChecksumAggregationMethod (p. 3)

The aggregation method used to generate the checksum. Currently, the only supported aggregation method is LINEAR.

Pattern: ^[A-Za-z0-9]+$

Valid Values: LINEAR ChecksumAlgorithm (p. 3)

The algorithm used to generate the checksum. Currently, the only supported algorithm is SHA256.

Valid Values: SHA256

(8)

Request Body

snapshotId (p. 3)

The ID of the snapshot.

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: ^snap-[0-9a-f]+$

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 202

Content-type: application/json { "Status": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 202 response.

The following data is returned in JSON format by the service.

Status (p. 4)

The status of the snapshot.

Type: String

Valid Values: completed | pending | error

Errors

For information about the errors that are common to all actions, see Common Errors (p. 32).

AccessDeniedException

You do not have suﬃcient access to perform this action.

HTTP Status Code: 403 InternalServerException

An internal error has occurred.

HTTP Status Code: 500 RequestThrottledException

The number of API requests has exceed the maximum allowed API request throttling limit.

(9)

GetSnapshotBlock

Returns the data in a block in an Amazon Elastic Block Store snapshot.

Request Syntax

GET /snapshots/snapshotId/blocks/blockIndex?blockToken=BlockToken HTTP/1.1

URI Request Parameters

blockIndex (p. 6)

The block index of the block in which to read the data. A block index is a logical index in units of 512 KiB blocks. To identify the block index, divide the logical offset of the data in the logical volume by the block size (logical offset of data/524288). The logical offset of the data must be 512 KiB aligned.

Required: Yes BlockToken (p. 6)

The block token of the block from which to get data. You can obtain the BlockToken by running the ListChangedBlocks or ListSnapshotBlocks operations.

Required: Yes snapshotId (p. 6)

The ID of the snapshot containing the block from which to get data.

Important

If the speciﬁed snapshot is encrypted, you must have permission to use the KMS key that was used to encrypt the snapshot. For more information, see Using encryption in the Amazon Elastic Compute Cloud User Guide.

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

(11)

Response Elements

x-amz-Data-Length: DataLength x-amz-Checksum: Checksum

x-amz-Checksum-Algorithm: ChecksumAlgorithm BlockData

Response Elements

The response returns the following HTTP headers.

Checksum (p. 6)

The checksum generated for the block, which is Base64 encoded.

ChecksumAlgorithm (p. 6)

The algorithm used to generate the checksum for the block, such as SHA256.

Valid Values: SHA256 DataLength (p. 6)

The size of the data in the block.

The response returns the following as the HTTP body.

BlockData (p. 6)

The data content of the block.

Errors

(12)

ListChangedBlocks

Returns information about the blocks that are diﬀerent between two Amazon Elastic Block Store snapshots of the same volume/snapshot lineage.

Request Syntax

GET /snapshots/secondSnapshotId/changedblocks?

firstSnapshotId=FirstSnapshotId&maxResults=MaxResults&pageToken=NextToken&startingBlockIndex=StartingBlockIndex HTTP/1.1

URI Request Parameters

FirstSnapshotId (p. 9)

The ID of the ﬁrst snapshot to use for the comparison.

Important

The FirstSnapshotID parameter must be speciﬁed with a SecondSnapshotId parameter; otherwise, an error occurs.

MaxResults (p. 9)

The maximum number of blocks to be returned by the request.

Even if additional blocks can be retrieved from the snapshot, the request can return less blocks than MaxResults or an empty array of blocks.

To retrieve the next set of blocks from the snapshot, make another request with the returned NextToken value. The value of NextToken is null when there are no more blocks to return.

Valid Range: Minimum value of 100. Maximum value of 10000.

NextToken (p. 9)

The token to request the next page of results.

If you specify NextToken, then StartingBlockIndex is ignored.

secondSnapshotId (p. 9)

The ID of the second snapshot to use for the comparison.

Important

The SecondSnapshotId parameter must be speciﬁed with a FirstSnapshotID parameter; otherwise, an error occurs.

Required: Yes

(14)

Request Body

StartingBlockIndex (p. 9)

The block index from which the comparison should start.

The list in the response will start from this block index or the next valid block index in the snapshots.

Request Body

Response Syntax

HTTP/1.1 200

Content-type: application/json { "BlockSize": number,

"ChangedBlocks": [ {

"BlockIndex": number, "FirstBlockToken": "string", "SecondBlockToken": "string"

} ],

"ExpiryTime": number, "NextToken": "string", "VolumeSize": number }

Response Elements

BlockSize (p. 10)

The size of the blocks in the snapshot, in bytes.

Type: Integer ChangedBlocks (p. 10)

An array of objects containing information about the changed blocks.

Type: Array of ChangedBlock (p. 28) objects ExpiryTime (p. 10)

The time when the BlockToken expires.

Type: Timestamp NextToken (p. 10)

The token to use to retrieve the next page of results. This value is null when there are no more results to return.

(15)

Errors

Type: String

VolumeSize (p. 10)

The size of the volume in GB.

Type: Long

Errors

ListSnapshotBlocks

Returns information about the blocks in an Amazon Elastic Block Store snapshot.

Request Syntax

GET /snapshots/snapshotId/blocks?

maxResults=MaxResults&pageToken=NextToken&startingBlockIndex=StartingBlockIndex HTTP/1.1

URI Request Parameters

MaxResults (p. 13)

The maximum number of blocks to be returned by the request.

Even if additional blocks can be retrieved from the snapshot, the request can return less blocks than MaxResults or an empty array of blocks.

To retrieve the next set of blocks from the snapshot, make another request with the returned NextToken value. The value of NextToken is null when there are no more blocks to return.

NextToken (p. 13)

The token to request the next page of results.

The ID of the snapshot from which to get block indexes and block tokens.

Required: Yes

StartingBlockIndex (p. 13)

The block index from which the list should start. The list in the response will start from this block index or the next valid block index in the snapshot.

Request Body

(18)

Response Syntax

HTTP/1.1 200

Content-type: application/json {

"Blocks": [ {

"BlockIndex": number, "BlockToken": "string"

} ],

"BlockSize": number, "ExpiryTime": number, "NextToken": "string", "VolumeSize": number }

Response Elements

Blocks (p. 14)

An array of objects containing information about the blocks.

Type: Array of Block (p. 27) objects BlockSize (p. 14)

Type: Integer ExpiryTime (p. 14)

The time when the BlockToken expires.

Type: Timestamp NextToken (p. 14)

The token to use to retrieve the next page of results. This value is null when there are no more results to return.

Type: String

VolumeSize (p. 14)

The size of the volume in GB.

Type: Long

(19)

Errors

PutSnapshotBlock

Writes a block of data to a snapshot. If the speciﬁed block contains data, the existing data is overwritten.

The target snapshot must be in the pending state.

Data written to a snapshot must be aligned with 512-KiB sectors.

Request Syntax

PUT /snapshots/snapshotId/blocks/blockIndex HTTP/1.1 x-amz-Data-Length: DataLength

x-amz-Progress: Progress x-amz-Checksum: Checksum

x-amz-Checksum-Algorithm: ChecksumAlgorithm BlockData

URI Request Parameters

blockIndex (p. 16)

The block index of the block in which to write the data. A block index is a logical index in units of 512 KiB blocks. To identify the block index, divide the logical offset of the data in the logical volume by the block size (logical offset of data/524288). The logical offset of the data must be 512 KiB aligned.

Required: Yes Checksum (p. 16)

A Base64-encoded SHA256 checksum of the data. Only SHA256 checksums are supported.

Required: Yes

The algorithm used to generate the checksum. Currently, the only supported algorithm is SHA256.

Valid Values: SHA256 Required: Yes

DataLength (p. 16)

The size of the data to write to the block, in bytes. Currently, the only supported size is 524288 bytes.

Valid values: 524288

(21)

Request Body

Required: Yes Progress (p. 16)

The progress of the write process, as a percentage.

Important

If the speciﬁed snapshot is encrypted, you must have permission to use the KMS key that was used to encrypt the snapshot. For more information, see Using encryption in the Amazon Elastic Compute Cloud User Guide..

Required: Yes

Request Body

The request accepts the following binary data.

BlockData (p. 16)

The data to write to the block.

The block data is not signed as part of the Signature Version 4 signing process. As a result, you must generate and provide a Base64-encoded SHA256 checksum for the block data using the x-amz- Checksum header. Also, you must specify the checksum algorithm using the x-amz-Checksum- Algorithm header. The checksum that you provide is part of the Signature Version 4 signing process.

It is validated against a checksum generated by Amazon EBS to ensure the validity and authenticity of the data. If the checksums do not correspond, the request fails. For more information, see Using checksums with the EBS direct APIs in the Amazon Elastic Compute Cloud User Guide.

Required: Yes

Response Syntax

HTTP/1.1 201

x-amz-Checksum: Checksum

x-amz-Checksum-Algorithm: ChecksumAlgorithm

Response Elements

The response returns the following HTTP headers.

Checksum (p. 17)

The SHA256 checksum generated for the block data by Amazon EBS.

(22)

Errors

The algorithm used by Amazon EBS to generate the checksum.

Valid Values: SHA256

Errors

StartSnapshot

Creates a new Amazon EBS snapshot. The new snapshot enters the pending state after the request completes.

After creating the snapshot, use PutSnapshotBlock to write blocks of data to the snapshot.

Request Syntax

POST /snapshots HTTP/1.1 Content-type: application/json { "ClientToken": "string", "Description": "string", "Encrypted": boolean, "KmsKeyArn": "string",

"ParentSnapshotId": "string", "Tags": [

{

"Key": "string", "Value": "string"

} ],

"Timeout": number, "VolumeSize": number }

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

ClientToken (p. 20)

A unique, case-sensitive identiﬁer that you provide to ensure the idempotency of the request.

Idempotency ensures that an API request completes only once. With an idempotent request, if the original request completes successfully. The subsequent retries with the same client token return the result from the original successful request and they have no additional eﬀect.

If you do not specify a client token, one is automatically generated by the AWS SDK.

For more information, see Idempotency for StartSnapshot API in the Amazon Elastic Compute Cloud User Guide.

Type: String

Pattern: ^[\S]+$

Required: No Description (p. 20)

A description for the snapshot.

(25)

Request Body

Type: String

Pattern: ^[\S\s]+$

Required: No Encrypted (p. 20)

Indicates whether to encrypt the snapshot.

You can't specify Encrypted and ParentSnapshotId in the same request. If you specify both parameters, the request fails with ValidationException.

The encryption status of the snapshot depends on the values that you specify for Encrypted, KmsKeyArn, and ParentSnapshotId, and whether your AWS account is enabled for encryption by default. For more information, see Using encryption in the Amazon Elastic Compute Cloud User Guide.

Important

To create an encrypted snapshot, you must have permission to use the KMS key. For more information, see Permissions to use AWS Key Management Service keys in the Amazon Elastic Compute Cloud User Guide.

Type: Boolean Required: No KmsKeyArn (p. 20)

The Amazon Resource Name (ARN) of the AWS Key Management Service (AWS KMS) key to be used to encrypt the snapshot.

Important

To create an encrypted snapshot, you must have permission to use the KMS key. For more information, see Permissions to use AWS Key Management Service keys in the Amazon Elastic Compute Cloud User Guide.

Type: String

Pattern: arn:aws[a-z\-]*:kms:.*:[0-9]{12}:key/.*

Required: No

ParentSnapshotId (p. 20)

The ID of the parent snapshot. If there is no parent snapshot, or if you are creating the ﬁrst snapshot for an on-premises volume, omit this parameter.

You can't specify ParentSnapshotId and Encrypted in the same request. If you specify both parameters, the request fails with ValidationException.

(26)

Response Syntax

Important

If you specify an encrypted parent snapshot, you must have permission to use the KMS key that was used to encrypt the parent snapshot. For more information, see Permissions to use AWS Key Management Service keys in the Amazon Elastic Compute Cloud User Guide.

Type: String

Required: No Tags (p. 20)

The tags to apply to the snapshot.

Type: Array of Tag (p. 29) objects Required: No

Timeout (p. 20)

The amount of time (in minutes) after which the snapshot is automatically cancelled if:

• No blocks are written to the snapshot.

• The snapshot is not completed after writing the last block of data.

If no value is speciﬁed, the timeout defaults to 60 minutes.

Type: Integer

Required: No VolumeSize (p. 20)

The size of the volume, in GiB. The maximum size is 65536 GiB (64 TiB).

Type: Long

Required: Yes

Response Syntax

HTTP/1.1 201

Content-type: application/json {

"BlockSize": number, "Description": "string", "KmsKeyArn": "string", "OwnerId": "string",

"ParentSnapshotId": "string", "SnapshotId": "string", "StartTime": number, "Status": "string", "Tags": [

{

(27)

Response Elements

"Key": "string", "Value": "string"

} ],

"VolumeSize": number }

Response Elements

BlockSize (p. 22)

Type: Integer Description (p. 22)

The description of the snapshot.

Type: String

Pattern: ^[\S\s]+$

KmsKeyArn (p. 22)

The Amazon Resource Name (ARN) of the AWS Key Management Service (AWS KMS) key used to encrypt the snapshot.

Type: String

Pattern: arn:aws[a-z\-]*:kms:.*:[0-9]{12}:key/.*

OwnerId (p. 22)

The AWS account ID of the snapshot owner.

Type: String

Pattern: \S+

ParentSnapshotId (p. 22)

The ID of the parent snapshot.

Type: String

SnapshotId (p. 22)

(28)

Errors

Type: String

StartTime (p. 22)

The timestamp when the snapshot was created.

Type: Timestamp Status (p. 22)

The status of the snapshot.

Type: String

Valid Values: completed | pending | error Tags (p. 22)

The tags applied to the snapshot. You can specify up to 50 tags per snapshot. For more information, see Tagging your Amazon EC2 resources in the Amazon Elastic Compute Cloud User Guide.

Type: Array of Tag (p. 29) objects VolumeSize (p. 22)

The size of the volume, in GiB.

Type: Long

Errors

ConcurrentLimitExceededException

You have reached the limit for concurrent API requests. For more information, see Optimizing performance of the EBS direct APIs in the Amazon Elastic Compute Cloud User Guide.

HTTP Status Code: 400 ConﬂictException

The request uses the same client token as a previous, but non-identical request.

(29)

Data Types

The EBS direct APIs API contains several data types that various actions use. This section describes each data type in detail.

Note

The order of each element in a data type structure is not guaranteed. Applications should not assume a particular order.

The following data types are supported:

• Block (p. 27)

• ChangedBlock (p. 28)

• Tag (p. 29)

(31)

Block

A block of data in an Amazon Elastic Block Store snapshot.

ChangedBlock

A block of data in an Amazon Elastic Block Store snapshot that is diﬀerent from another snapshot of the same volume/snapshot lineage.

Tag

Describes a tag.

Common Parameters

The following list contains the parameters that all actions use for signing Signature Version 4 requests with a query string. Any action-speciﬁc parameters are listed in the topic for that action. For more information about Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web Services General Reference.

Action

The action to be performed.

Type: string Required: Yes Version

The API version that the request is written for, expressed in the format YYYY-MM-DD.

Type: string Required: Yes X-Amz-Algorithm

The hash algorithm that you used to create the request signature.

Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header.

Type: string

Valid Values: AWS4-HMAC-SHA256 Required: Conditional

X-Amz-Credential

The credential scope value, which is a string that includes your access key, the date, the region you are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request.

For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web Services General Reference.

Type: string

Required: Conditional X-Amz-Date

The date that is used to create the signature. The format must be ISO 8601 basic format (YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:

20120325T120000Z.

Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for signing requests. If the Date header is speciﬁed in the ISO 8601 basic format, X-Amz-Date is

(35)

not required. When X-Amz-Date is used, it always overrides the value of the Date header. For more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General Reference.

Type: string

Required: Conditional X-Amz-Security-Token

The temporary security token that was obtained through a call to AWS Security Token Service (AWS STS). For a list of services that support temporary security credentials from AWS Security Token Service, go to AWS Services That Work with IAM in the IAM User Guide.

Condition: If you're using temporary security credentials from the AWS Security Token Service, you must include the security token.

Type: string

Required: Conditional X-Amz-Signature

Speciﬁes the hex-encoded signature that was calculated from the string to sign and the derived signing key.

Type: string

Required: Conditional X-Amz-SignedHeaders

Speciﬁes all the HTTP headers that were included as part of the canonical request. For more information about specifying signed headers, see Task 1: Create a Canonical Request For Signature Version 4 in the Amazon Web Services General Reference.

Type: string

Required: Conditional

(36)

Common Errors

This section lists the errors common to the API actions of all AWS services. For errors speciﬁc to an API action for this service, see the topic for that API action.

HTTP Status Code: 400 IncompleteSignature

The request signature does not conform to AWS standards.

HTTP Status Code: 400 InternalFailure

The request processing has failed because of an unknown error, exception or failure.

HTTP Status Code: 500 InvalidAction

The action or operation requested is invalid. Verify that the action is typed correctly.

HTTP Status Code: 400 InvalidClientTokenId

The X.509 certiﬁcate or AWS access key ID provided does not exist in our records.

HTTP Status Code: 403 InvalidParameterCombination

Parameters that must not be used together were used together.

HTTP Status Code: 400 InvalidParameterValue

An invalid or out-of-range value was supplied for the input parameter.

HTTP Status Code: 400 InvalidQueryParameter

The AWS query string is malformed or does not adhere to AWS standards.

HTTP Status Code: 400 MalformedQueryString

The query string contains a syntax error.

HTTP Status Code: 404 MissingAction

The request is missing an action or a required parameter.

(37)

MissingAuthenticationToken

The request must contain either a valid (registered) AWS access key ID or X.509 certiﬁcate.

HTTP Status Code: 403 MissingParameter

A required parameter for the speciﬁed action is not supplied.

HTTP Status Code: 400 NotAuthorized

You do not have permission to perform this action.

HTTP Status Code: 400 OptInRequired

The AWS access key ID needs a subscription for the service.

HTTP Status Code: 403 RequestExpired

The request reached the service more than 15 minutes after the date stamp on the request or more than 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp on the request is more than 15 minutes in the future.

HTTP Status Code: 400 ServiceUnavailable

The request has failed due to a temporary failure of the server.

HTTP Status Code: 503 ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 400 ValidationError

The input fails to satisfy the constraints speciﬁed by an AWS service.

EBS direct APIs

EBS direct APIs

API Reference

API Version 2019-11-02

EBS direct APIs: API Reference

Table of Contents

Welcome

Actions

CompleteSnapshot

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

GetSnapshotBlock

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

ListChangedBlocks

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

ListSnapshotBlocks

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

PutSnapshotBlock

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

StartSnapshot

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

Data Types

Block

Contents

See Also

ChangedBlock

Contents

See Also

Tag

Contents

See Also

Common Parameters

Common Errors