public class GetObjectMetadataRequest extends AmazonWebServiceRequest implements SSECustomerKeyProvider, Serializable, ExpectedBucketOwnerRequest
The HEAD action retrieves metadata from an object without returning the object itself. This action is useful if you're only interested in an object's metadata. To use HEAD, you must have READ access to the object.
A HEAD request has the same options as a GET action on an object. The response is identical
to the GET response except that there is no response body. Because of this, if the HEAD request
generates an error, it returns a generic 404 Not Found or 403 Forbidden code. It is not possible
to retrieve the exact exception beyond these error codes.
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 retrieve the metadata from 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).
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.
The last modified property in this case is the creation date of the object.
Request headers are limited to 8 KB in size. For more information, see Common Request Headers.
Consider the following when using request headers:
Consideration 1 – 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 Amazon S3 returns 200 OK and the data requested.
Consideration 2 – 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 Amazon S3 returns the 304 Not Modified response code.
For more information about conditional requests, see RFC 7232.
Permissions
< p>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 returns an HTTP status code
404 (\"no such key\") error.
If you don’t have the s3:ListBucket permission, Amazon S3 returns an HTTP status code 403
(\"access denied\") error.
The following action is related to HeadObject:
NOOP| Constructor and Description |
|---|
GetObjectMetadataRequest(String bucketName,
String key)
Constructs a new
GetObjectMetadataRequest
used to retrieve a specified
object's metadata. |
GetObjectMetadataRequest(String bucketName,
String key,
String versionId)
Constructs a new
GetObjectMetadataRequest
with basic options. |
| Modifier and Type | Method and Description |
|---|---|
String |
getBucketName()
The name of the bucket containing the object.
|
String |
getExpectedBucketOwner()
Returns he account id of the expected bucket owner.
|
String |
getKey()
Gets the key of the object whose metadata is being retrieved.
|
Integer |
getPartNumber()
Returns the optional part number that indicates a part in multipart object.
|
SSECustomerKey |
getSSECustomerKey()
Returns the optional customer-provided server-side encryption key to use
to encrypt the uploaded object.
|
String |
getVersionId()
Gets the optional version ID of the object version whose metadata is
being retrieved.
|
boolean |
isRequesterPays()
Returns true if the user has enabled Requester Pays option when
downloading the object metadata from Requester Pays Bucket; else false.
|
void |
setBucketName(String bucketName)
Sets the name of the bucket containing the object whose metadata is
being retrieved.
|
void |
setExpectedBucketOwner(String expectedBucketOwner)
Set the account id of the expected bucket owner.
|
void |
setKey(String key)
Sets the key of the object whose metadata is being retrieved.
|
void |
setPartNumber(Integer partNumber)
Sets the optional part number to find the number of parts of an object.
|
void |
setRequesterPays(boolean isRequesterPays)
Used for downloading an Amazon S3 Object metadata from a Requester Pays Bucket.
|
void |
setSSECustomerKey(SSECustomerKey sseKey)
Sets the optional customer-provided server-side encryption key to use
when retrieving the metadata of a server-side encrypted object.
|
void |
setVersionId(String versionId)
Sets the optional version ID of the object version whose metadata is
being retrieved.
|
GetObjectMetadataRequest |
withBucketName(String bucketName)
The name of the bucket containing the object.
|
GetObjectMetadataRequest |
withExpectedBucketOwner(String expectedBucketOwner)
Set the account id of the expected bucket owner.
|
GetObjectMetadataRequest |
withKey(String key)
Sets the key of the object whose metadata is being retrieved.
|
GetObjectMetadataRequest |
withPartNumber(Integer partNumber)
Sets the optional part number to find the number of parts of an object.
|
GetObjectMetadataRequest |
withRequesterPays(boolean isRequesterPays)
Used for conducting this operation from a Requester Pays Bucket.
|
GetObjectMetadataRequest |
withSSECustomerKey(SSECustomerKey sseKey)
Sets the optional customer-provided server-side encryption key to use
when retrieving the metadata of a server-side encrypted object, and
retuns the updated request object so that additional method calls can be
chained together.
|
GetObjectMetadataRequest |
withVersionId(String versionId)
Sets the optional version ID of the object version whose metadata is
being retrieved.
|
addHandlerContext, clone, getCloneRoot, getCloneSource, getCustomQueryParameters, getCustomRequestHeaders, getGeneralProgressListener, getHandlerContext, getReadLimit, getRequestClientOptions, getRequestCredentials, getRequestCredentialsProvider, getRequestMetricCollector, getSdkClientExecutionTimeout, getSdkRequestTimeout, putCustomQueryParameter, putCustomRequestHeader, setGeneralProgressListener, setRequestCredentials, setRequestCredentialsProvider, setRequestMetricCollector, setSdkClientExecutionTimeout, setSdkRequestTimeout, withGeneralProgressListener, withRequestCredentialsProvider, withRequestMetricCollector, withSdkClientExecutionTimeout, withSdkRequestTimeoutpublic GetObjectMetadataRequest(String bucketName, String key)
GetObjectMetadataRequest
used to retrieve a specified
object's metadata.bucketName - The name of the bucket containing the object whose metadata
is being retrieved.key - The key of the object whose metadata is being retrieved.GetObjectMetadataRequest(String bucketName, String key, String versionId)public GetObjectMetadataRequest(String bucketName, String key, String versionId)
GetObjectMetadataRequest
with basic options.bucketName - The name of the bucket containing the object whose metadata
is being retrieved.key - The key of the object whose metadata is being retrieved.versionId - The version ID of the object version whose metadata is being
retrieved.GetObjectMetadataRequest(String bucketName, String key)public String getExpectedBucketOwner()
ExpectedBucketOwnerRequest403 (Access Denied) error.getExpectedBucketOwner in interface ExpectedBucketOwnerRequestpublic GetObjectMetadataRequest withExpectedBucketOwner(String expectedBucketOwner)
ExpectedBucketOwnerRequest403 (Access Denied) error.withExpectedBucketOwner in interface ExpectedBucketOwnerRequestpublic void setExpectedBucketOwner(String expectedBucketOwner)
ExpectedBucketOwnerRequest403 (Access Denied) error.setExpectedBucketOwner in interface ExpectedBucketOwnerRequestpublic String getBucketName()
The name of the bucket 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 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 using 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.
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 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 using 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.
setBucketName(String bucketName),
withBucketName(String)public void setBucketName(String bucketName)
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 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 using 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.
bucketName - The name of the bucket, or access point ARN, containing the object's whose metadata
is being retrieved.
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 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 using 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.
getBucketName(),
withBucketName(String)public GetObjectMetadataRequest withBucketName(String bucketName)
The name of the bucket 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 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 using 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.
bucketName - The name of the bucket 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 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 using 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.
GetObjectMetadataRequest, enabling additional method
calls to be chained together.getBucketName(),
setBucketName(String bucketName)public String getKey()
setKey(String),
withKey(String)public void setKey(String key)
key - The key of the object whose metadata is being retrieved.getKey(),
withKey(String)public GetObjectMetadataRequest withKey(String key)
GetObjectMetadataRequest, enabling additional method
calls to be chained together.key - The key of the object whose metadata is being retrieved.GetObjectMetadataRequest, enabling additional method
calls to be chained together.getKey(),
setKey(String)public String getVersionId()
setVersionId(String),
withVersionId(String)public void setVersionId(String versionId)
versionId - The optional version ID of the object version whose metadata
is being retrieved. If not specified, the latest version will
be used.getVersionId(),
withVersionId(String)public GetObjectMetadataRequest withVersionId(String versionId)
GetObjectMetadataRequest, enabling additional method
calls to be chained together.
If not specified, the latest version will be used.versionId - The optional version ID of the object version whose metadata
is being retrieved.GetObjectMetadataRequest, enabling additional method
calls to be chained together.getVersionId(),
setVersionId(String)public boolean isRequesterPays()
If a bucket is enabled for Requester Pays, then any attempt to read an object from it without Requester Pays enabled will result in a 403 error and the bucket owner will be charged for the request.
Enabling Requester Pays disables the ability to have anonymous access to this bucket
public void setRequesterPays(boolean isRequesterPays)
If a bucket is enabled for Requester Pays, then any attempt to read an object metadata from it without Requester Pays enabled will result in a 403 error and the bucket owner will be charged for the request.
Enabling Requester Pays disables the ability to have anonymous access to this bucket
isRequesterPays - Enable Requester Pays option for the operation.public GetObjectMetadataRequest withRequesterPays(boolean isRequesterPays)
If a bucket is enabled for Requester Pays, then any attempt to upload or download an object from it without Requester Pays enabled will result in a 403 error and the bucket owner will be charged for the request.
Enabling Requester Pays disables the ability to have anonymous access to this bucket.
isRequesterPays - Enable Requester Pays option for the operation.public SSECustomerKey getSSECustomerKey()
SSECustomerKeyProvidergetSSECustomerKey in interface SSECustomerKeyProviderpublic void setSSECustomerKey(SSECustomerKey sseKey)
sseKey - The optional customer-provided server-side encryption key to
use when retrieving the metadata of a server-side encrypted
object.public GetObjectMetadataRequest withSSECustomerKey(SSECustomerKey sseKey)
sseKey - The optional customer-provided server-side encryption key to
use when retrieving the metadata of a server-side encrypted
object.public Integer getPartNumber()
Returns the optional part number that indicates a part in multipart object.
setPartNumber(Integer),
withPartNumber(Integer)public void setPartNumber(Integer partNumber)
Sets the optional part number to find the number of parts of an object.
To find the number of parts of an object, set partNumber to 1 and observe the x-amz-mp-parts-count response. If the object exists and x-amz-mp-parts-count is missing it's implicitly 1. Otherwise number of parts is equal to the value returned by x-amz-mp-parts-count.
The valid range for part number is 1 - 10000 inclusive. For partNumber < 1, an AmazonS3Exception is thrown with response code 400 bad request For partNumber larger than actual part count, an AmazonS3Exception is thrown with response code 416 Request Range Not Satisfiable
partNumber - The part number representing a part in a multipart object.getPartNumber(),
withPartNumber(Integer)public GetObjectMetadataRequest withPartNumber(Integer partNumber)
Sets the optional part number to find the number of parts of an object.
To find the number of parts of an object, set partNumber to 1 and observe the x-amz-mp-parts-count response. If the object exists and x-amz-mp-parts-count is missing it's implicitly 1. Otherwise number of parts is equal to the value returned by x-amz-mp-parts-count.
The valid range for part number is 1 - 10000 inclusive. For partNumber < 1, an AmazonS3Exception is thrown with response code 400 bad request For partNumber larger than actual part count, an AmazonS3Exception is thrown with response code 416 Request Range Not Satisfiable
partNumber - The part number representing a part in a multipart object.GetObjectRequest, enabling additional method
calls to be chained together.getPartNumber(),
setPartNumber(Integer)