Method: Aws::S3::Client#head_object

Defined in:

lib/aws-sdk-s3/client.rb

#head_object(params = {}) ⇒ Types::HeadObjectOutput

The HEAD operation retrieves metadata from an object without returning the object itself. This operation 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` operation on an object. The response is identical to the `GET` response except that there is no response body.

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)].

<note markdown=“1”> 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 AWS 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.

</note>

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

You need the ‘s3:GetObject` 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 operation is related to ‘HeadObject`:

• GetObject

^

[1]: docs.aws.amazon.com/AmazonS3/latest/dev/ServerSideEncryptionCustomerKeys.html [2]: docs.aws.amazon.com/AmazonS3/latest/API/RESTCommonRequestHeaders.html [3]: tools.ietf.org/html/rfc7232 [4]: docs.aws.amazon.com/AmazonS3/latest/dev/using-with-s3-actions.html

The following waiters are defined for this operation (see #wait_until for detailed usage):

* object_exists
* object_not_exists

Examples:

Example: To retrieve metadata of an object without returning the object itself

# The following example retrieves an object metadata.

resp = client.head_object({
  bucket: "examplebucket", 
  key: "HappyFace.jpg", 
})

resp.to_h outputs the following:
{
  accept_ranges: "bytes", 
  content_length: 3191, 
  content_type: "image/jpeg", 
  etag: "\"6805f2cfc46c0f04559748bb039d69ae\"", 
  last_modified: Time.parse("Thu, 15 Dec 2016 01:19:41 GMT"), 
  metadata: {
  }, 
  version_id: "null", 
}

Request syntax with placeholder values

resp = client.head_object({
  bucket: "BucketName", # required
  if_match: "IfMatch",
  if_modified_since: Time.now,
  if_none_match: "IfNoneMatch",
  if_unmodified_since: Time.now,
  key: "ObjectKey", # required
  range: "Range",
  version_id: "ObjectVersionId",
  sse_customer_algorithm: "SSECustomerAlgorithm",
  sse_customer_key: "SSECustomerKey",
  sse_customer_key_md5: "SSECustomerKeyMD5",
  request_payer: "requester", # accepts requester
  part_number: 1,
})

Response structure

resp.delete_marker #=> Boolean
resp.accept_ranges #=> String
resp.expiration #=> String
resp.restore #=> String
resp.last_modified #=> Time
resp.content_length #=> Integer
resp.etag #=> String
resp.missing_meta #=> Integer
resp.version_id #=> String
resp.cache_control #=> String
resp.content_disposition #=> String
resp.content_encoding #=> String
resp.content_language #=> String
resp.content_type #=> String
resp.expires #=> Time
resp.expires_string #=> String
resp.website_redirect_location #=> String
resp.server_side_encryption #=> String, one of "AES256", "aws:kms"
resp.metadata #=> Hash
resp.metadata["MetadataKey"] #=> String
resp.sse_customer_algorithm #=> String
resp.sse_customer_key_md5 #=> String
resp.ssekms_key_id #=> String
resp.storage_class #=> String, one of "STANDARD", "REDUCED_REDUNDANCY", "STANDARD_IA", "ONEZONE_IA", "INTELLIGENT_TIERING", "GLACIER", "DEEP_ARCHIVE"
resp.request_charged #=> String, one of "requester"
resp.replication_status #=> String, one of "COMPLETE", "PENDING", "FAILED", "REPLICA"
resp.parts_count #=> Integer
resp.object_lock_mode #=> String, one of "GOVERNANCE", "COMPLIANCE"
resp.object_lock_retain_until_date #=> Time
resp.object_lock_legal_hold_status #=> String, one of "ON", "OFF"

Parameters:

• params (Hash) (defaults to: {}) —

  ({})

Options Hash (params):

• :bucket (required, String) —

  The name of the bucket containing the object.

• :if_match (String) —

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

• :if_modified_since (Time, DateTime, Date, Integer, String) —

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

• :if_none_match (String) —

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

• :if_unmodified_since (Time, DateTime, Date, Integer, String) —

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

• :key (required, String) —

  The object key.

• :range (String) —

  Downloads the specified range bytes of an object. For more information about the HTTP Range header, see [www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35]().

• :version_id (String) —

  VersionId used to reference a specific version of the object.

• :sse_customer_algorithm (String) —

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

• :sse_customer_key (String) —

  Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon S3 does not store the encryption key. The key must be appropriate for use with the algorithm specified in the ‘x-amz-server-side​-encryption​-customer-algorithm` header.

• :sse_customer_key_md5 (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.

• :request_payer (String) —

  Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. For information about downloading objects from requester pays buckets, see [Downloading Objects in Requestor Pays Buckets] in the *Amazon S3 Developer Guide*.

  [1]: docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html

• :part_number (Integer) —

  Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a ‘ranged’ HEAD request for the part specified. Useful querying about the size of the part and the number of parts in this object.

Returns:

• (Types::HeadObjectOutput) —

  Returns a response object which responds to the following methods:

  • #delete_marker => Boolean

  • #accept_ranges => String

  • #expiration => String

  • #restore => String

  • #last_modified => Time

  • #content_length => Integer

  • #etag => String

  • #missing_meta => Integer

  • #version_id => String

  • #cache_control => String

  • #content_disposition => String

  • #content_encoding => String

  • #content_language => String

  • #content_type => String

  • #expires => Time

  • #expires_string => String

  • #website_redirect_location => String

  • #server_side_encryption => String

  • #metadata => Hash&lt;String,String&gt;

  • #sse_customer_algorithm => String

  • #sse_customer_key_md5 => String

  • #ssekms_key_id => String

  • #storage_class => String

  • #request_charged => String

  • #replication_status => String

  • #parts_count => Integer

  • #object_lock_mode => String

  • #object_lock_retain_until_date => Time

  • #object_lock_legal_hold_status => String

See Also:

• AWS API Documentation

# File 'lib/aws-sdk-s3/client.rb', line 5600

def head_object(params = {}, options = {})
  req = build_request(:head_object, params)
  req.send_request(options)
end