Amazon Elastic Block Store 2019-11-02
- Client: Aws\EBS\EBSClient
- Service ID: ebs
- Version: 2019-11-02
This page describes the parameters and results for the operations of the Amazon Elastic Block Store (2019-11-02), and shows how to use the Aws\EBS\EBSClient object to call the described operations. This documentation is specific to the 2019-11-02 API version of the service.
Operation Summary
Each of the following operations can be created from a client using
$client->getCommand('CommandName'), where "CommandName" is the
name of one of the following operations. Note: a command is a value that
encapsulates an operation and the parameters used to create an HTTP request.
You can also create and send a command immediately using the magic methods
available on a client object: $client->commandName(/* parameters */).
You can send the command asynchronously (returning a promise) by appending the
word "Async" to the operation name: $client->commandNameAsync(/* parameters */).
- CompleteSnapshot ( array $params = [] )
Seals and completes the snapshot after all of the required blocks of data have been written to it.
- GetSnapshotBlock ( array $params = [] )
Returns the data in a block in an Amazon Elastic Block Store snapshot.
- ListChangedBlocks ( array $params = [] )
Returns information about the blocks that are different between two Amazon Elastic Block Store snapshots of the same volume/snapshot lineage.
- ListSnapshotBlocks ( array $params = [] )
Returns information about the blocks in an Amazon Elastic Block Store snapshot.
- PutSnapshotBlock ( array $params = [] )
Writes a block of data to a snapshot.
- StartSnapshot ( array $params = [] )
Creates a new Amazon EBS snapshot.
Paginators
Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:
Operations
CompleteSnapshot
$result = $client->completeSnapshot([/* ... */]); $promise = $client->completeSnapshotAsync([/* ... */]);
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.
Parameter Syntax
$result = $client->completeSnapshot([
'ChangedBlocksCount' => <integer>, // REQUIRED
'Checksum' => '<string>',
'ChecksumAggregationMethod' => 'LINEAR',
'ChecksumAlgorithm' => 'SHA256',
'SnapshotId' => '<string>', // REQUIRED
]);
Parameter Details
Members
- ChangedBlocksCount
-
- Required: Yes
- Type: int
The number of blocks that were written to the snapshot.
- Checksum
-
- Type: string
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.
- ChecksumAggregationMethod
-
- Type: string
The aggregation method used to generate the checksum. Currently, the only supported aggregation method is
LINEAR. - ChecksumAlgorithm
-
- Type: string
The algorithm used to generate the checksum. Currently, the only supported algorithm is
SHA256. - SnapshotId
-
- Required: Yes
- Type: string
The ID of the snapshot.
Result Syntax
[
'Status' => 'completed|pending|error',
]
Result Details
Errors
-
You do not have sufficient access to perform this action.
-
The input fails to satisfy the constraints of the EBS direct APIs.
-
The specified resource does not exist.
-
The number of API requests has exceed the maximum allowed API request throttling limit.
-
ServiceQuotaExceededException:
Your current service quotas do not allow you to perform this action.
-
An internal error has occurred.
GetSnapshotBlock
$result = $client->getSnapshotBlock([/* ... */]); $promise = $client->getSnapshotBlockAsync([/* ... */]);
Returns the data in a block in an Amazon Elastic Block Store snapshot.
Parameter Syntax
$result = $client->getSnapshotBlock([
'BlockIndex' => <integer>, // REQUIRED
'BlockToken' => '<string>', // REQUIRED
'SnapshotId' => '<string>', // REQUIRED
]);
Parameter Details
Members
- BlockIndex
-
- Required: Yes
- Type: int
The block index of the block in which to read the data. A block index is a logical index in units of
512KiB 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 be512KiB aligned. - BlockToken
-
- Required: Yes
- Type: string
The block token of the block from which to get data. You can obtain the
BlockTokenby running theListChangedBlocksorListSnapshotBlocksoperations. - SnapshotId
-
- Required: Yes
- Type: string
The ID of the snapshot containing the block from which to get data.
If the specified 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.
Result Syntax
[
'BlockData' => <string || resource || Psr\Http\Message\StreamInterface>,
'Checksum' => '<string>',
'ChecksumAlgorithm' => 'SHA256',
'DataLength' => <integer>,
]
Result Details
Members
- BlockData
-
- Type: blob (string|resource|Psr\Http\Message\StreamInterface)
The data content of the block.
- Checksum
-
- Type: string
The checksum generated for the block, which is Base64 encoded.
- ChecksumAlgorithm
-
- Type: string
The algorithm used to generate the checksum for the block, such as SHA256.
- DataLength
-
- Type: int
The size of the data in the block.
Errors
-
You do not have sufficient access to perform this action.
-
The input fails to satisfy the constraints of the EBS direct APIs.
-
The specified resource does not exist.
-
The number of API requests has exceed the maximum allowed API request throttling limit.
-
ServiceQuotaExceededException:
Your current service quotas do not allow you to perform this action.
-
An internal error has occurred.
ListChangedBlocks
$result = $client->listChangedBlocks([/* ... */]); $promise = $client->listChangedBlocksAsync([/* ... */]);
Returns information about the blocks that are different between two Amazon Elastic Block Store snapshots of the same volume/snapshot lineage.
Parameter Syntax
$result = $client->listChangedBlocks([
'FirstSnapshotId' => '<string>',
'MaxResults' => <integer>,
'NextToken' => '<string>',
'SecondSnapshotId' => '<string>', // REQUIRED
'StartingBlockIndex' => <integer>,
]);
Parameter Details
Members
- FirstSnapshotId
-
- Type: string
The ID of the first snapshot to use for the comparison.
The
FirstSnapshotIDparameter must be specified with aSecondSnapshotIdparameter; otherwise, an error occurs. - MaxResults
-
- Type: int
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
nullwhen there are no more blocks to return. - NextToken
-
- Type: string
The token to request the next page of results.
If you specify NextToken, then StartingBlockIndex is ignored.
- SecondSnapshotId
-
- Required: Yes
- Type: string
The ID of the second snapshot to use for the comparison.
The
SecondSnapshotIdparameter must be specified with aFirstSnapshotIDparameter; otherwise, an error occurs. - StartingBlockIndex
-
- Type: int
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.
If you specify NextToken, then StartingBlockIndex is ignored.
Result Syntax
[
'BlockSize' => <integer>,
'ChangedBlocks' => [
[
'BlockIndex' => <integer>,
'FirstBlockToken' => '<string>',
'SecondBlockToken' => '<string>',
],
// ...
],
'ExpiryTime' => <DateTime>,
'NextToken' => '<string>',
'VolumeSize' => <integer>,
]
Result Details
Members
- BlockSize
-
- Type: int
The size of the blocks in the snapshot, in bytes.
- ChangedBlocks
-
- Type: Array of ChangedBlock structures
An array of objects containing information about the changed blocks.
- ExpiryTime
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The time when the
BlockTokenexpires. - NextToken
-
- Type: string
The token to use to retrieve the next page of results. This value is null when there are no more results to return.
- VolumeSize
-
- Type: long (int|float)
The size of the volume in GB.
Errors
-
You do not have sufficient access to perform this action.
-
The input fails to satisfy the constraints of the EBS direct APIs.
-
The specified resource does not exist.
-
The number of API requests has exceed the maximum allowed API request throttling limit.
-
ServiceQuotaExceededException:
Your current service quotas do not allow you to perform this action.
-
An internal error has occurred.
ListSnapshotBlocks
$result = $client->listSnapshotBlocks([/* ... */]); $promise = $client->listSnapshotBlocksAsync([/* ... */]);
Returns information about the blocks in an Amazon Elastic Block Store snapshot.
Parameter Syntax
$result = $client->listSnapshotBlocks([
'MaxResults' => <integer>,
'NextToken' => '<string>',
'SnapshotId' => '<string>', // REQUIRED
'StartingBlockIndex' => <integer>,
]);
Parameter Details
Members
- MaxResults
-
- Type: int
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
nullwhen there are no more blocks to return. - NextToken
-
- Type: string
The token to request the next page of results.
If you specify NextToken, then StartingBlockIndex is ignored.
- SnapshotId
-
- Required: Yes
- Type: string
The ID of the snapshot from which to get block indexes and block tokens.
- StartingBlockIndex
-
- Type: int
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.
If you specify NextToken, then StartingBlockIndex is ignored.
Result Syntax
[
'BlockSize' => <integer>,
'Blocks' => [
[
'BlockIndex' => <integer>,
'BlockToken' => '<string>',
],
// ...
],
'ExpiryTime' => <DateTime>,
'NextToken' => '<string>',
'VolumeSize' => <integer>,
]
Result Details
Members
- BlockSize
-
- Type: int
The size of the blocks in the snapshot, in bytes.
- Blocks
-
- Type: Array of Block structures
An array of objects containing information about the blocks.
- ExpiryTime
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The time when the
BlockTokenexpires. - NextToken
-
- Type: string
The token to use to retrieve the next page of results. This value is null when there are no more results to return.
- VolumeSize
-
- Type: long (int|float)
The size of the volume in GB.
Errors
-
You do not have sufficient access to perform this action.
-
The input fails to satisfy the constraints of the EBS direct APIs.
-
The specified resource does not exist.
-
The number of API requests has exceed the maximum allowed API request throttling limit.
-
ServiceQuotaExceededException:
Your current service quotas do not allow you to perform this action.
-
An internal error has occurred.
PutSnapshotBlock
$result = $client->putSnapshotBlock([/* ... */]); $promise = $client->putSnapshotBlockAsync([/* ... */]);
Writes a block of data to a snapshot. If the specified 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.
Parameter Syntax
$result = $client->putSnapshotBlock([
'BlockData' => <string || resource || Psr\Http\Message\StreamInterface>, // REQUIRED
'BlockIndex' => <integer>, // REQUIRED
'Checksum' => '<string>', // REQUIRED
'ChecksumAlgorithm' => 'SHA256', // REQUIRED
'DataLength' => <integer>, // REQUIRED
'Progress' => <integer>,
'SnapshotId' => '<string>', // REQUIRED
]);
Parameter Details
Members
- BlockData
-
- Required: Yes
- Type: blob (string|resource|Psr\Http\Message\StreamInterface)
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.
- BlockIndex
-
- Required: Yes
- Type: int
The block index of the block in which to write the data. A block index is a logical index in units of
512KiB 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 be512KiB aligned. - Checksum
-
- Required: Yes
- Type: string
A Base64-encoded SHA256 checksum of the data. Only SHA256 checksums are supported.
- ChecksumAlgorithm
-
- Required: Yes
- Type: string
The algorithm used to generate the checksum. Currently, the only supported algorithm is
SHA256. - DataLength
-
- Required: Yes
- Type: int
The size of the data to write to the block, in bytes. Currently, the only supported size is
524288bytes.Valid values:
524288 - Progress
-
- Type: int
The progress of the write process, as a percentage.
- SnapshotId
-
- Required: Yes
- Type: string
The ID of the snapshot.
If the specified 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..
Result Syntax
[
'Checksum' => '<string>',
'ChecksumAlgorithm' => 'SHA256',
]
Result Details
Members
Errors
-
You do not have sufficient access to perform this action.
-
The input fails to satisfy the constraints of the EBS direct APIs.
-
The specified resource does not exist.
-
The number of API requests has exceed the maximum allowed API request throttling limit.
-
ServiceQuotaExceededException:
Your current service quotas do not allow you to perform this action.
-
An internal error has occurred.
StartSnapshot
$result = $client->startSnapshot([/* ... */]); $promise = $client->startSnapshotAsync([/* ... */]);
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.
Parameter Syntax
$result = $client->startSnapshot([
'ClientToken' => '<string>',
'Description' => '<string>',
'Encrypted' => true || false,
'KmsKeyArn' => '<string>',
'ParentSnapshotId' => '<string>',
'Tags' => [
[
'Key' => '<string>',
'Value' => '<string>',
],
// ...
],
'Timeout' => <integer>,
'VolumeSize' => <integer>, // REQUIRED
]);
Parameter Details
Members
- ClientToken
-
- Type: string
A unique, case-sensitive identifier 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 effect.
If you do not specify a client token, one is automatically generated by the Amazon Web Services SDK.
For more information, see Idempotency for StartSnapshot API in the Amazon Elastic Compute Cloud User Guide.
- Description
-
- Type: string
A description for the snapshot.
- Encrypted
-
- Type: boolean
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 Amazon Web Services account is enabled for encryption by default. For more information, see Using encryption in the Amazon Elastic Compute Cloud User Guide.
To create an encrypted snapshot, you must have permission to use the KMS key. For more information, see Permissions to use Key Management Service keys in the Amazon Elastic Compute Cloud User Guide.
- KmsKeyArn
-
- Type: string
The Amazon Resource Name (ARN) of the Key Management Service (KMS) key to be used to encrypt the snapshot.
The encryption status of the snapshot depends on the values that you specify for Encrypted, KmsKeyArn, and ParentSnapshotId, and whether your Amazon Web Services account is enabled for encryption by default. For more information, see Using encryption in the Amazon Elastic Compute Cloud User Guide.
To create an encrypted snapshot, you must have permission to use the KMS key. For more information, see Permissions to use Key Management Service keys in the Amazon Elastic Compute Cloud User Guide.
- ParentSnapshotId
-
- Type: string
The ID of the parent snapshot. If there is no parent snapshot, or if you are creating the first 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.The encryption status of the snapshot depends on the values that you specify for Encrypted, KmsKeyArn, and ParentSnapshotId, and whether your Amazon Web Services account is enabled for encryption by default. For more information, see Using encryption in the Amazon Elastic Compute Cloud User Guide.
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 Key Management Service keys in the Amazon Elastic Compute Cloud User Guide.
- Tags
-
- Type: Array of Tag structures
The tags to apply to the snapshot.
- Timeout
-
- Type: int
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 specified, the timeout defaults to
60minutes. - VolumeSize
-
- Required: Yes
- Type: long (int|float)
The size of the volume, in GiB. The maximum size is
65536GiB (64 TiB).
Result Syntax
[
'BlockSize' => <integer>,
'Description' => '<string>',
'KmsKeyArn' => '<string>',
'OwnerId' => '<string>',
'ParentSnapshotId' => '<string>',
'SnapshotId' => '<string>',
'StartTime' => <DateTime>,
'Status' => 'completed|pending|error',
'Tags' => [
[
'Key' => '<string>',
'Value' => '<string>',
],
// ...
],
'VolumeSize' => <integer>,
]
Result Details
Members
- BlockSize
-
- Type: int
The size of the blocks in the snapshot, in bytes.
- Description
-
- Type: string
The description of the snapshot.
- KmsKeyArn
-
- Type: string
The Amazon Resource Name (ARN) of the Key Management Service (KMS) key used to encrypt the snapshot.
- OwnerId
-
- Type: string
The Amazon Web Services account ID of the snapshot owner.
- ParentSnapshotId
-
- Type: string
The ID of the parent snapshot.
- SnapshotId
-
- Type: string
The ID of the snapshot.
- StartTime
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The timestamp when the snapshot was created.
- Status
-
- Type: string
The status of the snapshot.
- Tags
-
- Type: Array of Tag structures
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.
- VolumeSize
-
- Type: long (int|float)
The size of the volume, in GiB.
Errors
-
You do not have sufficient access to perform this action.
-
The input fails to satisfy the constraints of the EBS direct APIs.
-
The number of API requests has exceed the maximum allowed API request throttling limit.
-
The specified resource does not exist.
-
ServiceQuotaExceededException:
Your current service quotas do not allow you to perform this action.
-
An internal error has occurred.
-
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.
-
The request uses the same client token as a previous, but non-identical request.
Shapes
AccessDeniedException
Description
You do not have sufficient access to perform this action.
Members
Block
Description
A block of data in an Amazon Elastic Block Store snapshot.
Members
ChangedBlock
Description
A block of data in an Amazon Elastic Block Store snapshot that is different from another snapshot of the same volume/snapshot lineage.
Members
- BlockIndex
-
- Type: int
The block index.
- FirstBlockToken
-
- Type: string
The block token for the block index of the
FirstSnapshotIdspecified in theListChangedBlocksoperation. This value is absent if the first snapshot does not have the changed block that is on the second snapshot. - SecondBlockToken
-
- Type: string
The block token for the block index of the
SecondSnapshotIdspecified in theListChangedBlocksoperation.
ConcurrentLimitExceededException
Description
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.
Members
ConflictException
Description
The request uses the same client token as a previous, but non-identical request.
Members
InternalServerException
RequestThrottledException
Description
The number of API requests has exceed the maximum allowed API request throttling limit.
Members
ResourceNotFoundException
Description
The specified resource does not exist.
Members
ServiceQuotaExceededException
Description
Your current service quotas do not allow you to perform this action.
Members
Tag
Description
Describes a tag.