public class AmazonS3EncryptionClientV2 extends AmazonS3Client implements AmazonS3EncryptionV2
The encryption materials specified in the constructor will be used to protect the CEK which is then stored along side with the S3 object.
For some code examples, see:
https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/examples-crypto.html
https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/examples-crypto-kms.html
https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/examples-crypto-masterkey.html
awsCredentialsProvider, configFactory, errorResponseHandler, S3_SERVICE_NAME
client, clientConfiguration, endpoint, isEndpointOverridden, LOGGING_AWS_REQUEST_METRIC, requestHandler2s, timeOffset
ENDPOINT_PREFIX
Modifier and Type | Method and Description |
---|---|
void |
abortMultipartUpload(AbortMultipartUploadRequest req)
Aborts a multipart upload.
|
CompleteMultipartUploadResult |
completeMultipartUpload(CompleteMultipartUploadRequest req)
Completes a multipart upload by assembling previously uploaded parts.
|
CopyPartResult |
copyPart(CopyPartRequest copyPartRequest)
Copies a source object to a part of a multipart upload.
|
void |
deleteObject(DeleteObjectRequest req)
Deletes the specified object in the specified bucket.
|
static AmazonS3EncryptionClientV2Builder |
encryptionBuilder() |
CryptoConfigurationV2 |
getCryptoConfiguration() |
EncryptionMaterialsProvider |
getEncryptionMaterialsProvider() |
AWSKMS |
getKmsClient()
Returns the kmsClient that was supplied to this encryption client, or
null if it wasn't set.
|
S3Object |
getObject(GetObjectRequest req)
Retrieves objects from Amazon S3.
|
ObjectMetadata |
getObject(GetObjectRequest req,
File dest)
Retrieves objects from Amazon S3.
|
InitiateMultipartUploadResult |
initiateMultipartUpload(InitiateMultipartUploadRequest req)
Initiates a multipart upload and returns an InitiateMultipartUploadResult
which contains an upload ID.
|
PutObjectResult |
putInstructionFile(PutInstructionFileRequest req)
Creates a new crypto instruction file by re-encrypting the CEK of an
existing encrypted S3 object with a new encryption material identifiable
via a new set of material description.
|
PutObjectResult |
putObject(PutObjectRequest req)
Uploads a new object to the specified Amazon S3 bucket.
|
void |
shutdown()
Shuts down this client object, releasing any resources that might be held
open.
|
CompleteMultipartUploadResult |
uploadObject(UploadObjectRequest req)
Used for performance testing purposes only.
|
UploadPartResult |
uploadPart(UploadPartRequest uploadPartRequest)
Uploads a part in a multipart upload.
|
builder, changeObjectStorageClass, copyObject, copyObject, createBucket, createBucket, createBucket, createBucket, createRequest, createRequest, createSigner, createSigner, createSignerProvider, deleteBucket, deleteBucket, deleteBucketAnalyticsConfiguration, deleteBucketAnalyticsConfiguration, deleteBucketCrossOriginConfiguration, deleteBucketCrossOriginConfiguration, deleteBucketEncryption, deleteBucketEncryption, deleteBucketIntelligentTieringConfiguration, deleteBucketIntelligentTieringConfiguration, deleteBucketInventoryConfiguration, deleteBucketInventoryConfiguration, deleteBucketLifecycleConfiguration, deleteBucketLifecycleConfiguration, deleteBucketMetricsConfiguration, deleteBucketMetricsConfiguration, deleteBucketOwnershipControls, deleteBucketPolicy, deleteBucketPolicy, deleteBucketReplicationConfiguration, deleteBucketReplicationConfiguration, deleteBucketTaggingConfiguration, deleteBucketTaggingConfiguration, deleteBucketWebsiteConfiguration, deleteBucketWebsiteConfiguration, deleteObject, deleteObjects, deleteObjectTagging, deletePublicAccessBlock, deleteVersion, deleteVersion, disableRequesterPays, doesBucketExist, doesBucketExistV2, doesObjectExist, download, download, enableRequesterPays, generatePresignedUrl, generatePresignedUrl, generatePresignedUrl, getBucketAccelerateConfiguration, getBucketAccelerateConfiguration, getBucketAcl, getBucketAcl, getBucketAnalyticsConfiguration, getBucketAnalyticsConfiguration, getBucketCrossOriginConfiguration, getBucketCrossOriginConfiguration, getBucketEncryption, getBucketEncryption, getBucketIntelligentTieringConfiguration, getBucketIntelligentTieringConfiguration, getBucketInventoryConfiguration, getBucketInventoryConfiguration, getBucketLifecycleConfiguration, getBucketLifecycleConfiguration, getBucketLocation, getBucketLocation, getBucketLoggingConfiguration, getBucketLoggingConfiguration, getBucketMetricsConfiguration, getBucketMetricsConfiguration, getBucketNotificationConfiguration, getBucketNotificationConfiguration, getBucketOwnershipControls, getBucketPolicy, getBucketPolicy, getBucketPolicyStatus, getBucketReplicationConfiguration, getBucketReplicationConfiguration, getBucketTaggingConfiguration, getBucketTaggingConfiguration, getBucketVersioningConfiguration, getBucketVersioningConfiguration, getBucketWebsiteConfiguration, getBucketWebsiteConfiguration, getCachedResponseMetadata, getObject, getObjectAcl, getObjectAcl, getObjectAcl, getObjectAsString, getObjectLegalHold, getObjectLockConfiguration, getObjectMetadata, getObjectMetadata, getObjectRetention, getObjectTagging, getPublicAccessBlock, getRegion, getRegionName, getResourceUrl, getS3AccountOwner, getS3AccountOwner, getUrl, headBucket, isRequesterPaysEnabled, listBucketAnalyticsConfigurations, listBucketIntelligentTieringConfigurations, listBucketInventoryConfigurations, listBucketMetricsConfigurations, listBuckets, listBuckets, listMultipartUploads, listNextBatchOfObjects, listNextBatchOfObjects, listNextBatchOfVersions, listNextBatchOfVersions, listObjects, listObjects, listObjects, listObjectsV2, listObjectsV2, listObjectsV2, listParts, listVersions, listVersions, listVersions, newInitiateMultipartUploadRequest, populateRequesterPaysHeader, populateRequestMetadata, presignRequest, putObject, putObject, putObject, restoreObject, restoreObject, restoreObjectV2, selectObjectContent, setBucketAccelerateConfiguration, setBucketAccelerateConfiguration, setBucketAcl, setBucketAcl, setBucketAcl, setBucketAcl, setBucketAcl, setBucketAnalyticsConfiguration, setBucketAnalyticsConfiguration, setBucketCrossOriginConfiguration, setBucketCrossOriginConfiguration, setBucketEncryption, setBucketIntelligentTieringConfiguration, setBucketIntelligentTieringConfiguration, setBucketInventoryConfiguration, setBucketInventoryConfiguration, setBucketLifecycleConfiguration, setBucketLifecycleConfiguration, setBucketLoggingConfiguration, setBucketMetricsConfiguration, setBucketMetricsConfiguration, setBucketNotificationConfiguration, setBucketNotificationConfiguration, setBucketOwnershipControls, setBucketOwnershipControls, setBucketPolicy, setBucketPolicy, setBucketReplicationConfiguration, setBucketReplicationConfiguration, setBucketTaggingConfiguration, setBucketTaggingConfiguration, setBucketVersioningConfiguration, setBucketWebsiteConfiguration, setBucketWebsiteConfiguration, setEndpoint, setObjectAcl, setObjectAcl, setObjectAcl, setObjectAcl, setObjectAcl, setObjectAcl, setObjectAcl, setObjectLegalHold, setObjectLockConfiguration, setObjectRedirectLocation, setObjectRetention, setObjectTagging, setPublicAccessBlock, setRegion, setRequestPaymentConfiguration, setS3ClientOptions, upload, useStrictHostNameVerification, waiters, writeGetObjectResponse
addRequestHandler, addRequestHandler, beforeClientExecution, beforeMarshalling, calculateCRC32FromCompressedData, checkMutability, configureRegion, createExecutionContext, createExecutionContext, createExecutionContext, endClientExecution, endClientExecution, getClientConfiguration, getClientId, getEndpointPrefix, getMonitoringListeners, getRequestMetricsCollector, getServiceAbbreviation, getServiceName, getServiceNameIntern, getSigner, getSignerByURI, getSignerOverride, getSignerProvider, getSignerRegionOverride, getSigningRegion, getTimeOffset, isCsmEnabled, isEndpointOverridden, isProfilingEnabled, isRequestMetricsEnabled, makeImmutable, removeRequestHandler, removeRequestHandler, requestMetricCollector, setEndpoint, setEndpointPrefix, setServiceNameIntern, setSignerRegionOverride, setTimeOffset, shouldGenerateClientSideMonitoringEvents, withEndpoint, withRegion, withRegion, withTimeOffset
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
changeObjectStorageClass, copyObject, copyObject, createBucket, createBucket, createBucket, createBucket, deleteBucket, deleteBucket, deleteBucketAnalyticsConfiguration, deleteBucketAnalyticsConfiguration, deleteBucketCrossOriginConfiguration, deleteBucketCrossOriginConfiguration, deleteBucketEncryption, deleteBucketEncryption, deleteBucketIntelligentTieringConfiguration, deleteBucketIntelligentTieringConfiguration, deleteBucketInventoryConfiguration, deleteBucketInventoryConfiguration, deleteBucketLifecycleConfiguration, deleteBucketLifecycleConfiguration, deleteBucketMetricsConfiguration, deleteBucketMetricsConfiguration, deleteBucketOwnershipControls, deleteBucketPolicy, deleteBucketPolicy, deleteBucketReplicationConfiguration, deleteBucketReplicationConfiguration, deleteBucketTaggingConfiguration, deleteBucketTaggingConfiguration, deleteBucketWebsiteConfiguration, deleteBucketWebsiteConfiguration, deleteObject, deleteObjects, deleteObjectTagging, deletePublicAccessBlock, deleteVersion, deleteVersion, disableRequesterPays, doesBucketExist, doesBucketExistV2, doesObjectExist, download, download, enableRequesterPays, generatePresignedUrl, generatePresignedUrl, generatePresignedUrl, getBucketAccelerateConfiguration, getBucketAccelerateConfiguration, getBucketAcl, getBucketAcl, getBucketAnalyticsConfiguration, getBucketAnalyticsConfiguration, getBucketCrossOriginConfiguration, getBucketCrossOriginConfiguration, getBucketEncryption, getBucketEncryption, getBucketIntelligentTieringConfiguration, getBucketIntelligentTieringConfiguration, getBucketInventoryConfiguration, getBucketInventoryConfiguration, getBucketLifecycleConfiguration, getBucketLifecycleConfiguration, getBucketLocation, getBucketLocation, getBucketLoggingConfiguration, getBucketLoggingConfiguration, getBucketMetricsConfiguration, getBucketMetricsConfiguration, getBucketNotificationConfiguration, getBucketNotificationConfiguration, getBucketOwnershipControls, getBucketPolicy, getBucketPolicy, getBucketPolicyStatus, getBucketReplicationConfiguration, getBucketReplicationConfiguration, getBucketTaggingConfiguration, getBucketTaggingConfiguration, getBucketVersioningConfiguration, getBucketVersioningConfiguration, getBucketWebsiteConfiguration, getBucketWebsiteConfiguration, getCachedResponseMetadata, getObject, getObjectAcl, getObjectAcl, getObjectAcl, getObjectAsString, getObjectLegalHold, getObjectLockConfiguration, getObjectMetadata, getObjectMetadata, getObjectRetention, getObjectTagging, getPublicAccessBlock, getRegion, getRegionName, getS3AccountOwner, getS3AccountOwner, getUrl, headBucket, isRequesterPaysEnabled, listBucketAnalyticsConfigurations, listBucketIntelligentTieringConfigurations, listBucketInventoryConfigurations, listBucketMetricsConfigurations, listBuckets, listBuckets, listMultipartUploads, listNextBatchOfObjects, listNextBatchOfObjects, listNextBatchOfVersions, listNextBatchOfVersions, listObjects, listObjects, listObjects, listObjectsV2, listObjectsV2, listObjectsV2, listParts, listVersions, listVersions, listVersions, putObject, putObject, putObject, restoreObject, restoreObject, restoreObjectV2, selectObjectContent, setBucketAccelerateConfiguration, setBucketAccelerateConfiguration, setBucketAcl, setBucketAcl, setBucketAcl, setBucketAnalyticsConfiguration, setBucketAnalyticsConfiguration, setBucketCrossOriginConfiguration, setBucketCrossOriginConfiguration, setBucketEncryption, setBucketIntelligentTieringConfiguration, setBucketIntelligentTieringConfiguration, setBucketInventoryConfiguration, setBucketInventoryConfiguration, setBucketLifecycleConfiguration, setBucketLifecycleConfiguration, setBucketLoggingConfiguration, setBucketMetricsConfiguration, setBucketMetricsConfiguration, setBucketNotificationConfiguration, setBucketNotificationConfiguration, setBucketOwnershipControls, setBucketOwnershipControls, setBucketPolicy, setBucketPolicy, setBucketReplicationConfiguration, setBucketReplicationConfiguration, setBucketTaggingConfiguration, setBucketTaggingConfiguration, setBucketVersioningConfiguration, setBucketWebsiteConfiguration, setBucketWebsiteConfiguration, setEndpoint, setObjectAcl, setObjectAcl, setObjectAcl, setObjectAcl, setObjectAcl, setObjectLegalHold, setObjectLockConfiguration, setObjectRedirectLocation, setObjectRetention, setObjectTagging, setPublicAccessBlock, setRegion, setRequestPaymentConfiguration, setS3ClientOptions, upload, waiters, writeGetObjectResponse
public static AmazonS3EncryptionClientV2Builder encryptionBuilder()
public AWSKMS getKmsClient()
public EncryptionMaterialsProvider getEncryptionMaterialsProvider()
public CryptoConfigurationV2 getCryptoConfiguration()
public PutObjectResult putObject(PutObjectRequest req)
Uploads a new object to the specified Amazon S3 bucket. The
PutObjectRequest
contains all the details of the request,
including the bucket to upload to, the key the object will be uploaded
under, and the file or input stream containing the data to upload.
Amazon S3 never stores partial objects; if during this call an exception wasn't thrown, the entire object was stored.
If you are uploading or accessing Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
Depending on whether a file or input stream is being uploaded, this method has slightly different behavior.
When uploading a file:
When uploading directly from an input stream:
If versioning is enabled for the specified bucket, this operation will
never overwrite an existing object with the same key, but will keep the
existing object as an older version until that version is explicitly
deleted (see AmazonS3.deleteVersion(String, String, String)
.
If versioning is not enabled, this operation will overwrite an existing object with the same key; Amazon S3 will store the last write request. Amazon S3 does not provide object locking. If Amazon S3 receives multiple write requests for the same object nearly simultaneously, all of the objects might be stored. However, a single object will be stored with the final write request.
When specifying a location constraint when creating a bucket, all objects added to the bucket are stored in the bucket's region. For example, if specifying a Europe (EU) region constraint for a bucket, all of that bucket's objects are stored in the EU region.
The specified bucket must already exist and the caller must have
Permission.Write
permission to the bucket to upload an object.
Use EncryptedPutObjectRequest
to specify materialsDescription for the EncryptionMaterials to be used for
this request.AmazonS3EncryptionClient would use
EncryptionMaterialsAccessor.getEncryptionMaterials(java.util.Map)
to
retrieve encryption materials corresponding to the materialsDescription specified in the current request.
putObject
in interface AmazonS3
putObject
in interface S3DirectSpi
putObject
in class AmazonS3Client
req
- The request object containing all the parameters to upload a
new object to Amazon S3.PutObjectResult
object containing the information
returned by Amazon S3 for the newly created object.AmazonS3.putObject(String, String, File)
,
AmazonS3.putObject(String, String, InputStream, ObjectMetadata)
,
Amazon Web Services API Documentationpublic S3Object getObject(GetObjectRequest req)
AmazonS3
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.
To distribute large files to many people, you can save bandwidth costs by using BitTorrent. For more information, see Amazon S3 Torrent. For more information about returning the ACL of an object, see GetObjectAcl.
If the object you are retrieving is stored in the S3 Glacier 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 InvalidObjectStateError
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 CMKs stored in Amazon Web Services KMS (SSE-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 BadRequest 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 you request does not exist, the error 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 will return an HTTP status code
404 (\"no such key\") error.
If you don’t have the s3:ListBucket
permission, Amazon S3 will return 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.
You need the s3:GetObjectVersion
permission to access a specific version of an object.
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
Additional Considerations about Request Headers
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
:
getObject
in interface AmazonS3
getObject
in interface S3DirectSpi
getObject
in class AmazonS3Client
req
- The request object containing all the options on how to
download the object.null
if constraints were specified but not met.AmazonS3.getObject(String, String)
,
AmazonS3.getObject(GetObjectRequest, File)
,
Amazon Web Services API Documentationpublic ObjectMetadata getObject(GetObjectRequest req, File dest)
AmazonS3
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.
To distribute large files to many people, you can save bandwidth costs by using BitTorrent. For more information, see Amazon S3 Torrent. For more information about returning the ACL of an object, see GetObjectAcl.
If the object you are retrieving is stored in the S3 Glacier 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 InvalidObjectStateError
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 CMKs stored in Amazon Web Services KMS (SSE-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 BadRequest 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 you request does not exist, the error 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 will return an HTTP status code
404 (\"no such key\") error.
If you don’t have the s3:ListBucket
permission, Amazon S3 will return 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.
You need the s3:GetObjectVersion
permission to access a specific version of an object.
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
Additional Considerations about Request Headers
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
:
getObject
in interface AmazonS3
getObject
in interface S3DirectSpi
getObject
in class AmazonS3Client
req
- The request object containing all the options on how to
download the Amazon S3 object content.dest
- Indicates the file (which might already exist) where
to save the object content being downloading from Amazon S3.null
if constraints were specified but not met.AmazonS3.getObject(String, String)
,
AmazonS3.getObject(GetObjectRequest)
,
Amazon Web Services API Documentationpublic void deleteObject(DeleteObjectRequest req)
AmazonS3
Deletes the specified object in the specified bucket. Once deleted, the object can only be restored if versioning was enabled when the object was deleted.
If attempting to delete an object that does not exist, Amazon S3 will return a success message instead of an error message.
deleteObject
in interface AmazonS3
deleteObject
in class AmazonS3Client
req
- The request object containing all options for deleting an Amazon S3
object.AmazonS3Client.deleteObject(String, String)
,
Amazon Web Services API Documentationpublic CompleteMultipartUploadResult completeMultipartUpload(CompleteMultipartUploadRequest req)
AmazonS3
Completes a multipart upload by assembling previously uploaded parts.
You first initiate the multipart upload and then upload all parts using the AmazonS3.uploadPart(UploadPartRequest)
method. After successfully uploading all relevant parts of an upload, you call this action to complete the upload. Upon
receiving this request, Amazon S3 concatenates all the parts in ascending order by part number to create a new
object. In the Complete Multipart Upload request, you must provide the parts list. You must ensure that the parts
list is complete. This action concatenates the parts that you provide in the list. For each part in the list, you
must provide the part number and the ETag
value, returned after that part was uploaded.
Processing of a Complete Multipart Upload request could take several minutes to complete. After Amazon S3 begins processing the request, it sends an HTTP response header that specifies a 200 OK response. While processing is in progress, Amazon S3 periodically sends white space characters to keep the connection from timing out. Because a request could fail after the initial 200 OK response has been sent, it is important that you check the response body to determine whether the request succeeded.
Note that if CompleteMultipartUpload
fails, applications should be prepared to retry the failed
requests. For more information, see Amazon S3 Error Best
Practices.
You cannot use Content-Type: application/x-www-form-urlencode
with Complete Multipart Upload
requests. It is not allowed by Amazon S3. Also, if you do not provide a Content-Type
header, CompleteMultipartUpload
returns a 200 OK response.
For more information about multipart uploads, see Uploading Objects Using Multipart Upload.
For information about permissions required to use the multipart upload API, see Multipart Upload and Permissions.
CompleteMultipartUpload
has the following special errors:
Error code: EntityTooSmall
Description: Your proposed upload is smaller than the minimum allowed object size. Each part must be at least 5 MB in size, except the last part.
400 Bad Request
Error code: InvalidPart
Description: One or more of the specified parts could not be found. The part might not have been uploaded, or the specified entity tag might not have matched the part's entity tag.
400 Bad Request
Error code: InvalidPartOrder
Description: The list of parts was not in ascending order. The parts list must be specified in order by part number.
400 Bad Request
Error code: NoSuchUpload
Description: The specified multipart upload does not exist. The upload ID might be invalid, or the multipart upload might have been aborted or completed.
404 Not Found
The following operations are related to CompleteMultipartUpload
:
completeMultipartUpload
in interface AmazonS3
completeMultipartUpload
in interface S3DirectSpi
completeMultipartUpload
in class AmazonS3Client
req
- The CompleteMultipartUploadRequest object that specifies all
the parameters of this operation.public InitiateMultipartUploadResult initiateMultipartUpload(InitiateMultipartUploadRequest req)
AmazonS3.uploadPart(UploadPartRequest)
requests. You also include this
upload ID in the final request to either complete, or abort the multipart
upload request.
Note: After you initiate a multipart upload and upload one or more parts, you must either complete or abort the multipart upload in order to stop getting charged for storage of the uploaded parts. Once you complete or abort the multipart upload Amazon S3 will release the stored parts and stop charging you for their storage.
If you are initiating a multipart upload for Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
Use EncryptedInitiateMultipartUploadRequest
to specify materialsDescription for the
EncryptionMaterials to be used for this request. AmazonS3EncryptionClient would use
EncryptionMaterialsAccessor.getEncryptionMaterials(java.util.Map)
to retrieve encryption materials
corresponding to the materialsDescription specified in the current request.
initiateMultipartUpload
in interface AmazonS3
initiateMultipartUpload
in interface S3DirectSpi
initiateMultipartUpload
in class AmazonS3Client
req
- The InitiateMultipartUploadRequest object that specifies all
the parameters of this operation.public UploadPartResult uploadPart(UploadPartRequest uploadPartRequest) throws SdkClientException, AmazonServiceException
Your UploadPart request must include an upload ID, a part number and part size. The upload ID is the ID returned by Amazon S3 in response to your Initiate Multipart Upload request. Part number can be any number between 1 and 10,000, inclusive. A part number uniquely identifies a part and also defines its position within the object being uploaded. If you upload a new part using the same part number that was specified in uploading a previous part, the previously uploaded part is overwritten.
For information about maximum and minimum part sizes and other multipart upload specifications, see Multipart upload limits in the Amazon S3 User Guide.
To ensure data is not corrupted traversing the network, specify the Content-MD5 header in the Upload Part request. Amazon S3 checks the part data against the provided MD5 value. If they do not match, Amazon S3 returns an error.
When you upload a part, the returned UploadPartResult contains an ETag property. You should record this ETag property value and the part number. After uploading all parts, you must send a CompleteMultipartUpload request. At that time Amazon S3 constructs a complete object by concatenating all the parts you uploaded, in ascending order based on the part numbers. The CompleteMultipartUpload request requires you to send all the part numbers and the corresponding ETag values.
Note: After you initiate a multipart upload and upload one or more parts, you must either complete or abort the multipart upload in order to stop getting charged for storage of the uploaded parts. Once you complete or abort the multipart upload Amazon S3 will release the stored parts and stop charging you for their storage.
If you are performing upload part for Amazon Web Services KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure Amazon Web Services Signature Version 4 for added security. For more information on how to do this, see http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html# specify-signature-version
When supplying an InputStream
using UploadPartRequest.withInputStream(InputStream)
or UploadPartRequest.setInputStream(InputStream)
, the stream will only be
closed by the client if UploadPartRequest.isLastPart()
is true
. If this is not the last part, the stream will be left open.
NOTE: Because the encryption process requires context from block N-1 in order to encrypt block N, parts uploaded with the AmazonS3EncryptionClient (as opposed to the normal AmazonS3Client) must be uploaded serially, and in order. Otherwise, the previous encryption context isn't available to use when encrypting the current part.
uploadPart
in interface AmazonS3
uploadPart
in interface S3DirectSpi
uploadPart
in class AmazonS3Client
uploadPartRequest
- The UploadPartRequest object that specifies all the parameters
of this operation.SdkClientException
- If any errors are encountered in the client while making the
request or handling the response.AmazonServiceException
- If any errors occurred in Amazon S3 while processing the
request.public CopyPartResult copyPart(CopyPartRequest copyPartRequest)
AmazonS3Client
For information about maximum and minimum part sizes and other multipart upload specifications, see Multipart upload limits in the Amazon S3 User Guide.
If constraints are specified in the CopyPartRequest
(e.g.
CopyPartRequest.setMatchingETagConstraints(List)
)
and are not satisfied when Amazon S3 receives the
request, this method returns null
.
This method returns a non-null result under all other
circumstances.
copyPart
in interface AmazonS3
copyPart
in interface S3DirectSpi
copyPart
in class AmazonS3Client
copyPartRequest
- The request object containing all the options for copying an
Amazon S3 object.CopyPartResult
object containing the information
returned by Amazon S3 about the newly created object, or null
if
constraints were specified that weren't met when Amazon S3 attempted
to copy the object.AmazonS3.copyObject(CopyObjectRequest)
,
AmazonS3.initiateMultipartUpload(InitiateMultipartUploadRequest)
public void abortMultipartUpload(AbortMultipartUploadRequest req)
AmazonS3
abortMultipartUpload
in interface AmazonS3
abortMultipartUpload
in interface S3DirectSpi
abortMultipartUpload
in class AmazonS3Client
req
- The AbortMultipartUploadRequest object that specifies all the
parameters of this operation.public PutObjectResult putInstructionFile(PutInstructionFileRequest req)
AmazonS3EncryptionV2
User of this method is responsible for explicitly deleting/updating the instruction file so created should the corresponding S3 object is deleted/created.
putInstructionFile
in interface AmazonS3EncryptionV2
public CompleteMultipartUploadResult uploadObject(UploadObjectRequest req) throws IOException, InterruptedException, ExecutionException
AmazonS3Client
uploadObject
in interface AmazonS3EncryptionV2
IOException
- if the encryption to disk failedInterruptedException
- if the current thread was interrupted while waitingExecutionException
- if the concurrent uploads threw an exceptionpublic void shutdown()
If the a default internal KMS client has been constructed, it will also be shut down by calling this method. Otherwise, users who provided the KMS client would be responsible to shut down the KMS client extrinsic to this method.
shutdown
in interface AmazonS3
shutdown
in class AmazonWebServiceClient
Copyright © 2022. All rights reserved.