Struct aws_sdk_ebs::Client
source · pub struct Client { /* private fields */ }
Expand description
Client for Amazon Elastic Block Store
Client for invoking operations on Amazon Elastic Block Store. Each operation on Amazon Elastic Block Store is a method on this
this struct. .send()
MUST be invoked on the generated operations to dispatch the request to the service.
§Constructing a Client
A Config
is required to construct a client. For most use cases, the aws-config
crate should be used to automatically resolve this config using
aws_config::load_from_env()
, since this will resolve an SdkConfig
which can be shared
across multiple different AWS SDK clients. This config resolution process can be customized
by calling aws_config::from_env()
instead, which returns a ConfigLoader
that uses
the builder pattern to customize the default config.
In the simplest case, creating a client looks as follows:
let config = aws_config::load_from_env().await;
let client = aws_sdk_ebs::Client::new(&config);
Occasionally, SDKs may have additional service-specific values that can be set on the Config
that
is absent from SdkConfig
, or slightly different settings for a specific client may be desired.
The Config
struct implements From<&SdkConfig>
, so setting these specific settings can be
done as follows:
let sdk_config = ::aws_config::load_from_env().await;
let config = aws_sdk_ebs::config::Builder::from(&sdk_config)
.some_service_specific_setting("value")
.build();
See the aws-config
docs and Config
for more information on customizing configuration.
Note: Client construction is expensive due to connection thread pool initialization, and should be done once at application start-up.
§Using the Client
A client has a function for every operation that can be performed by the service.
For example, the CompleteSnapshot
operation has
a Client::complete_snapshot
, function which returns a builder for that operation.
The fluent builder ultimately has a send()
function that returns an async future that
returns a result, as illustrated below:
let result = client.complete_snapshot()
.snapshot_id("example")
.send()
.await;
The underlying HTTP requests that get made by this can be modified with the customize_operation
function on the fluent builder. See the customize
module for more
information.
Implementations§
source§impl Client
impl Client
sourcepub fn complete_snapshot(&self) -> CompleteSnapshotFluentBuilder
pub fn complete_snapshot(&self) -> CompleteSnapshotFluentBuilder
Constructs a fluent builder for the CompleteSnapshot
operation.
- The fluent builder is configurable:
snapshot_id(impl Into<String>)
/set_snapshot_id(Option<String>)
:
required: trueThe ID of the snapshot.
changed_blocks_count(i32)
/set_changed_blocks_count(Option<i32>)
:
required: trueThe number of blocks that were written to the snapshot.
checksum(impl Into<String>)
/set_checksum(Option<String>)
:
required: falseAn 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.
checksum_algorithm(ChecksumAlgorithm)
/set_checksum_algorithm(Option<ChecksumAlgorithm>)
:
required: falseThe algorithm used to generate the checksum. Currently, the only supported algorithm is
SHA256
.checksum_aggregation_method(ChecksumAggregationMethod)
/set_checksum_aggregation_method(Option<ChecksumAggregationMethod>)
:
required: falseThe aggregation method used to generate the checksum. Currently, the only supported aggregation method is
LINEAR
.
- On success, responds with
CompleteSnapshotOutput
with field(s):status(Option<Status>)
:The status of the snapshot.
- On failure, responds with
SdkError<CompleteSnapshotError>
source§impl Client
impl Client
sourcepub fn get_snapshot_block(&self) -> GetSnapshotBlockFluentBuilder
pub fn get_snapshot_block(&self) -> GetSnapshotBlockFluentBuilder
Constructs a fluent builder for the GetSnapshotBlock
operation.
- The fluent builder is configurable:
snapshot_id(impl Into<String>)
/set_snapshot_id(Option<String>)
:
required: trueThe 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.
block_index(i32)
/set_block_index(Option<i32>)
:
required: trueThe block index of the block in which to read the data. A block index is a logical index in units of
512
KiB blocks. To identify the block index, divide the logical offset of the data in the logical volume by the block size (logical offset of data/524288
). The logical offset of the data must be512
KiB aligned.block_token(impl Into<String>)
/set_block_token(Option<String>)
:
required: trueThe block token of the block from which to get data. You can obtain the
BlockToken
by running theListChangedBlocks
orListSnapshotBlocks
operations.
- On success, responds with
GetSnapshotBlockOutput
with field(s):data_length(Option<i32>)
:The size of the data in the block.
block_data(ByteStream)
:The data content of the block.
checksum(Option<String>)
:The checksum generated for the block, which is Base64 encoded.
checksum_algorithm(Option<ChecksumAlgorithm>)
:The algorithm used to generate the checksum for the block, such as SHA256.
- On failure, responds with
SdkError<GetSnapshotBlockError>
source§impl Client
impl Client
sourcepub fn list_changed_blocks(&self) -> ListChangedBlocksFluentBuilder
pub fn list_changed_blocks(&self) -> ListChangedBlocksFluentBuilder
Constructs a fluent builder for the ListChangedBlocks
operation.
This operation supports pagination; See into_paginator()
.
- The fluent builder is configurable:
first_snapshot_id(impl Into<String>)
/set_first_snapshot_id(Option<String>)
:
required: falseThe ID of the first snapshot to use for the comparison.
The
FirstSnapshotID
parameter must be specified with aSecondSnapshotId
parameter; otherwise, an error occurs.second_snapshot_id(impl Into<String>)
/set_second_snapshot_id(Option<String>)
:
required: trueThe ID of the second snapshot to use for the comparison.
The
SecondSnapshotId
parameter must be specified with aFirstSnapshotID
parameter; otherwise, an error occurs.next_token(impl Into<String>)
/set_next_token(Option<String>)
:
required: falseThe token to request the next page of results.
If you specify NextToken, then StartingBlockIndex is ignored.
max_results(i32)
/set_max_results(Option<i32>)
:
required: falseThe maximum number of blocks to be returned by the request.
Even if additional blocks can be retrieved from the snapshot, the request can return less blocks than MaxResults or an empty array of blocks.
To retrieve the next set of blocks from the snapshot, make another request with the returned NextToken value. The value of NextToken is
null
when there are no more blocks to return.starting_block_index(i32)
/set_starting_block_index(Option<i32>)
:
required: falseThe 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.
- On success, responds with
ListChangedBlocksOutput
with field(s):changed_blocks(Option<Vec::<ChangedBlock>>)
:An array of objects containing information about the changed blocks.
expiry_time(Option<DateTime>)
:The time when the
BlockToken
expires.volume_size(Option<i64>)
:The size of the volume in GB.
block_size(Option<i32>)
:The size of the blocks in the snapshot, in bytes.
next_token(Option<String>)
:The token to use to retrieve the next page of results. This value is null when there are no more results to return.
- On failure, responds with
SdkError<ListChangedBlocksError>
source§impl Client
impl Client
sourcepub fn list_snapshot_blocks(&self) -> ListSnapshotBlocksFluentBuilder
pub fn list_snapshot_blocks(&self) -> ListSnapshotBlocksFluentBuilder
Constructs a fluent builder for the ListSnapshotBlocks
operation.
This operation supports pagination; See into_paginator()
.
- The fluent builder is configurable:
snapshot_id(impl Into<String>)
/set_snapshot_id(Option<String>)
:
required: trueThe ID of the snapshot from which to get block indexes and block tokens.
next_token(impl Into<String>)
/set_next_token(Option<String>)
:
required: falseThe token to request the next page of results.
If you specify NextToken, then StartingBlockIndex is ignored.
max_results(i32)
/set_max_results(Option<i32>)
:
required: falseThe maximum number of blocks to be returned by the request.
Even if additional blocks can be retrieved from the snapshot, the request can return less blocks than MaxResults or an empty array of blocks.
To retrieve the next set of blocks from the snapshot, make another request with the returned NextToken value. The value of NextToken is
null
when there are no more blocks to return.starting_block_index(i32)
/set_starting_block_index(Option<i32>)
:
required: falseThe 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.
- On success, responds with
ListSnapshotBlocksOutput
with field(s):blocks(Option<Vec::<Block>>)
:An array of objects containing information about the blocks.
expiry_time(Option<DateTime>)
:The time when the
BlockToken
expires.volume_size(Option<i64>)
:The size of the volume in GB.
block_size(Option<i32>)
:The size of the blocks in the snapshot, in bytes.
next_token(Option<String>)
:The token to use to retrieve the next page of results. This value is null when there are no more results to return.
- On failure, responds with
SdkError<ListSnapshotBlocksError>
source§impl Client
impl Client
sourcepub fn put_snapshot_block(&self) -> PutSnapshotBlockFluentBuilder
pub fn put_snapshot_block(&self) -> PutSnapshotBlockFluentBuilder
Constructs a fluent builder for the PutSnapshotBlock
operation.
- The fluent builder is configurable:
snapshot_id(impl Into<String>)
/set_snapshot_id(Option<String>)
:
required: trueThe 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..
block_index(i32)
/set_block_index(Option<i32>)
:
required: trueThe block index of the block in which to write the data. A block index is a logical index in units of
512
KiB blocks. To identify the block index, divide the logical offset of the data in the logical volume by the block size (logical offset of data/524288
). The logical offset of the data must be512
KiB aligned.block_data(ByteStream)
/set_block_data(ByteStream)
:
required: trueThe 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.
data_length(i32)
/set_data_length(Option<i32>)
:
required: trueThe size of the data to write to the block, in bytes. Currently, the only supported size is
524288
bytes.Valid values:
524288
progress(i32)
/set_progress(Option<i32>)
:
required: falseThe progress of the write process, as a percentage.
checksum(impl Into<String>)
/set_checksum(Option<String>)
:
required: trueA Base64-encoded SHA256 checksum of the data. Only SHA256 checksums are supported.
checksum_algorithm(ChecksumAlgorithm)
/set_checksum_algorithm(Option<ChecksumAlgorithm>)
:
required: trueThe algorithm used to generate the checksum. Currently, the only supported algorithm is
SHA256
.
- On success, responds with
PutSnapshotBlockOutput
with field(s):checksum(Option<String>)
:The SHA256 checksum generated for the block data by Amazon EBS.
checksum_algorithm(Option<ChecksumAlgorithm>)
:The algorithm used by Amazon EBS to generate the checksum.
- On failure, responds with
SdkError<PutSnapshotBlockError>
source§impl Client
impl Client
sourcepub fn start_snapshot(&self) -> StartSnapshotFluentBuilder
pub fn start_snapshot(&self) -> StartSnapshotFluentBuilder
Constructs a fluent builder for the StartSnapshot
operation.
- The fluent builder is configurable:
volume_size(i64)
/set_volume_size(Option<i64>)
:
required: trueThe size of the volume, in GiB. The maximum size is
65536
GiB (64 TiB).parent_snapshot_id(impl Into<String>)
/set_parent_snapshot_id(Option<String>)
:
required: falseThe 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(Tag)
/set_tags(Option<Vec::<Tag>>)
:
required: falseThe tags to apply to the snapshot.
description(impl Into<String>)
/set_description(Option<String>)
:
required: falseA description for the snapshot.
client_token(impl Into<String>)
/set_client_token(Option<String>)
:
required: falseA 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.
encrypted(bool)
/set_encrypted(Option<bool>)
:
required: falseIndicates 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.
kms_key_arn(impl Into<String>)
/set_kms_key_arn(Option<String>)
:
required: falseThe 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.
timeout(i32)
/set_timeout(Option<i32>)
:
required: falseThe 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
60
minutes.-
- On success, responds with
StartSnapshotOutput
with field(s):description(Option<String>)
:The description of the snapshot.
snapshot_id(Option<String>)
:The ID of the snapshot.
owner_id(Option<String>)
:The Amazon Web Services account ID of the snapshot owner.
status(Option<Status>)
:The status of the snapshot.
start_time(Option<DateTime>)
:The timestamp when the snapshot was created.
volume_size(Option<i64>)
:The size of the volume, in GiB.
block_size(Option<i32>)
:The size of the blocks in the snapshot, in bytes.
tags(Option<Vec::<Tag>>)
: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.
parent_snapshot_id(Option<String>)
:The ID of the parent snapshot.
kms_key_arn(Option<String>)
:The Amazon Resource Name (ARN) of the Key Management Service (KMS) key used to encrypt the snapshot.
sse_type(Option<SseType>)
:Reserved for future use.
- On failure, responds with
SdkError<StartSnapshotError>
source§impl Client
impl Client
sourcepub fn from_conf(conf: Config) -> Self
pub fn from_conf(conf: Config) -> Self
Creates a new client from the service Config
.
§Panics
This method will panic in the following cases:
- Retries or timeouts are enabled without a
sleep_impl
configured. - Identity caching is enabled without a
sleep_impl
andtime_source
configured. - No
behavior_version
is provided.
The panic message for each of these will have instructions on how to resolve them.
source§impl Client
impl Client
sourcepub fn new(sdk_config: &SdkConfig) -> Self
pub fn new(sdk_config: &SdkConfig) -> Self
Creates a new client from an SDK Config.
§Panics
- This method will panic if the
sdk_config
is missing an async sleep implementation. If you experience this panic, set thesleep_impl
on the Config passed into this function to fix it. - This method will panic if the
sdk_config
is missing an HTTP connector. If you experience this panic, set thehttp_connector
on the Config passed into this function to fix it. - This method will panic if no
BehaviorVersion
is provided. If you experience this panic, setbehavior_version
on the Config or enable thebehavior-version-latest
Cargo feature.