Struct bonsaidb::keystorage::s3::aws_sdk_s3::operation::get_object::builders::GetObjectFluentBuilder

pub struct GetObjectFluentBuilder { /* private fields */ }

Fluent builder constructing a request to GetObject.

Retrieves objects from Amazon S3. To use GET, you must have READ access to the object. If you grant READ access to the anonymous user, you can return the object without using an authorization header.

An Amazon S3 bucket has no directory hierarchy such as you would find in a typical computer file system. You can, however, create a logical hierarchy by using object key names that imply a folder structure. For example, instead of naming an object sample.jpg, you can name it photos/2006/February/sample.jpg.

To get an object from such a logical hierarchy, specify the full key name for the object in the GET operation. For a virtual hosted-style request example, if you have the object photos/2006/February/sample.jpg, specify the resource as /photos/2006/February/sample.jpg. For a path-style request example, if you have the object photos/2006/February/sample.jpg in the bucket named examplebucket, specify the resource as /examplebucket/photos/2006/February/sample.jpg. For more information about request types, see HTTP Host Header Bucket Specification.

For more information about returning the ACL of an object, see GetObjectAcl.

If the object you are retrieving is stored in the S3 Glacier Flexible Retrieval or S3 Glacier Deep Archive storage class, or S3 Intelligent-Tiering Archive or S3 Intelligent-Tiering Deep Archive tiers, before you can retrieve the object you must first restore a copy using RestoreObject. Otherwise, this action returns an InvalidObjectState error. For information about restoring archived objects, see Restoring Archived Objects.

Encryption request headers, like x-amz-server-side-encryption, should not be sent for GET requests if your object uses server-side encryption with Key Management Service (KMS) keys (SSE-KMS), dual-layer server-side encryption with Amazon Web Services KMS keys (DSSE-KMS), or server-side encryption with Amazon S3 managed encryption keys (SSE-S3). If your object does use these types of keys, you’ll get an HTTP 400 Bad Request error.

If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-C) when you store the object in Amazon S3, then when you GET the object, you must use the following headers:

• x-amz-server-side-encryption-customer-algorithm

• x-amz-server-side-encryption-customer-key

• x-amz-server-side-encryption-customer-key-MD5

For more information about SSE-C, see Server-Side Encryption (Using Customer-Provided Encryption Keys).

Assuming you have the relevant permission to read object tags, the response also returns the x-amz-tagging-count header that provides the count of number of tags associated with the object. You can use GetObjectTagging to retrieve the tag set associated with an object.

Permissions

You need the relevant read object (or version) permission for this operation. For more information, see Specifying Permissions in a Policy. If the object that you request doesn’t exist, the error that Amazon S3 returns depends on whether you also have the s3:ListBucket permission.

If you have the s3:ListBucket permission on the bucket, Amazon S3 returns an HTTP status code 404 (Not Found) error.

If you don’t have the s3:ListBucket permission, Amazon S3 returns an HTTP status code 403 ("access denied") error.

Versioning

By default, the GET action returns the current version of an object. To return a different version, use the versionId subresource.

• If you supply a versionId, you need the s3:GetObjectVersion permission to access a specific version of an object. If you request a specific version, you do not need to have the s3:GetObject permission. If you request the current version without a specific version ID, only s3:GetObject permission is required. s3:GetObjectVersion permission won't be required.

• If the current version of the object is a delete marker, Amazon S3 behaves as if the object was deleted and includes x-amz-delete-marker: true in the response.

For more information about versioning, see PutBucketVersioning.

Overriding Response Header Values

There are times when you want to override certain response header values in a GET response. For example, you might override the Content-Disposition response header value in your GET request.

You can override values for a set of response headers using the following query parameters. These response header values are sent only on a successful request, that is, when status code 200 OK is returned. The set of headers you can override using these parameters is a subset of the headers that Amazon S3 accepts when you create an object. The response headers that you can override for the GET response are Content-Type, Content-Language, Expires, Cache-Control, Content-Disposition, and Content-Encoding. To override these header values in the GET response, you use the following request parameters.

You must sign the request, either using an Authorization header or a presigned URL, when using these parameters. They cannot be used with an unsigned (anonymous) request.

• response-content-type

• response-content-language

• response-expires

• response-cache-control

• response-content-disposition

• response-content-encoding

Overriding Response Header Values

If both of the If-Match and If-Unmodified-Since headers are present in the request as follows: If-Match condition evaluates to true, and; If-Unmodified-Since condition evaluates to false; then, S3 returns 200 OK and the data requested.

If both of the If-None-Match and If-Modified-Since headers are present in the request as follows: If-None-Match condition evaluates to false, and; If-Modified-Since condition evaluates to true; then, S3 returns 304 Not Modified response code.

For more information about conditional requests, see RFC 7232.

The following operations are related to GetObject:

• ListBuckets

• GetObjectAcl

Implementations

impl GetObjectFluentBuilder

pub fn as_input(&self) -> &GetObjectInputBuilder

Access the GetObject as a reference.

pub async fn send( self ) -> impl Future<Output = Result<GetObjectOutput, SdkError<GetObjectError, Response<SdkBody>>>>

Sends the request and returns the response.

If an error occurs, an SdkError will be returned with additional details that can be matched against.

By default, any retryable failures will be retried twice. Retry behavior is configurable with the RetryConfig, which can be set when configuring the client.

pub async fn customize( self ) -> impl Future<Output = Result<CustomizableOperation<GetObjectOutput, GetObjectError, GetObjectFluentBuilder>, SdkError<GetObjectError, Response>>>

Consumes this builder, creating a customizable operation that can be modified before being sent.

pub async fn presigned( self, presigning_config: PresigningConfig ) -> impl Future<Output = Result<PresignedRequest, SdkError<GetObjectError, Response<SdkBody>>>>

Creates a presigned request for this operation.

The presigning_config provides additional presigning-specific config values, such as the amount of time the request should be valid for after creation.

Presigned requests can be given to other users or applications to access a resource or perform an operation without having access to the AWS security credentials.

Important: If you’re using credentials that can expire, such as those from STS AssumeRole or SSO, then the presigned request can only be valid for as long as the credentials used to create it are.

pub fn bucket(self, input: impl Into<String>) -> GetObjectFluentBuilder

The bucket name containing the object.

When using this action with an access point, you must direct requests to the access point hostname. The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. When using this action with an access point through the Amazon Web Services SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, see Using access points in the Amazon S3 User Guide.

When using an Object Lambda access point the hostname takes the form AccessPointName-AccountId.s3-object-lambda.Region.amazonaws.com.

When you use this action with Amazon S3 on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When you use this action with S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts? in the Amazon S3 User Guide.

pub fn set_bucket(self, input: Option<String>) -> GetObjectFluentBuilder

The bucket name containing the object.

When using this action with an access point, you must direct requests to the access point hostname. The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. When using this action with an access point through the Amazon Web Services SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, see Using access points in the Amazon S3 User Guide.

When using an Object Lambda access point the hostname takes the form AccessPointName-AccountId.s3-object-lambda.Region.amazonaws.com.

When you use this action with Amazon S3 on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When you use this action with S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts? in the Amazon S3 User Guide.

pub fn get_bucket(&self) -> &Option<String>

The bucket name containing the object.

When using this action with an access point, you must direct requests to the access point hostname. The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. When using this action with an access point through the Amazon Web Services SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, see Using access points in the Amazon S3 User Guide.

When using an Object Lambda access point the hostname takes the form AccessPointName-AccountId.s3-object-lambda.Region.amazonaws.com.

When you use this action with Amazon S3 on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When you use this action with S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts? in the Amazon S3 User Guide.

pub fn if_match(self, input: impl Into<String>) -> GetObjectFluentBuilder

Return the object only if its entity tag (ETag) is the same as the one specified; otherwise, return a 412 (precondition failed) error.

pub fn set_if_match(self, input: Option<String>) -> GetObjectFluentBuilder

Return the object only if its entity tag (ETag) is the same as the one specified; otherwise, return a 412 (precondition failed) error.

pub fn get_if_match(&self) -> &Option<String>

Return the object only if its entity tag (ETag) is the same as the one specified; otherwise, return a 412 (precondition failed) error.

pub fn if_modified_since(self, input: DateTime) -> GetObjectFluentBuilder

Return the object only if it has been modified since the specified time; otherwise, return a 304 (not modified) error.

pub fn set_if_modified_since( self, input: Option<DateTime> ) -> GetObjectFluentBuilder

Return the object only if it has been modified since the specified time; otherwise, return a 304 (not modified) error.

pub fn get_if_modified_since(&self) -> &Option<DateTime>

Return the object only if it has been modified since the specified time; otherwise, return a 304 (not modified) error.

pub fn if_none_match(self, input: impl Into<String>) -> GetObjectFluentBuilder

Return the object only if its entity tag (ETag) is different from the one specified; otherwise, return a 304 (not modified) error.

pub fn set_if_none_match(self, input: Option<String>) -> GetObjectFluentBuilder

Return the object only if its entity tag (ETag) is different from the one specified; otherwise, return a 304 (not modified) error.

pub fn get_if_none_match(&self) -> &Option<String>

Return the object only if its entity tag (ETag) is different from the one specified; otherwise, return a 304 (not modified) error.

pub fn if_unmodified_since(self, input: DateTime) -> GetObjectFluentBuilder

Return the object only if it has not been modified since the specified time; otherwise, return a 412 (precondition failed) error.

pub fn set_if_unmodified_since( self, input: Option<DateTime> ) -> GetObjectFluentBuilder

Return the object only if it has not been modified since the specified time; otherwise, return a 412 (precondition failed) error.

pub fn get_if_unmodified_since(&self) -> &Option<DateTime>

Return the object only if it has not been modified since the specified time; otherwise, return a 412 (precondition failed) error.

pub fn key(self, input: impl Into<String>) -> GetObjectFluentBuilder

Key of the object to get.

pub fn set_key(self, input: Option<String>) -> GetObjectFluentBuilder

Key of the object to get.

pub fn get_key(&self) -> &Option<String>

Key of the object to get.

pub fn range(self, input: impl Into<String>) -> GetObjectFluentBuilder

Downloads the specified range bytes of an object. For more information about the HTTP Range header, see https://www.rfc-editor.org/rfc/rfc9110.html#name-range.

Amazon S3 doesn't support retrieving multiple ranges of data per GET request.

pub fn set_range(self, input: Option<String>) -> GetObjectFluentBuilder

Downloads the specified range bytes of an object. For more information about the HTTP Range header, see https://www.rfc-editor.org/rfc/rfc9110.html#name-range.

Amazon S3 doesn't support retrieving multiple ranges of data per GET request.

pub fn get_range(&self) -> &Option<String>

Downloads the specified range bytes of an object. For more information about the HTTP Range header, see https://www.rfc-editor.org/rfc/rfc9110.html#name-range.

Amazon S3 doesn't support retrieving multiple ranges of data per GET request.

pub fn response_cache_control( self, input: impl Into<String> ) -> GetObjectFluentBuilder

Sets the Cache-Control header of the response.

pub fn set_response_cache_control( self, input: Option<String> ) -> GetObjectFluentBuilder

Sets the Cache-Control header of the response.

pub fn get_response_cache_control(&self) -> &Option<String>

Sets the Cache-Control header of the response.

pub fn response_content_disposition( self, input: impl Into<String> ) -> GetObjectFluentBuilder

Sets the Content-Disposition header of the response

pub fn set_response_content_disposition( self, input: Option<String> ) -> GetObjectFluentBuilder

Sets the Content-Disposition header of the response

pub fn get_response_content_disposition(&self) -> &Option<String>

Sets the Content-Disposition header of the response

pub fn response_content_encoding( self, input: impl Into<String> ) -> GetObjectFluentBuilder

Sets the Content-Encoding header of the response.

pub fn set_response_content_encoding( self, input: Option<String> ) -> GetObjectFluentBuilder

Sets the Content-Encoding header of the response.

pub fn get_response_content_encoding(&self) -> &Option<String>

Sets the Content-Encoding header of the response.

pub fn response_content_language( self, input: impl Into<String> ) -> GetObjectFluentBuilder

Sets the Content-Language header of the response.

pub fn set_response_content_language( self, input: Option<String> ) -> GetObjectFluentBuilder

Sets the Content-Language header of the response.

pub fn get_response_content_language(&self) -> &Option<String>

Sets the Content-Language header of the response.

pub fn response_content_type( self, input: impl Into<String> ) -> GetObjectFluentBuilder

Sets the Content-Type header of the response.

pub fn set_response_content_type( self, input: Option<String> ) -> GetObjectFluentBuilder

Sets the Content-Type header of the response.

pub fn get_response_content_type(&self) -> &Option<String>

Sets the Content-Type header of the response.

pub fn response_expires(self, input: DateTime) -> GetObjectFluentBuilder

Sets the Expires header of the response.

pub fn set_response_expires( self, input: Option<DateTime> ) -> GetObjectFluentBuilder

Sets the Expires header of the response.

pub fn get_response_expires(&self) -> &Option<DateTime>

Sets the Expires header of the response.

pub fn version_id(self, input: impl Into<String>) -> GetObjectFluentBuilder

VersionId used to reference a specific version of the object.

pub fn set_version_id(self, input: Option<String>) -> GetObjectFluentBuilder

VersionId used to reference a specific version of the object.

pub fn get_version_id(&self) -> &Option<String>

VersionId used to reference a specific version of the object.

pub fn sse_customer_algorithm( self, input: impl Into<String> ) -> GetObjectFluentBuilder

Specifies the algorithm to use to when decrypting the object (for example, AES256).

pub fn set_sse_customer_algorithm( self, input: Option<String> ) -> GetObjectFluentBuilder

Specifies the algorithm to use to when decrypting the object (for example, AES256).

pub fn get_sse_customer_algorithm(&self) -> &Option<String>

Specifies the algorithm to use to when decrypting the object (for example, AES256).

pub fn sse_customer_key( self, input: impl Into<String> ) -> GetObjectFluentBuilder

Specifies the customer-provided encryption key for Amazon S3 used to encrypt the data. This value is used to decrypt the object when recovering it and must match the one used when storing the data. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.

pub fn set_sse_customer_key( self, input: Option<String> ) -> GetObjectFluentBuilder

Specifies the customer-provided encryption key for Amazon S3 used to encrypt the data. This value is used to decrypt the object when recovering it and must match the one used when storing the data. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.

pub fn get_sse_customer_key(&self) -> &Option<String>

Specifies the customer-provided encryption key for Amazon S3 used to encrypt the data. This value is used to decrypt the object when recovering it and must match the one used when storing the data. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.

pub fn sse_customer_key_md5( self, input: impl Into<String> ) -> GetObjectFluentBuilder

Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure that the encryption key was transmitted without error.

pub fn set_sse_customer_key_md5( self, input: Option<String> ) -> GetObjectFluentBuilder

Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure that the encryption key was transmitted without error.

pub fn get_sse_customer_key_md5(&self) -> &Option<String>

Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure that the encryption key was transmitted without error.

pub fn request_payer(self, input: RequestPayer) -> GetObjectFluentBuilder

Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. If either the source or destination Amazon S3 bucket has Requester Pays enabled, the requester will pay for corresponding charges to copy the object. For information about downloading objects from Requester Pays buckets, see Downloading Objects in Requester Pays Buckets in the Amazon S3 User Guide.

pub fn set_request_payer( self, input: Option<RequestPayer> ) -> GetObjectFluentBuilder

Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. If either the source or destination Amazon S3 bucket has Requester Pays enabled, the requester will pay for corresponding charges to copy the object. For information about downloading objects from Requester Pays buckets, see Downloading Objects in Requester Pays Buckets in the Amazon S3 User Guide.

pub fn get_request_payer(&self) -> &Option<RequestPayer>

Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. If either the source or destination Amazon S3 bucket has Requester Pays enabled, the requester will pay for corresponding charges to copy the object. For information about downloading objects from Requester Pays buckets, see Downloading Objects in Requester Pays Buckets in the Amazon S3 User Guide.

pub fn part_number(self, input: i32) -> GetObjectFluentBuilder

Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a 'ranged' GET request for the part specified. Useful for downloading just a part of an object.

pub fn set_part_number(self, input: Option<i32>) -> GetObjectFluentBuilder

Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a 'ranged' GET request for the part specified. Useful for downloading just a part of an object.

pub fn get_part_number(&self) -> &Option<i32>

Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a 'ranged' GET request for the part specified. Useful for downloading just a part of an object.

pub fn expected_bucket_owner( self, input: impl Into<String> ) -> GetObjectFluentBuilder

The account ID of the expected bucket owner. If the bucket is owned by a different account, the request fails with the HTTP status code 403 Forbidden (access denied).

pub fn set_expected_bucket_owner( self, input: Option<String> ) -> GetObjectFluentBuilder

The account ID of the expected bucket owner. If the bucket is owned by a different account, the request fails with the HTTP status code 403 Forbidden (access denied).

pub fn get_expected_bucket_owner(&self) -> &Option<String>

The account ID of the expected bucket owner. If the bucket is owned by a different account, the request fails with the HTTP status code 403 Forbidden (access denied).

pub fn checksum_mode(self, input: ChecksumMode) -> GetObjectFluentBuilder

To retrieve the checksum, this mode must be enabled.

pub fn set_checksum_mode( self, input: Option<ChecksumMode> ) -> GetObjectFluentBuilder

To retrieve the checksum, this mode must be enabled.

pub fn get_checksum_mode(&self) -> &Option<ChecksumMode>

To retrieve the checksum, this mode must be enabled.

Trait Implementations

impl Clone for GetObjectFluentBuilder

fn clone(&self) -> GetObjectFluentBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GetObjectFluentBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.