# Use EBS direct APIs to access the contents of an EBS snapshot
You can use the Amazon Elastic Block Store (Amazon EBS) direct APIs to create 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 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 differences.
You can create incremental snapshots directly from data on-premises into EBS 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 EBS 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 user guide provides an overview of the elements that make up the EBS direct APIs, and examples of how to use them effectively. For more information about the actions, data types, parameters, and errors of the APIs, see the [EBS direct APIs reference](https://docs.aws.amazon.com/ebs/latest/APIReference/). For more information about the supported AWS Regions, endpoints, and service quotas for the EBS direct APIs, see [Amazon EBS endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/ebs-service.html) in the *AWS General Reference*.
**Topics**
+ [Pricing](ebsapi-pricing.md)
+ [Concepts](ebsapi-elements.md)
+ [Control access](ebsapi-permissions.md)
+ [Read snapshots](readsnapshots.md)
+ [Write snapshots](writesnapshots.md)
+ [Encryption outcomes](ebsapis-using-encryption.md)
+ [Validate snapshot data](ebsapis-using-checksums.md)
+ [Ensure idempotency](ebs-direct-api-idempotency.md)
+ [Error retries](error-retries.md)
+ [Optimize performance](ebsapi-performance.md)
+ [Service endpoints](using-endpoints.md)
+ [SDK code examples](sdk.md)
+ [Interface VPC endpoints](ebs-apis-vpc-endpoints.md)
+ [CloudTrail logs](logging-ebs-apis-using-cloudtrail.md)
+ [FAQs](ebsapi-faq.md)
# Pricing for EBS direct APIs
## Pricing for APIs
The price that you pay to use the EBS direct APIs depends on the requests you make. For more information, see [Amazon EBS pricing](https://aws.amazon.com/ebs/pricing/).
+ **ListChangedBlocks** and ListSnapshotBlocks APIs are charged per request. For example, if you make 100,000 ListSnapshotBlocks API requests in a Region that charges \$10.0006 per 1,000 requests, you will be charged \$10.06 (\$10.0006 per 1,000 requests x 100).
+ **GetSnapshotBlock** is charged per block returned. For example, if you make 100,000 GetSnapshotBlock API requests in a Region that charges \$10.003 per 1,000 blocks returned, you will be charged \$10.30 (\$10.003 per 1,000 blocks returned x 100).
+ **PutSnapshotBlock** is charged per block written. For example, if you make 100,000 PutSnapshotBlock API requests in a Region that charges \$10.006 per 1,000 blocks written, you will be charged \$10.60 (\$10.006 per 1,000 blocks written x 100).
## Networking costs
**Data transfer costs**
Data transferred directly between EBS direct APIs and Amazon EC2 instances in the same AWS Region is free when using [ non-FIPS endpoints](https://docs.aws.amazon.com/general/latest/gr/ebs-service.html#ebs_direct_apis). For more information, see [AWS service endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html). If other AWS services are in the path of your data transfer, you will be charged their associated data processing costs. These services include, but are not limited to, PrivateLink endpoints, NAT Gateway and Transit Gateway.
**VPC interface endpoints**
If you are using EBS direct APIs from Amazon EC2 instances or AWS Lambda functions in private subnets, you can use VPC interface endpoints, instead of using NAT gateways, to reduce network data transfer costs. For more information, see [Create a private connection between a VPC and EBS direct APIs](ebs-apis-vpc-endpoints.md).
# Concepts for EBS direct APIs
The following are the key concepts that you should understand before getting started with the EBS direct APIs.
## Snapshots
Snapshots are the primary means to back up data from your EBS volumes. With the EBS direct APIs, you can also back up data from your on-premises disks to snapshots. To save storage costs, successive snapshots are incremental, containing only the volume data that changed since the previous snapshot. For more information, see [Amazon EBS snapshots](ebs-snapshots.md).
**Note**
EBS direct APIs does not support public snapshots and local snapshots on AWS Outposts.
## Blocks
A block is a fragment of data within a snapshot. Each snapshot can contain thousands of blocks. All blocks in a snapshot are of a fixed size.
## Block indexes
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.
## Block tokens
A block token is the identifying hash of a block within a snapshot, and it is used to locate the block data. Block tokens returned by EBS direct APIs are temporary. They change on the expiry timestamp specified for them, or if you run another ListSnapshotBlocks or ListChangedBlocks request for the same snapshot.
## Checksum
A checksum is a small-sized datum derived from a block of data for the purpose of detecting errors that were introduced during its transmission or storage. The EBS direct APIs use checksums to validate data integrity. When you read data from an EBS snapshot, the service provides Base64-encoded SHA256 checksums for each block of data transmitted, which you can use for validation. When you write data to an EBS snapshot, you must provide a Base64 encoded SHA256 checksum for each block of data transmitted. The service validates the data received using the checksum provided. For more information, see [Use EBS direct APIs checksums to validate snapshot data](ebsapis-using-checksums.md) later in this guide.
## Encryption
Encryption protects your data by converting it into unreadable code that can be deciphered only by people who have access to the KMS key used to encrypt it. You can use the EBS direct APIs to read and write encrypted snapshots, but there are some limitations. For more information, see [Encryption outcomes for EBS direct APIs](ebsapis-using-encryption.md) later in this guide.
## API actions
The EBS direct APIs consists of six actions. There are three read actions and three write actions. The read actions are:
+ **ListSnapshotBlocks** — returns the block indexes and block tokens of blocks in the specified snapshot
+ **ListChangedBlocks** — returns the block indexes and block tokens of blocks that are different between two specified snapshots of the same volume and snapshot lineage.
+ **GetSnapshotBlock** — returns the data in a block for the specified snapshot ID, block index, and block token.
The write actions are:
+ **StartSnapshot** — starts a snapshot, either as an incremental snapshot of an existing one or as a new snapshot. The started snapshot remains in a pending state until it is completed using the CompleteSnapshot action.
+ **PutSnapshotBlock** — adds data to a started snapshot in the form of individual blocks. You must specify a Base64-encoded SHA256 checksum for the block of data transmitted. The service validates the checksum after the transmission is completed. The request fails if the checksum computed by the service doesn’t match what you specified.
+ **CompleteSnapshot** — completes a started snapshot that is in a pending state. The snapshot is then changed to a completed state.
## Signature Version 4 signing
Signature Version 4 is the process to add authentication information to AWS requests sent by HTTP. For security, most requests to AWS must be signed with an access key, which consists of an access key ID and secret access key. These two keys are commonly referred to as your security credentials. For information about how to obtain credentials for your account, see [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html).
If you intend to manually create HTTP requests, you must learn how to sign them. When you use the AWS Command Line Interface (AWS CLI) or one of the AWS SDKs to make requests to AWS, these tools automatically sign the requests for you with the access key that you specify when you configure the tools. When you use these tools, you don't need to learn how to sign requests yourself.
For more information, see [Signing AWS API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) in the *IAM User Guide*.
# Control access to EBS direct APIs using IAM
A user must have the following policies to use the EBS direct APIs. For more information, see [ Changing permissions for a user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html).
For more information about the EBS direct APIs resources, actions, and condition context keys for use in IAM permission policies, see [ Actions, resources, and condition keys for Amazon Elastic Block Store](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonelasticblockstore.html) in the *Service Authorization Reference*.
**Important**
Be cautious when assigning the following policies to users. By assigning these policies, you might give access to a user who is denied access to the same resource through the Amazon EC2 APIs, such as the CopySnapshot or CreateVolume actions.
## Permissions to read snapshots
The following policy allows the *read* EBS direct APIs to be used on all snapshots in a specific AWS Region. In the policy, replace ** with the Region of the snapshot.
The following policy allows the *read* EBS direct APIs to be used on snapshots with a specific key-value tag. In the policy, replace ** with the key value of the tag, and ** with the value of the tag.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ebs:ListSnapshotBlocks",
"ebs:ListChangedBlocks",
"ebs:GetSnapshotBlock"
],
"Resource": "arn:aws:ec2:*::snapshot/*",
"Condition": {
"StringEqualsIgnoreCase": {
"aws:ResourceTag/": ""
}
}
}
]
}
```
------
The following policy allows all of the *read* EBS direct APIs to be used on all snapshots in the account only within a specific time range. This policy authorizes use of the EBS direct APIs based on the `aws:CurrentTime` global condition key. In the policy, be sure to replace the date and time range shown with the date and time range for your policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ebs:ListSnapshotBlocks",
"ebs:ListChangedBlocks",
"ebs:GetSnapshotBlock"
],
"Resource": "arn:aws:ec2:*::snapshot/*",
"Condition": {
"DateGreaterThan": {
"aws:CurrentTime": "2018-05-29T00:00:00Z"
},
"DateLessThan": {
"aws:CurrentTime": "2020-05-29T23:59:59Z"
}
}
}
]
}
```
------
For more information, see [Changing permissions for a user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html) in the *IAM User Guide*.
## Permissions to write snapshots
The following policy allows the *write* EBS direct APIs to be used on all snapshots in a specific AWS Region. In the policy, replace ** with the Region of the snapshot.
The following policy allows the *write* EBS direct APIs to be used on snapshots with a specific key-value tag. In the policy, replace ** with the key value of the tag, and ** with the value of the tag.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ebs:StartSnapshot",
"ebs:PutSnapshotBlock",
"ebs:CompleteSnapshot"
],
"Resource": "arn:aws:ec2:*::snapshot/*",
"Condition": {
"StringEqualsIgnoreCase": {
"aws:ResourceTag/": ""
}
}
}
]
}
```
------
The following policy allows all of the EBS direct APIs to be used. It also allows the `StartSnapshot` action only if a parent snapshot ID is specified. Therefore, this policy blocks the ability to start new snapshots without using a parent snapshot.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ebs:*",
"Resource": "*",
"Condition": {
"StringEquals": {
"ebs:ParentSnapshot": "arn:aws:ec2:*::snapshot/*"
}
}
}
]
}
```
------
The following policy allows all of the EBS direct APIs to be used. It also allows only the `user` tag key to be created for a new snapshot. This policy also ensures that the user has access to create tags. The `StartSnapshot` action is the only action that can specify tags.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ebs:*",
"Resource": "*",
"Condition": {
"ForAllValues:StringEquals": {
"aws:TagKeys": "user"
}
}
},
{
"Effect": "Allow",
"Action": "ec2:CreateTags",
"Resource": "*"
}
]
}
```
------
The following policy allows all of the *write* EBS direct APIs to be used on all snapshots in the account only within a specific time range. This policy authorizes use of the EBS direct APIs based on the `aws:CurrentTime` global condition key. In the policy, be sure to replace the date and time range shown with the date and time range for your policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ebs:StartSnapshot",
"ebs:PutSnapshotBlock",
"ebs:CompleteSnapshot"
],
"Resource": "arn:aws:ec2:*::snapshot/*",
"Condition": {
"DateGreaterThan": {
"aws:CurrentTime": "2018-05-29T00:00:00Z"
},
"DateLessThan": {
"aws:CurrentTime": "2020-05-29T23:59:59Z"
}
}
}
]
}
```
------
For more information, see [Changing permissions for a user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html) in the *IAM User Guide*.
## Permissions to use AWS KMS keys
The following policy grants permission to decrypt an encrypted snapshot using a specific KMS key. It also grants permission to encrypt new snapshots using the default KMS key for EBS encryption. In the policy, replace ** with the Region of the KMS key, ** with the ID of the AWS account of the KMS key, and ** with the ID of the KMS key.
**Note**
By default, all principals in the account have access to the default AWS managed KMS key for Amazon EBS encryption, and they can use it for EBS encryption and decryption operations. If you are using a customer managed key, you must create a new key policy or modify the existing key policy for the customer managed key to grant the principal access to the customer managed key. For more information, see [Key policies in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) in the *AWS Key Management Service Developer Guide*.
**Tip**
To follow the principle of least privilege, do not allow full access to `kms:CreateGrant`. Instead, use the `kms:GrantIsForAWSResource` condition key to allow the user to create grants on the KMS key only when the grant is created on the user's behalf by an AWS service, as shown in the following example.
For more information, see [Changing permissions for a user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html) in the *IAM User Guide*.
# Read Amazon EBS snapshots with EBS direct APIs
The following steps describe how to use the EBS direct APIs to read snapshots:
1. 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.
1. 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
](#list-blocks)
+ [
## List blocks that are different between two snapshots
](#list-different-blocks)
+ [
## Get block data from a snapshot
](#get-block-data)
## List blocks in a snapshot
------
#### [ AWS CLI ]
The following [list-snapshot-blocks](https://docs.aws.amazon.com/cli/latest/reference/ebs/list-snapshot-blocks.html) example command returns the block indexes and block tokens of blocks that are in snapshot `snap-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-id snap-0987654321 --starting-block-index 1000 --max-results 100
```
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
}
```
------
#### [ AWS API ]
The following [ListSnapshotBlocks](https://docs.aws.amazon.com/ebs/latest/APIReference/API_ListSnapshotBlocks.html) example request returns the block indexes and block tokens of blocks that are in snapshot `snap-0acEXAMPLEcf41648`. The `startingBlockIndex` parameter limits the results to block indexes greater than `1000`, and the `maxResults` parameter limits the results to the first `100` blocks.
```
GET /snapshots/snap-0acEXAMPLEcf41648/blocks?maxResults=100&startingBlockIndex=1000 HTTP/1.1
Host: ebs.us-east-2.amazonaws.com
Accept-Encoding: identity
User-Agent:
X-Amz-Date: 20200617T231953Z
Authorization:
```
The following example response for the previous request lists the block indexes and block tokens in the snapshot. Use the GetSnapshotBlock action 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.
```
HTTP/1.1 200 OK
x-amzn-RequestId: d6e5017c-70a8-4539-8830-57f5557f3f27
Content-Type: application/json
Content-Length: 2472
Date: Wed, 17 Jun 2020 23:19:56 GMT
Connection: keep-alive
{
"BlockSize": 524288,
"Blocks": [
{
"BlockIndex": 0,
"BlockToken": "AAUBAcuWqOCnDNuKle11s7IIX6jp6FYcC/q8oT93913HhvLvA+3JRrSybp/0"
},
{
"BlockIndex": 1536,
"BlockToken": "AAUBAWudwfmofcrQhGVlLwuRKm2b8ZXPiyrgoykTRC6IU1NbxKWDY1pPjvnV"
},
{
"BlockIndex": 3072,
"BlockToken": "AAUBAV7p6pC5fKAC7TokoNCtAnZhqq27u6YEXZ3MwRevBkDjmMx6iuA6tsBt"
},
{
"BlockIndex": 3073,
"BlockToken": "AAUBAbqt9zpqBUEvtO2HINAfFaWToOwlPjbIsQOlx6JUN/0+iMQl0NtNbnX4"
},
...
],
"ExpiryTime": 1.59298379649E9,
"VolumeSize": 3
}
```
------
## 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 `ChangedBlocks` arrays. 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 = 0` and `MaxResults = 100` returns an empty array of `ChangedBlocks`. You must request the remaining results using `nextToken` until the changed block is returned in the tenth result set, which includes blocks with block indexes `900` - `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 = 0` and `MaxResults = 100`, the response skips block indexes `0` - `1999` and includes block index `2000`. The response will not include empty `ChangedBlocks` arrays.
------
#### [ AWS CLI ]
The following [list-changed-blocks](https://docs.aws.amazon.com/cli/latest/reference/ebs/list-changed-blocks.html) example command returns the block indexes and block tokens of blocks that are different between snapshots `snap-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-id snap-1234567890 --second-snapshot-id snap-0987654321 --starting-block-index 0 --max-results 500
```
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"
}
```
------
#### [ AWS API ]
The following [ListChangedBlocks](https://docs.aws.amazon.com/ebs/latest/APIReference/API_ListChangedBlocks.html) example request returns the block indexes and block tokens of blocks that are different between snapshots `snap-0acEXAMPLEcf41648` and `snap-0c9EXAMPLE1b30e2f`. The `startingBlockIndex` parameter limits the results to block indexes greater than `0`, and the `maxResults` parameter limits the results to the first `500` blocks.
```
GET /snapshots/snap-0c9EXAMPLE1b30e2f/changedblocks?firstSnapshotId=snap-0acEXAMPLEcf41648&maxResults=500&startingBlockIndex=0 HTTP/1.1
Host: ebs.us-east-2.amazonaws.com
Accept-Encoding: identity
User-Agent:
X-Amz-Date: 20200617T232546Z
Authorization:
```
The following example response for the previous request shows that block indexes `0`, `3072`, `6002`, and `6003` are different between the two snapshots. Additionally, block indexes `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 `GetSnapshotBlock` action 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.
```
HTTP/1.1 200 OK
x-amzn-RequestId: fb0f6743-6d81-4be8-afbe-db11a5bb8a1f
Content-Type: application/json
Content-Length: 1456
Date: Wed, 17 Jun 2020 23:25:47 GMT
Connection: keep-alive
{
"BlockSize": 524288,
"ChangedBlocks": [
{
"BlockIndex": 0,
"FirstBlockToken": "AAUBAVaWqOCnDNuKle11s7IIX6jp6FYcC/tJuVT1GgP23AuLntwiMdJ+OJkL",
"SecondBlockToken": "AAUBASxzy0Y0b33JVRLoYm3NOresCxn5RO+HVFzXW3Y/RwfFaPX2Edx8QHCh"
},
{
"BlockIndex": 3072,
"FirstBlockToken": "AAUBAcHp6pC5fKAC7TokoNCtAnZhqq27u6fxRfZOLEmeXLmHBf2R/Yb24MaS",
"SecondBlockToken": "AAUBARGCaufCqBRZC8tEkPYGGkSv3vqvOjJ2xKDi3ljDFiytUxBLXYgTmkid"
},
{
"BlockIndex": 6002,
"FirstBlockToken": "AAABASqX4/NWjvNceoyMUljcRd0DnwbSwNnes1UkoP62CrQXvn47BY5435aw"
},
{
"BlockIndex": 6003,
"FirstBlockToken": "AAABASmJ0O5JxAOce25rF4P1sdRtyIDsX12tFEDunnePYUKOf4PBROuICb2A"
},
...
],
"ExpiryTime": 1.592976647009E9,
"VolumeSize": 3
}
```
------
## Get block data from a snapshot
------
#### [ AWS CLI ]
The following [get-snapshot-block](https://docs.aws.amazon.com/cli/latest/reference/ebs/get-snapshot-block.html) example command returns the data in the block index `6001` 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-id snap-1234567890 --block-index 6001 --block-token AAABASBpSJ2UAD3PLxJnCt6zun4/T4sU25Bnb8jB5Q6FRXHFqAIAqE04hJoR C:/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"
}
```
------
#### [ AWS API ]
The following [GetSnapshotBlock](https://docs.aws.amazon.com/ebs/latest/APIReference/API_GetSnapshotBlock.html) example request returns the data in the block index `3072` with block token `AAUBARGCaufCqBRZC8tEkPYGGkSv3vqvOjJ2xKDi3ljDFiytUxBLXYgTmkid`, in snapshot `snap-0c9EXAMPLE1b30e2f`.
```
GET /snapshots/snap-0c9EXAMPLE1b30e2f/blocks/3072?blockToken=AAUBARGCaufCqBRZC8tEkPYGGkSv3vqvOjJ2xKDi3ljDFiytUxBLXYgTmkid HTTP/1.1
Host: ebs.us-east-2.amazonaws.com
Accept-Encoding: identity
User-Agent:
X-Amz-Date: 20200617T232838Z
Authorization:
```
The following example response for the previous request shows the size of the data returned, the checksum to validate the data, and the algorithm used to generate the checksum. The binary data is transmitted in the body of the response and is represented as *BlockData* in the following example.
```
HTTP/1.1 200 OK
x-amzn-RequestId: 2d0db2fb-bd88-474d-a137-81c4e57d7b9f
x-amz-Data-Length: 524288
x-amz-Checksum: Vc0yY2j3qg8bUL9I6GQuI2orTudrQRBDMIhcy7bdEsw=
x-amz-Checksum-Algorithm: SHA256
Content-Type: application/octet-stream
Content-Length: 524288
Date: Wed, 17 Jun 2020 23:28:38 GMT
Connection: keep-alive
BlockData
```
------
# Write Amazon EBS snapshots with EBS direct APIs
The following steps describe how to use the EBS direct APIs to write incremental snapshots:
1. Use the StartSnapshot action and specify a parent snapshot ID to start a snapshot as an incremental snapshot of an existing one, or omit the parent snapshot ID to start a new snapshot. This action returns the new snapshot ID, which is in a pending state.
1. Use the PutSnapshotBlock action and specify the ID of the pending snapshot to add data to it in the form of individual blocks. You must specify a Base64-encoded SHA256 checksum for the block of data transmitted. The service computes the checksum of the data received and validates it with the checksum that you specified. The action fails if the checksums don't match.
1. When you're done adding data to the pending snapshot, use the CompleteSnapshot action to start an asynchronous workflow that seals the snapshot and moves it to a completed state.
Repeat these steps to create a new, incremental snapshot using the previously created snapshot as the parent.
For example, in the following diagram, snapshot A is the first new snapshot started. Snapshot A is used as the parent snapshot to start snapshot B. Snapshot B is used as the parent snapshot to start and create snapshot C. Snapshots A, B, and C are incremental snapshots. Snapshot A is used to create EBS volume 1. Snapshot D is created from EBS volume 1. Snapshot D is an incremental snapshot of A; it is not an incremental snapshot of B or C.
![\[EBS direct APIs used to create incremental snapshots.\]](http://docs.aws.amazon.com/ebs/latest/userguide/images/ebs-apis-write.png)
The following examples show how to write snapshots using the EBS direct APIs.
**Topics**
+ [
## Start a snapshot
](#start-snapshot)
+ [
## Put data into a snapshot
](#put-data)
+ [
## Complete a snapshot
](#complete-snapshot)
## Start a snapshot
------
#### [ AWS CLI ]
The following [start-snapshot](https://docs.aws.amazon.com/cli/latest/reference/ebs/start-snapshot.html) example command starts an `8` GiB snapshot, using snapshot `snap-123EXAMPLE1234567` as the parent snapshot. The new snapshot will be an incremental snapshot of the parent snapshot. The snapshot moves to an error state if there are no put or complete requests made for the snapshot within the specified `60` minute timeout period. The `550e8400-e29b-41d4-a716-446655440000` client token ensures idempotency for the request. If the client token is omitted, the AWS SDK automatically generates one for you. For more information about idempotency, see [Ensure idempotency in StartSnapshot API requests](ebs-direct-api-idempotency.md).
```
aws ebs start-snapshot --volume-size 8 --parent-snapshot snap-123EXAMPLE1234567 --timeout 60 --client-token 550e8400-e29b-41d4-a716-446655440000
```
The following example response for the previous command shows the snapshot ID, AWS account ID, status, volume size in GiB, and size of the blocks in the snapshot. The snapshot is started in a `pending` state. Specify the snapshot ID in subsequent `put-snapshot-block` commands to write data to the snapshot, then use the `complete-snapshot` command to complete the snapshot and change its status to `completed`.
```
{
"SnapshotId": "snap-0aaEXAMPLEe306d62",
"OwnerId": "111122223333",
"Status": "pending",
"VolumeSize": 8,
"BlockSize": 524288
}
```
------
#### [ AWS API ]
The following [StartSnapshot](https://docs.aws.amazon.com/ebs/latest/APIReference/API_StartSnapshot.html) example request starts an `8` GiB snapshot, using snapshot `snap-123EXAMPLE1234567` as the parent snapshot. The new snapshot will be an incremental snapshot of the parent snapshot. The snapshot moves to an error state if there are no put or complete requests made for the snapshot within the specified `60` minute timeout period. The `550e8400-e29b-41d4-a716-446655440000` client token ensures idempotency for the request. If the client token is omitted, the AWS SDK automatically generates one for you. For more information about idempotency, see [Ensure idempotency in StartSnapshot API requests](ebs-direct-api-idempotency.md).
```
POST /snapshots HTTP/1.1
Host: ebs.us-east-2.amazonaws.com
Accept-Encoding: identity
User-Agent:
X-Amz-Date: 20200618T040724Z
Authorization:
{
"VolumeSize": 8,
"ParentSnapshot": snap-123EXAMPLE1234567,
"ClientToken": "550e8400-e29b-41d4-a716-446655440000",
"Timeout": 60
}
```
The following example response for the previous request shows the snapshot ID, AWS account ID, status, volume size in GiB, and size of the blocks in the snapshot. The snapshot is started in a pending state. Specify the snapshot ID in a subsequent `PutSnapshotBlocks` request to write data to the snapshot.
```
HTTP/1.1 201 Created
x-amzn-RequestId: 929e6eb9-7183-405a-9502-5b7da37c1b18
Content-Type: application/json
Content-Length: 181
Date: Thu, 18 Jun 2020 04:07:29 GMT
Connection: keep-alive
{
"BlockSize": 524288,
"Description": null,
"OwnerId": "138695307491",
"Progress": null,
"SnapshotId": "snap-052EXAMPLEc85d8dd",
"StartTime": null,
"Status": "pending",
"Tags": null,
"VolumeSize": 8
}
```
------
## Put data into a snapshot
------
#### [ AWS CLI ]
The following [put-snapshot-block](https://docs.aws.amazon.com/cli/latest/reference/ebs/put-snapshot-block.html) example command writes `524288` Bytes of data to block index `1000` on snapshot `snap-0aaEXAMPLEe306d62`. The Base64 encoded `QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM=` checksum was generated using the `SHA256` algorithm. The data that is transmitted is in the `/tmp/data` file.
```
aws ebs put-snapshot-block --snapshot-id snap-0aaEXAMPLEe306d62 --block-index 1000 --data-length 524288 --block-data /tmp/data --checksum QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM= --checksum-algorithm SHA256
```
The following example response for the previous command confirms the data length, checksum, and checksum algorithm for the data received by the service.
```
{
"DataLength": "524288",
"Checksum": "QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM=",
"ChecksumAlgorithm": "SHA256"
}
```
------
#### [ AWS API ]
The following [PutSnapshot](https://docs.aws.amazon.com/ebs/latest/APIReference/API_PutSnapshotBlock.html) example request writes `524288` Bytes of data to block index `1000` on snapshot `snap-052EXAMPLEc85d8dd`. The Base64 encoded `QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM=` checksum was generated using the `SHA256` algorithm. The data is transmitted in the body of the request and is represented as *BlockData* in the following example.
```
PUT /snapshots/snap-052EXAMPLEc85d8dd/blocks/1000 HTTP/1.1
Host: ebs.us-east-2.amazonaws.com
Accept-Encoding: identity
x-amz-Data-Length: 524288
x-amz-Checksum: QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM=
x-amz-Checksum-Algorithm: SHA256
User-Agent:
X-Amz-Date: 20200618T042215Z
X-Amz-Content-SHA256: UNSIGNED-PAYLOAD
Authorization:
BlockData
```
The following is example response for the previous request confirms the data length, checksum, and checksum algorithm for the data received by the service.
```
HTTP/1.1 201 Created
x-amzn-RequestId: 643ac797-7e0c-4ad0-8417-97b77b43c57b
x-amz-Checksum: QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM=
x-amz-Checksum-Algorithm: SHA256
Content-Type: application/json
Content-Length: 2
Date: Thu, 18 Jun 2020 04:22:12 GMT
Connection: keep-alive
{}
```
------
## Complete a snapshot
------
#### [ AWS CLI ]
The following [complete-snapshot](https://docs.aws.amazon.com/cli/latest/reference/ebs/complete-snapshot.html) example command completes snapshot `snap-0aaEXAMPLEe306d62`. The command specifies that `5` blocks were written to the snapshot. The `6D3nmwi5f2F0wlh7xX8QprrJBFzDX8aacdOcA3KCM3c=` checksum represents the checksum for the complete set of data written to a snapshot. For more information about checksums, see [Use EBS direct APIs checksums to validate snapshot data](ebsapis-using-checksums.md) earlier in this guide.
```
aws ebs complete-snapshot --snapshot-id snap-0aaEXAMPLEe306d62 --changed-blocks-count 5 --checksum 6D3nmwi5f2F0wlh7xX8QprrJBFzDX8aacdOcA3KCM3c= --checksum-algorithm SHA256 --checksum-aggregation-method LINEAR
```
The following is an example response for the previous command.
```
{
"Status": "pending"
}
```
------
#### [ AWS API ]
The following [CompleteSnapshot](https://docs.aws.amazon.com/ebs/latest/APIReference/API_CompleteSnapshot.html) example request completes snapshot `snap-052EXAMPLEc85d8dd`. The command specifies that `5` blocks were written to the snapshot. The `6D3nmwi5f2F0wlh7xX8QprrJBFzDX8aacdOcA3KCM3c=` checksum represents the checksum for the complete set of data written to a snapshot.
```
POST /snapshots/completion/snap-052EXAMPLEc85d8dd HTTP/1.1
Host: ebs.us-east-2.amazonaws.com
Accept-Encoding: identity
x-amz-ChangedBlocksCount: 5
x-amz-Checksum: 6D3nmwi5f2F0wlh7xX8QprrJBFzDX8aacdOcA3KCM3c=
x-amz-Checksum-Algorithm: SHA256
x-amz-Checksum-Aggregation-Method: LINEAR
User-Agent:
X-Amz-Date: 20200618T043158Z
Authorization:
```
The following is an example response for the previous request.
```
HTTP/1.1 202 Accepted
x-amzn-RequestId: 06cba5b5-b731-49de-af40-80333ac3a117
Content-Type: application/json
Content-Length: 20
Date: Thu, 18 Jun 2020 04:31:50 GMT
Connection: keep-alive
{"Status":"pending"}
```
------
# Encryption outcomes for EBS direct APIs
When you start a new snapshot using [ StartSnapshot](https://docs.aws.amazon.com/ebs/latest/APIReference/API_StartSnapshot.html), the encryption status depends on the values that you specify for **Encrypted**, **KmsKeyArn**, and **ParentSnapshotId**, and whether your AWS account is enabled for [encryption by default](encryption-by-default.md).
**Note**
You might need additional IAM permissions to use the EBS direct APIs with encryption. For moreinformation, see [Permissions to use AWS KMS keys](ebsapi-permissions.md#ebsapi-kms-permissions).
If Amazon EBS encryption by default is enabled on your AWS account, you can't create unencrypted snapshots.
If Amazon EBS encryption by default is enabled on your AWS account, you cannot start a new snapshot using an unencrypted parent snapshot. You must first encrypt the parent snapshot by copying it. For more information, see [Copy an Amazon EBS snapshot](ebs-copy-snapshot.md).
**Topics**
+ [
## Encryption outcomes: Unencrypted parent snapshot
](#ebs-direct-api-unencr-outcomes-parent)
+ [
## Encryption outcomes: Encrypted parent snapshot
](#ebs-direct-api-encr-outcomes-parent)
+ [
## Encryption outcomes: No parent snapshot
](#ebs-direct-api-encr-outcomes-noparent)
## Encryption outcomes: Unencrypted parent snapshot
The following table describes the encryption outcome for each possible combination of settings when specifying an unencrypted parent snapshot.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ebs/latest/userguide/ebsapis-using-encryption.html)
## Encryption outcomes: Encrypted parent snapshot
The following table describes the encryption outcome for each possible combination of settings when specifying an encrypted parent snapshot.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ebs/latest/userguide/ebsapis-using-encryption.html)
## Encryption outcomes: No parent snapshot
The following tables describe the encryption outcome for each possible combination of settings when not using a parent snapshot.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ebs/latest/userguide/ebsapis-using-encryption.html)
\$1 This default KMS key could be a customer managed key or the default AWS managed KMS key for Amazon EBS encryption.
# Use EBS direct APIs checksums to validate snapshot data
The GetSnapshotBlock action returns data that is in a block of a snapshot, and the PutSnapshotBlock action adds data to a block in a snapshot. The block data that is transmitted is not signed as part of the Signature Version 4 signing process. As a result, checksums are used to validate the integrity of the data as follows:
+ When you use the GetSnapshotBlock action, the response provides a Base64-encoded SHA256 checksum for the block data using the **x-amz-Checksum** header, and the checksum algorithm using the **x-amz-Checksum-Algorithm** header. Use the returned checksum to validate the integrity of the data. If the checksum that you generate doesn't match what Amazon EBS provided, you should consider the data not valid and retry your request.
+ When you use the PutSnapshotBlock action, your request must provide a Base64-encoded SHA256 checksum for the block data using the **x-amz-Checksum** header, and the checksum algorithm using the **x-amz-Checksum-Algorithm** header. The checksum that you provide is validated against a checksum generated by Amazon EBS to validate the integrity of the data. If the checksums do not correspond, the request fails.
+ When you use the CompleteSnapshot action, your request can optionally provide an aggregate Base64-encoded SHA256 checksum for the complete set of data added to the snapshot. Provide the checksum using the **x-amz-Checksum** header, the checksum algorithm using the **x-amz-Checksum-Algorithm** header, and the checksum aggregation method using the **x-amz-Checksum-Aggregation-Method** header. 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.
The checksums in these actions are part of the Signature Version 4 signing process.
# Ensure idempotency in StartSnapshot API requests
Idempotency ensures that an API request completes only once. With an idempotent request, if the original request completes successful, the subsequent retries return the result from the original successful request and they have no additional effect.
The [ StartSnapshot](https://docs.aws.amazon.com/ebs/latest/APIReference/API_StartSnapshot.html) API supports idempotency using a *client token*. A client token is a unique string that you specify when you make an API request. If you retry an API request with the same client token and the same request parameters after it has completed successfully, the result of the original request is returned. If you retry a request with the same client token, but change one or more of the request parameters, the `ConflictException` error is returned.
If you do not specify your own client token, the AWS SDKs automatically generates a client token for the request to ensure that it is idempotent.
A client token can be any string that includes up to 64 ASCII characters. You should not reuse the same client tokens for different requests.
**To make an idempotent StartSnapshot request with your own client token using the API**
Specify the `ClientToken` request parameter.
```
POST /snapshots HTTP/1.1
Host: ebs.us-east-2.amazonaws.com
Accept-Encoding: identity
User-Agent:
X-Amz-Date: 20200618T040724Z
Authorization:
{
"VolumeSize": 8,
"ParentSnapshot": snap-123EXAMPLE1234567,
"ClientToken": "550e8400-e29b-41d4-a716-446655440000",
"Timeout": 60
}
```
**To make an idempotent StartSnapshot request with your own client token using the AWS CLI**
Specify the `client-token` request parameter.
```
$ C:\> aws ebs start-snapshot --region us-east-2 --volume-size 8 --parent-snapshot snap-123EXAMPLE1234567 --timeout 60 --client-token 550e8400-e29b-41d4-a716-446655440000
```
# Error retries for EBS direct APIs
The **AWS SDKs** implement automatic retry logic for requests that return error responses. You can configure the retry settings for the AWS SDKs. For more information, see your SDK's documentation.
You can configure the **AWS CLI** to automatically retry some failed requests. For more information about configuring retries for the AWS CLI, see [AWS CLI retries](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-retries.html) in the *AWS Command Line Interface User Guide*.
The **AWS Query API** does not support retry logic for failed requests. If you are using HTTP or HTTPS requests, you must implement retry logic in your client application.
The following table shows the possible API error responses. Some API errors are retryable. Your client application should always retry failed requests that receive a retryable error.
| Error | Response code | Description | Thrown by | Retryable? |
| --- | --- | --- | --- | --- |
| InternalServerException | 500 | The request failed due to a network or AWS server-side issue. | All APIs | Yes |
| ThrottlingException | 400 | The number of API requests has exceeded the maximum allowed API request throttling limit for the account. | All APIs | Yes |
| RequestThrottleException | 400 | The number of API requests has exceeded the maximum allowed API request throttling limit for the snapshot. | GetSnapshotBlock \$1 PutSnapshotBlock | Yes |
| ValidationException with message "Failed to read block data" | 400 | The provided data block was not readable. | PutSnapshotBlock | Yes |
| ValidationException with any other message | 400 | The request syntax is malformed, or the input does not satisfy the constraints specified by the AWS service. | All APIs | No |
| ResourceNotFoundException | 404 | The specified snapshot ID does not exist. | All APIs | No |
| ConflictException | 409 | The specified client token was previously used in a similar request that had different request parameters. For more information, see [Ensure idempotency in StartSnapshot API requests](ebs-direct-api-idempotency.md). | StartSnapshot | No |
| AccessDeniedException | 403 | You do not have permission to perform the requested operation. | All APIs | No |
| ServiceQuotaExceededException | 402 | The request failed because fulfilling the request would exceed one or more dependent service quotas for your account. | All APIs | No |
| InvalidSignatureException | 403 | The request authorization signature has expired. You can retry the request only after refreshing the authorization signature. | All APIs | No |
# Optimize performance for EBS direct APIs
You can run API requests concurrently. Assuming PutSnapshotBlock latency is 100ms, then a thread can process 10 requests in one second. Furthermore, assuming your client application creates multiple threads and connections (for example, 100 connections), it can make 1000 (10 \$1 100) requests per second in total. This will correspond to a throughput of around 500 MB per second.
The following list contains few things to look for in your application:
+ Is each thread using a separate connection? If the connections are limited on the application then multiple threads will wait for the connection to be available and you will notice lower throughput.
+ Is there any wait time in the application between two put requests? This will reduce the effective throughput of a thread.
+ The bandwidth limit on the instance – If bandwidth on the instance is shared by other applications, it could limit the available throughput for PutSnapshotBlock requests.
Be sure to take note of other workloads that might be running in the account to avoid bottlenecks. You should also build retry mechanisms into your EBS direct APIs workflows to handle throttling, timeouts, and service unavailability.
Review the EBS direct APIs service quotas to determine the maximum API requests that you can run per second. For more information, see [Amazon Elastic Block Store Endpoints and Quotas](https://docs.aws.amazon.com/general/latest/gr/ebs-service.html#w542aab9d130b7c15) in the *AWS General Reference*.
# Service endpoints for EBS direct APIs
An *endpoint* is a URL that serves as an entry point for an AWS web service. EBS direct APIs supports the following endpoint types:
+ IPv4 endpoints
+ Dual-stack endpoints that support both IPv4 and IPv6
+ FIPS endpoints
When you make a request, you can specify the endpoint and Region to use. If you do not specify an endpoint, the IPv4 endpoint is used by default. To use a different endpoint type, you must specify it in your request. For examples of how to do this, see [Specifying endpoints](#examples).
For more information about Regions, see [ Regions and Availability Zones](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) in the *Amazon EC2 User Guide*. For a list of endpoints for EBS direct APIs, see [ Endpoints for the EBS direct APIs](https://docs.aws.amazon.com/general/latest/gr/ebs-service.html#ebs_direct_apis) in the *Amazon Web Services General Reference*.
**Topics**
+ [
## IPv4 endpoints
](#ipv4)
+ [
## Dual-stack (IPv4 and IPv6) endpoints
](#ipv6)
+ [
## FIPS endpoints
](#fips)
+ [
## Specifying endpoints
](#examples)
## IPv4 endpoints
IPv4 endpoints support IPv4 traffic only. IPv4 endpoints are available for all Regions.
EBS direct APIs supports only Regional IPv4 endpoints that you can use to make your requests. You must specify the Region as part of the endpoint name. The endpoint names use the following naming convention:
+ `ebs.region.amazonaws.com`
For example, to direct your requests to the `us-east-2` IPv4 endpoint, you must specify `ebs.us-east-2.amazonaws.com` as the endpoint. For a list of endpoints for EBS direct APIs, see [ Endpoints for the EBS direct APIs](https://docs.aws.amazon.com/general/latest/gr/ebs-service.html#ebs_direct_apis) in the *Amazon Web Services General Reference*.
**Pricing**
You are not charged for data transferred directly between EBS direct APIs and Amazon EC2 instances using an IPv4 endpoint in the same Region. However, if there are intermediate services, such as AWS PrivateLink endpoints, NAT Gateway, or Amazon VPC Transit Gateways, you are charged their associated costs.
## Dual-stack (IPv4 and IPv6) endpoints
Dual-stack endpoints support both IPv4 and IPv6 traffic. Dual-stack endpoints are available for all Regions.
To use IPv6, you must use a dual-stack endpoint. When you make a request to a dual-stack endpoint, the endpoint URL resolves to an IPv6 or an IPv4 address, depending on the protocol used by your network and client.
EBS direct APIs supports only regional dual-stack endpoints, which means that you must specify the Region as part of the endpoint name. Dual-stack endpoint names use the following naming convention:
+ `ebs.region.api.aws`
For example, the dual-stack endpoint name for the `eu-west-1` Region is `ebs.eu-west-1.api.aws`. For a list of endpoints for EBS direct APIs, see [Endpoints for the EBS direct APIs](https://docs.aws.amazon.com/general/latest/gr/ebs-service.html#ebs_direct_apis) in the *Amazon Web Services General Reference*.
**Pricing**
You are not charged for data transferred directly between EBS direct APIs and Amazon EC2 instances using a dual-stack endpoint in the same Region. However, if there are intermediate services, such as AWS PrivateLink endpoints, NAT Gateway, or Amazon VPC Transit Gateways, you are charged their associated costs.
## FIPS endpoints
EBS direct APIs provides FIPS-validated IPv4 and dual-stack (IPv4 and IPv6) endpoints for the following Regions:
+ `us-east-1` — US East (N. Virginia)
+ `us-east-2` — US East (Ohio)
+ `us-west-1` — US West (N. California)
+ `us-west-2` — US West (Oregon)
+ `ca-central-1` — Canada (Central)
+ `ca-west-1` — Canada West (Calgary)
**FIPS IPv4 endpoints** use the following naming convention: `ebs-fips.region.amazonaws.com`. For example, the FIPS IPv4 endpoint for `us-east-1` is `ebs-fips.us-east-1.amazonaws.com`.
**FIPS dual-stack endpoints** use the following naming convention: `ebs-fips.region.api.aws`. For example, the FIPS dual-stack endpoint for `us-east-1` is `ebs-fips.us-east-1.api.aws`.
For more information about FIPS endpoints see, [ FIPS endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#FIPS-endpoints) in the *Amazon Web Services General Reference*.
## Specifying endpoints
This section provides some examples of how to specify an endpoint when making a request.
------
#### [ AWS CLI ]
The following examples show how to specify an endpoint for the `us-east-2` Region using the AWS CLI.
+ **Dual-stack**
```
aws ebs list-snapshot-blocks --snapshot-id snap-0987654321 --starting-block-index 1000 --endpoint-url https://ebs.us-east-2.api.aws
```
+ **IPv4**
```
aws ebs list-snapshot-blocks --snapshot-id snap-0987654321 --starting-block-index 1000 --endpoint-url https://ebs.us-east-2.amazonaws.com
```
------
#### [ AWS SDK for Java 2.x ]
The following examples show how to specify an endpoint for the `us-east-2` Region using the AWS SDK for Java 2.x.
+ **Dual-stack**
```
AwsClientBuilder.EndpointConfiguration config = new AwsClientBuilder.EndpointConfiguration("https://ebs.us-east-2.api.aws", "us-east-2");
AmazonEBS ebs = AmazonEBSClientBuilder.standard()
.withEndpointConfiguration(config)
.build();
```
+ **IPv4**
```
AwsClientBuilder.EndpointConfiguration config = new AwsClientBuilder.EndpointConfiguration("https://ebs.us-east-2.amazonaws.com", "us-east-2");
AmazonEBS ebs = AmazonEBSClientBuilder.standard()
.withEndpointConfiguration(config)
.build();
```
------
#### [ AWS SDK for Go ]
The following examples show how to specify an endpoint for the `us-east-2` Region using the AWS SDK for Go.
+ **Dual-stack**
```
sess := session.Must(session.NewSession())
svc := ebs.New(sess, &aws.Config{
Region: aws.String(endpoints.UsEast2RegionID),
Endpoint: aws.String("https://ebs.us-east-2.api.aws")
})
```
+ **IPv4**
```
sess := session.Must(session.NewSession())
svc := ebs.New(sess, &aws.Config{
Region: aws.String(endpoints.UsEast2RegionID),
Endpoint: aws.String("https://ebs.us-east-2.amazonaws.com")
})
```
------
# AWS SDK code examples for EBS direct APIs
The following code examples show how to use EBS direct APIs with an AWS software development kit (SDK).
**Topics**
+ [StartSnapshot](#sdk-StartSnapshot)
+ [PutSnapshotBlock](#sdk-PutSnapshotBlock)
+ [CompleteSnapshot](#sdk-CompleteSnapshot)
## Use `StartSnapshot` with an AWS SDK or CLI
The following code example shows how to use `StartSnapshot`.
------
#### [ Rust ]
**SDK for Rust**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/ebs#code-examples).
```
async fn start(client: &Client, description: &str) -> Result {
let snapshot = client
.start_snapshot()
.description(description)
.encrypted(false)
.volume_size(1)
.send()
.await?;
Ok(snapshot.snapshot_id.unwrap())
}
```
+ For API details, see [StartSnapshot](https://docs.rs/aws-sdk-ebs/latest/aws_sdk_ebs/client/struct.Client.html#method.start_snapshot) in *AWS SDK for Rust API reference*.
------
## Use `PutSnapshotBlock` with an AWS SDK or CLI
The following code example shows how to use `PutSnapshotBlock`.
------
#### [ Rust ]
**SDK for Rust**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/ebs#code-examples).
```
async fn add_block(
client: &Client,
id: &str,
idx: usize,
block: Vec,
checksum: &str,
) -> Result<(), Error> {
client
.put_snapshot_block()
.snapshot_id(id)
.block_index(idx as i32)
.block_data(ByteStream::from(block))
.checksum(checksum)
.checksum_algorithm(ChecksumAlgorithm::ChecksumAlgorithmSha256)
.data_length(EBS_BLOCK_SIZE as i32)
.send()
.await?;
Ok(())
}
```
+ For API details, see [PutSnapshotBlock](https://docs.rs/aws-sdk-ebs/latest/aws_sdk_ebs/client/struct.Client.html#method.put_snapshot_block) in *AWS SDK for Rust API reference*.
------
## Use `CompleteSnapshot` with an AWS SDK or CLI
The following code example shows how to use `CompleteSnapshot`.
------
#### [ Rust ]
**SDK for Rust**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/ebs#code-examples).
```
async fn finish(client: &Client, id: &str) -> Result<(), Error> {
client
.complete_snapshot()
.changed_blocks_count(2)
.snapshot_id(id)
.send()
.await?;
println!("Snapshot ID {}", id);
println!("The state is 'completed' when all of the modified blocks have been transferred to Amazon S3.");
println!("Use the get-snapshot-state code example to get the state of the snapshot.");
Ok(())
}
```
+ For API details, see [CompleteSnapshot](https://docs.rs/aws-sdk-ebs/latest/aws_sdk_ebs/client/struct.Client.html#method.complete_snapshot) in *AWS SDK for Rust API reference*.
------
# Create a private connection between a VPC and EBS direct APIs
You can establish a private connection between your VPC and EBS direct APIs by creating an *interface VPC endpoint*, powered by [AWS PrivateLink](https://aws.amazon.com/privatelink/). You can access EBS direct APIs as if it were in your VPC, without using an internet gateway, NAT device, VPN connection, or AWS Direct Connect connection. Instances in your VPC don't need public IP addresses to communicate with EBS direct APIs.
We create an endpoint network interface in each subnet that you enable for the interface endpoint.
For more information, see [Access AWS services through AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-access-aws-services.html) in the *AWS PrivateLink Guide*.
## Considerations for EBS direct APIs VPC endpoints
Before you set up an interface VPC endpoint for EBS direct APIs, review [Considerations](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#considerations-interface-endpoints) in the *AWS PrivateLink Guide*.
By default, full access to EBS direct APIs is allowed through the endpoint. You can control access to the interface endpoint using VPC endpoint policies. You can attach an endpoint policy to your VPC endpoint that controls access to EBS direct APIs. The policy specifies the following information:
+ The **principal** that can perform actions.
+ The **actions** that can be performed.
+ The **resources** on which actions can be performed.
For more information, see [ Controlling access to services with VPC endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html) in the *Amazon VPC User Guide*.
The following is an example of an endpoint policy for EBS direct APIs. When attached to an endpoint, this policy grants access to all EBS direct APIs actions on all resources, except snapshots that are tagged with key `Environment` and value `Test`.
```
{
"Statement": [
{
"Effect": "Deny",
"Action": "ebs:*",
"Principal": "*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/Environment": "Test"
}
}
},
{
"Effect": "Allow",
"Action": "ebs:*",
"Principal": "*",
"Resource": "*"
}
]
}
```
## Create an interface VPC endpoint for EBS direct APIs
You can create a VPC endpoint for EBS direct APIs using either the Amazon VPC console or the AWS Command Line Interface (AWS CLI). For more information, see [ Create a VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint-aws) in the *AWS PrivateLink Guide*.
Create a VPC endpoint for EBS direct APIs using one of the following service names:
+ `com.amazonaws.region.ebs`
+ `com.amazonaws.region.ebs-fips` — To create an interface VPC endpoint that complies with the Federal Information Processing Standard (FIPS) Publication 140-2 US government standard.
**Note**
FIPS-compliant interface VPC endpoints can be created for the following Regions: `us-east-1` \$1 `us-east-2` \$1 `us-west-1` \$1 `us-west-2` \$1 `ca-central-1` \$1 `ca-west-1`. FIPS-compliant interface VPC endpoints support both IPv4 and IPv6 traffic.
If you enable private DNS for the endpoint, you can make API requests to EBS direct APIs using its default DNS name for the Region, for example, `ebs.us-east-1.amazonaws.com`.
# Log EBS direct APIs calls using AWS CloudTrail
EBS direct APIs are integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service. CloudTrail captures calls made to the EBS direct APIs as events. The calls captured include calls from the AWS Management Console and code calls to the EBS direct APIs. Using the information collected by CloudTrail, you can determine the request that was made to the EBS direct APIs, the IP address from which the request was made, when it was made, and additional details.
Every event or log entry contains information about who generated the request. The identity information helps you determine the following:
+ Whether the request was made with root user or user credentials.
+ Whether the request was made on behalf of an IAM Identity Center user.
+ Whether the request was made with temporary security credentials for a role or federated user.
+ Whether the request was made by another AWS service.
CloudTrail is active in your AWS account when you create the account and you automatically have access to the CloudTrail **Event history**. The CloudTrail **Event history** provides a viewable, searchable, downloadable, and immutable record of the past 90 days of recorded management events in an AWS Region. For more information, see [Working with CloudTrail Event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) in the *AWS CloudTrail User Guide*. There are no CloudTrail charges for viewing the **Event history**.
For an ongoing record of events in your AWS account past 90 days, create a trail or a [CloudTrail Lake](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake.html) event data store.
**CloudTrail trails**
A *trail* enables CloudTrail to deliver log files to an Amazon S3 bucket. All trails created using the AWS Management Console are multi-Region. You can create a single-Region or a multi-Region trail by using the AWS CLI. Creating a multi-Region trail is recommended because you capture activity in all AWS Regions in your account. If you create a single-Region trail, you can view only the events logged in the trail's AWS Region. For more information about trails, see [Creating a trail for your AWS account](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) and [Creating a trail for an organization](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/creating-trail-organization.html) in the *AWS CloudTrail User Guide*.
You can deliver one copy of your ongoing management events to your Amazon S3 bucket at no charge from CloudTrail by creating a trail, however, there are Amazon S3 storage charges. For more information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). For information about Amazon S3 pricing, see [Amazon S3 Pricing](https://aws.amazon.com/s3/pricing/).
**CloudTrail Lake event data stores**
*CloudTrail Lake* lets you run SQL-based queries on your events. CloudTrail Lake converts existing events in row-based JSON format to [ Apache ORC](https://orc.apache.org/) format. ORC is a columnar storage format that is optimized for fast retrieval of data. Events are aggregated into *event data stores*, which are immutable collections of events based on criteria that you select by applying [advanced event selectors](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake-concepts.html#adv-event-selectors). The selectors that you apply to an event data store control which events persist and are available for you to query. For more information about CloudTrail Lake, see [Working with AWS CloudTrail Lake](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake.html) in the *AWS CloudTrail User Guide*.
CloudTrail Lake event data stores and queries incur costs. When you create an event data store, you choose the [pricing option](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake-manage-costs.html#cloudtrail-lake-manage-costs-pricing-option) you want to use for the event data store. The pricing option determines the cost for ingesting and storing events, and the default and maximum retention period for the event data store. For more information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/).
## EBS direct APIs data events in CloudTrail
[Data events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events) provide information about the resource operations performed on or in a resource. These are also known as data plane operations. Data events are often high-volume activities. By default, CloudTrail doesn’t log data events. The CloudTrail **Event history** doesn't record data events.
Additional charges apply for data events. For more information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/).
You can log data events for the EBS direct APIs resource types by using the CloudTrail console, AWS CLI, or CloudTrail API operations. For more information about how to log data events, see [Logging data events with the AWS Management Console](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events-console) and [Logging data events with the AWS Command Line Interface](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#creating-data-event-selectors-with-the-AWS-CLI) in the *AWS CloudTrail User Guide*.
You can log the following EBS direct APIs operations as data events.
+ [ListSnapshotBlocks](https://docs.aws.amazon.com/ebs/latest/APIReference/API_ListSnapshotBlocks.html)
+ [ListChangedBlocks](https://docs.aws.amazon.com/ebs/latest/APIReference/API_ListChangedBlocks.html)
+ [ GetSnapshotBlock](https://docs.aws.amazon.com/ebs/latest/APIReference/API_GetSnapshotBlock.html)
+ [PutSnapshotBlock](https://docs.aws.amazon.com/ebs/latest/APIReference/API_PutSnapshotBlock.html)
**Note**
If you perform an action on a snapshot that is shared with you, data events are not sent to the AWS account that owns the snapshot.
## EBS direct APIs management events in CloudTrail
[Management events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html#logging-management-events) provide information about management operations that are performed on resources in your AWS account. These are also known as control plane operations. By default, CloudTrail logs management events.
The EBS direct APIs service logs the following control plane operations to CloudTrail as management events.
+ [ StartSnapshot](https://docs.aws.amazon.com/ebs/latest/APIReference/API_StartSnapshot.html)
+ [ CompleteSnapshot](https://docs.aws.amazon.com/ebs/latest/APIReference/API_CompleteSnapshot.html)
## EBS direct APIs event examples
An event represents a single request from any source and includes information about the requested API operation, the date and time of the operation, request parameters, and so on. CloudTrail log files aren't an ordered stack trace of the public API calls, so events don't appear in any specific order.
The following are example CloudTrail events for the EBS direct APIs.
------
#### [ StartSnapshot ]
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "123456789012",
"arn": "arn:aws:iam::123456789012:root",
"accountId": "123456789012",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"userName": "user"
},
"eventTime": "2020-07-03T23:27:26Z",
"eventSource": "ebs.amazonaws.com",
"eventName": "StartSnapshot",
"awsRegion": "eu-west-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "PostmanRuntime/7.25.0",
"requestParameters": {
"volumeSize": 8,
"clientToken": "token",
"encrypted": true
},
"responseElements": {
"snapshotId": "snap-123456789012",
"ownerId": "123456789012",
"status": "pending",
"startTime": "Jul 3, 2020 11:27:26 PM",
"volumeSize": 8,
"blockSize": 524288,
"kmsKeyArn": "HIDDEN_DUE_TO_SECURITY_REASONS"
},
"requestID": "be112233-1ba5-4ae0-8e2b-1c302EXAMPLE",
"eventID": "6e12345-2a4e-417c-aa78-7594fEXAMPLE",
"eventType": "AwsApiCall",
"recipientAccountId": "123456789012"
}
```
------
#### [ CompleteSnapshot ]
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "123456789012",
"arn": "arn:aws:iam::123456789012:root",
"accountId": "123456789012",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"userName": "user"
},
"eventTime": "2020-07-03T23:28:24Z",
"eventSource": "ebs.amazonaws.com",
"eventName": "CompleteSnapshot",
"awsRegion": "eu-west-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "PostmanRuntime/7.25.0",
"requestParameters": {
"snapshotId": "snap-123456789012",
"changedBlocksCount": 5
},
"responseElements": {
"status": "completed"
},
"requestID": "be112233-1ba5-4ae0-8e2b-1c302EXAMPLE",
"eventID": "6e12345-2a4e-417c-aa78-7594fEXAMPLE",
"eventType": "AwsApiCall",
"recipientAccountId": "123456789012"
}
```
------
#### [ ListSnapshotBlocks ]
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "IAMUser",
"principalId": "AIDAT4HPB2AO3JEXAMPLE",
"arn": "arn:aws:iam::123456789012:user/user",
"accountId": "123456789012",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"userName": "user"
},
"eventTime": "2021-06-03T00:32:46Z",
"eventSource": "ebs.amazonaws.com",
"eventName": "ListSnapshotBlocks",
"awsRegion": "us-east-1",
"sourceIPAddress": "111.111.111.111",
"userAgent": "PostmanRuntime/7.28.0",
"requestParameters": {
"snapshotId": "snap-abcdef01234567890",
"maxResults": 100,
"startingBlockIndex": 0
},
"responseElements": null,
"requestID": "example6-0e12-4aa9-b923-1555eexample",
"eventID": "example4-218b-4f69-a9e0-2357dexample",
"readOnly": true,
"resources": [
{
"accountId": "123456789012",
"type": "AWS::EC2::Snapshot",
"ARN": "arn:aws:ec2:us-west-2::snapshot/snap-abcdef01234567890"
}
],
"eventType": "AwsApiCall",
"managementEvent": false,
"recipientAccountId": "123456789012",
"eventCategory": "Data",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-SHA",
"clientProvidedHostHeader": "ebs.us-west-2.amazonaws.com"
}
}
```
------
#### [ ListChangedBlocks ]
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "IAMUser",
"principalId": "AIDAT4HPB2AO3JEXAMPLE",
"arn": "arn:aws:iam::123456789012:user/user",
"accountId": "123456789012",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"userName": "user"
},
"eventTime": "2021-06-02T21:11:46Z",
"eventSource": "ebs.amazonaws.com",
"eventName": "ListChangedBlocks",
"awsRegion": "us-east-1",
"sourceIPAddress": "111.111.111.111",
"userAgent": "PostmanRuntime/7.28.0",
"requestParameters": {
"firstSnapshotId": "snap-abcdef01234567890",
"secondSnapshotId": "snap-9876543210abcdef0",
"maxResults": 100,
"startingBlockIndex": 0
},
"responseElements": null,
"requestID": "example0-f4cb-4d64-8d84-72e1bexample",
"eventID": "example3-fac4-4a78-8ebb-3e9d3example",
"readOnly": true,
"resources": [
{
"accountId": "123456789012",
"type": "AWS::EC2::Snapshot",
"ARN": "arn:aws:ec2:us-west-2::snapshot/snap-abcdef01234567890"
},
{
"accountId": "123456789012",
"type": "AWS::EC2::Snapshot",
"ARN": "arn:aws:ec2:us-west-2::snapshot/snap-9876543210abcdef0"
}
],
"eventType": "AwsApiCall",
"managementEvent": false,
"recipientAccountId": "123456789012",
"eventCategory": "Data",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-SHA",
"clientProvidedHostHeader": "ebs.us-west-2.amazonaws.com"
}
}
```
------
#### [ GetSnapshotBlock ]
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "IAMUser",
"principalId": "AIDAT4HPB2AO3JEXAMPLE",
"arn": "arn:aws:iam::123456789012:user/user",
"accountId": "123456789012",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"userName": "user"
},
"eventTime": "2021-06-02T20:43:05Z",
"eventSource": "ebs.amazonaws.com",
"eventName": "GetSnapshotBlock",
"awsRegion": "us-east-1",
"sourceIPAddress": "111.111.111.111",
"userAgent": "PostmanRuntime/7.28.0",
"requestParameters": {
"snapshotId": "snap-abcdef01234567890",
"blockIndex": 1,
"blockToken": "EXAMPLEiL5E3pMPFpaDWjExM2/mnSKh1mQfcbjwe2mM7EwhrgCdPAEXAMPLE"
},
"responseElements": null,
"requestID": "examplea-6eca-4964-abfd-fd9f0example",
"eventID": "example6-4048-4365-a275-42e94example",
"readOnly": true,
"resources": [
{
"accountId": "123456789012",
"type": "AWS::EC2::Snapshot",
"ARN": "arn:aws:ec2:us-west-2::snapshot/snap-abcdef01234567890"
}
],
"eventType": "AwsApiCall",
"managementEvent": false,
"recipientAccountId": "123456789012",
"eventCategory": "Data",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-SHA",
"clientProvidedHostHeader": "ebs.us-west-2.amazonaws.com"
}
}
```
------
#### [ PutSnapshotBlock ]
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "IAMUser",
"principalId": "AIDAT4HPB2AO3JEXAMPLE",
"arn": "arn:aws:iam::123456789012:user/user",
"accountId": "123456789012",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"userName": "user"
},
"eventTime": "2021-06-02T21:09:17Z",
"eventSource": "ebs.amazonaws.com",
"eventName": "PutSnapshotBlock",
"awsRegion": "us-east-1",
"sourceIPAddress": "111.111.111.111",
"userAgent": "PostmanRuntime/7.28.0",
"requestParameters": {
"snapshotId": "snap-abcdef01234567890",
"blockIndex": 1,
"dataLength": 524288,
"checksum": "exampleodSGvFSb1e3kxWUgbOQ4TbzPurnsfVexample",
"checksumAlgorithm": "SHA256"
},
"responseElements": {
"checksum": "exampleodSGvFSb1e3kxWUgbOQ4TbzPurnsfVexample",
"checksumAlgorithm": "SHA256"
},
"requestID": "example3-d5e0-4167-8ee8-50845example",
"eventID": "example8-4d9a-4aad-b71d-bb31fexample",
"readOnly": false,
"resources": [
{
"accountId": "123456789012",
"type": "AWS::EC2::Snapshot",
"ARN": "arn:aws:ec2:us-west-2::snapshot/snap-abcdef01234567890"
}
],
"eventType": "AwsApiCall",
"managementEvent": false,
"recipientAccountId": "123456789012",
"eventCategory": "Data",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-SHA",
"clientProvidedHostHeader": "ebs.us-west-2.amazonaws.com"
}
}
```
------
For information about CloudTrail record contents, see [CloudTrail record contents](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-record-contents.html) in the *AWS CloudTrail User Guide*.
# Frequently asked questions for EBS direct APIs
**Can a snapshot be accessed using the EBS direct APIs if it has a pending status?**
No. The snapshot can be accessed only if it has a completed status.
**Are the block indexes returned by the EBS direct APIs in numerical order?**
Yes. The block indexes returned are unique, and in numerical order.
**Can I submit a request with a MaxResults parameter value of under 100?**
No. The minimum MaxResult parameter value you can use is 100. If you submit a request with a MaxResult parameter value of under 100, and there are more than 100 blocks in the snapshot, then the API will return at least 100 results.
**Can I run API requests concurrently?**
You can run API requests concurrently. Be sure to take note of other workloads that might be running in the account to avoid bottlenecks. You should also build retry mechanisms into your EBS direct APIs workflows to handle throttling, timeouts, and service unavailability. For more information, see [Optimize performance for EBS direct APIs](ebsapi-performance.md).
Review the EBS direct APIs service quotas to determine the API requests that you can run per second. For more information, see [Amazon Elastic Block Store Endpoints and Quotas](https://docs.aws.amazon.com/general/latest/gr/ebs-service.html#w542aab9d130b7c15) in the *AWS General Reference*.
**When running the ListChangedBlocks action, is it possible to get an empty response even though there are blocks in the snapshot?**
Yes. If the changed blocks are scarce in the snapshot, the response may be empty but the API will return a next page token value. Use the next page token value to continue to the next page of results. You can confirm that you have reached the last page of results when the API returns a next page token value of null.
**If the NextToken parameter is specified together with a StartingBlockIndex parameter, which of the two is used?**
The NextToken is used, and the StartingBlockIndex is ignored.
**How long are the block tokens and next tokens valid?**
Block tokens are valid for seven days, and next tokens are valid for 60 minutes.
**Are encrypted snapshots supported?**
Yes. Encrypted snapshots can be accessed using the EBS direct APIs.
To access an encrypted snapshot, the user must have access to the KMS key used to encrypt the snapshot, and the AWS KMS decrypt action. See the [Control access to EBS direct APIs using IAM](ebsapi-permissions.md) section earlier in this guide for the AWS KMS policy to assign to a user.
**Are public snapshots supported?**
Public snapshots are not supported.
**Are Amazon EBS local snapshots on AWS Outposts supported?**
Amazon EBS local snapshots on AWS Outposts are not supported.
**Does list snapshot block return all block indexes and block tokens in a snapshot, or only those that have data written to them?**
It returns only block indexes and tokens that have data written to them.
**Can I get a history of the API calls made by the EBS direct APIs on my account for security analysis and operational troubleshooting purposes?**
Yes. To receive a history of EBS direct APIs API calls made on your account, turn on AWS CloudTrail in the AWS Management Console. For more information, see [Log EBS direct APIs calls using AWS CloudTrail](logging-ebs-apis-using-cloudtrail.md).