HeadObject
Description
The HeadObject 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.
Permissions
You must have the s3:GetObject permission on the object, or be the bucket owner.
Request Headers
| Name | Description | Required | Type |
|---|---|---|---|
| If-Match | Return the object only if its entity tag (ETag) is the same as the one specified; otherwise, return a 412 (precondition failed) error. For more information about conditional requests, see RFC 7232. | No | text |
| If-None-Match | Return the object only if its entity tag (ETag) is different from the one specified; otherwise, return a 304 (not modified) error. For more information about conditional requests, see RFC 7232. | No | text |
| If-Modified-Since | Return the object only if it has been modified since the specified time; otherwise, return a 304 (not modified) error. For more information about conditional requests, see RFC 7232. | No | text |
| If-Unmodified-Since | Return the object only if it has not been modified since the specified time; otherwise, return a 412 (precondition failed) error. For more information about conditional requests, see RFC 7232. | No | text |
| Range | HeadObject returns only the metadata for an object. If the Range is satisfiable, only the ContentLength is affected in the response. If the Range is not satisfiable, QStorage returns a 416 - Requested Range Not Satisfiable error. | No | text |
| partNumber | 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. | No | text |
| versionId | Version ID used to reference a specific version of the object. | No | text |
| x-amz-checksum-mode | To retrieve the checksum, this parameter must be enabled. | No | text |
| x-amz-expected-bucket-owner | The account ID of the expected bucket owner. If the account ID that you provide does not match the actual owner of the bucket, the request fails with the HTTP status code 403 Forbidden (access denied). | No | text |
| x-amz-request-payer | Confirms that the requester knows that they will be charged for the request. | No | text |
| x-amz-server-side-encryption-customer-algorithm | Specifies the algorithm to use when encrypting the object (for example, AES256). | No | text |
| x-amz-server-side-encryption-customer-key | Specifies the customer-provided encryption key for QStorage to use in encrypting data. This value is used to store the object and then it is discarded; QStorage does not store the encryption key. | No | text |
| x-amz-server-side-encryption-customer-key-MD5 | Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. QStorage uses this header for a message integrity check to ensure that the encryption key was transmitted without error. | No | text |
| response-cache-control | Sets the Cache-Control header of the response. | No | text |
| response-content-disposition | Sets the Content-Disposition header of the response. | No | text |
| response-content-encoding | Sets the Content-Encoding header of the response. | No | text |
| response-content-language | Sets the Content-Language header of the response. | No | text |
| response-content-type | Sets the Content-Type header of the response. | No | text |
| response-expires | Sets the Expires header of the response. | No | text |
Request URI Parameters
None
Request Body
This operation does not have a request body.
Request Syntax
HEAD /ObjectKey?partNumber=PartNumber&response-cache-control=ResponseCacheControl&response-content-disposition=ResponseContentDisposition&response-content-encoding=ResponseContentEncoding&response-content-language=ResponseContentLanguage&response-content-type=ResponseContentType&response-expires=ResponseExpires&versionId=VersionId HTTP/1.1
Host: BucketName.qstorage.quilibrium.com
If-Match: "7778aef83f66abc1fa1e8477f296d394"
If-None-Match: "7778aef83f66abc1fa1e8477f296d394"
If-Modified-Since: Wed, 01 Mar 2024 12:00:00 GMT
If-Unmodified-Since: Wed, 01 Mar 2024 12:00:00 GMT
x-amz-expected-bucket-owner: OwnerAccountId
Values in italics indicate user input and should be replaced with actual values.
Response Headers
| Name | Description | Required | Type |
|---|---|---|---|
| x-amz-id-2 | An identifier for the request | No | String |
| x-amz-request-id | A unique identifier for the request | No | String |
| accept-ranges | Indicates that a range of bytes was specified | No | String |
| Cache-Control | Specifies caching behavior along the request/reply chain | No | String |
| Content-Disposition | Specifies presentational information for the object | No | String |
| Content-Encoding | Indicates what content encodings have been applied to the object and thus what decoding mechanisms must be applied | No | String |
| Content-Language | The language the content is in | No | String |
| Content-Length | Size of the body in bytes | No | String |
| Content-Range | The portion of the object returned in the response for a GET request | No | String |
| Content-Type | A standard MIME type describing the format of the object data | No | String |
| ETag | An entity tag that represents a specific version of the object | No | String |
| Expires | The date and time at which the object is no longer cacheable | No | String |
| Last-Modified | Date and time when the object was last modified | No | String |
| x-amz-checksum-crc32 | The Base64 encoded, 32-bit CRC32 checksum of the object | No | String |
| x-amz-checksum-crc32c | The Base64 encoded, 32-bit CRC32C checksum of the object | No | String |
| x-amz-checksum-crc64nvme | The Base64 encoded, 64-bit CRC64NVME checksum of the object | No | String |
| x-amz-checksum-sha1 | The Base64 encoded, 160-bit SHA1 digest of the object | No | String |
| x-amz-checksum-sha256 | The Base64 encoded, 256-bit SHA256 digest of the object | No | String |
| x-amz-checksum-type | The checksum type, which determines how part-level checksums are combined to create an object-level checksum for multipart objects | No | String |
| x-amz-delete-marker | Specifies whether the object retrieved was (true) or was not (false) a Delete Marker | No | String |
| x-amz-expiration | If the object expiration is configured, the response includes this header with expiry-date and rule-id key-value pairs | No | String |
| x-amz-missing-meta | The number of metadata entries not returned in x-amz-meta headers | No | String |
| x-amz-mp-parts-count | The count of parts this object has for multipart uploads | No | String |
| x-amz-request-charged | If present, indicates that the requester was successfully charged for the request Valid values: requester | No | String |
| x-amz-restore | If the object is an archived object, this header provides restoration status | No | String |
| x-amz-server-side-encryption | The server-side encryption algorithm used when storing this object in QStorage Valid values: AES256 | verenc | No | String |
| x-amz-server-side-encryption-aws-kms-key-id | If present, indicates the ID of the KMS key used for object encryption | No | String |
| x-amz-server-side-encryption-bucket-key-enabled | Indicates whether the object uses an QStorage Bucket Key for server-side encryption with QKMS | No | String |
| x-amz-server-side-encryption-customer-algorithm | If server-side encryption with a customer-provided key was requested, confirms the encryption algorithm used | No | String |
| x-amz-server-side-encryption-customer-key-MD5 | If server-side encryption with a customer-provided key was requested, provides verification of the encryption key | No | String |
| x-amz-version-id | Version ID of the object | No | String |
| x-amz-website-redirect-location | If the bucket is configured as a website, redirects requests for this object to another object or URL | No | String |
| x-amz-object-lock-legal-hold | Specifies whether a legal hold is in effect for this object (ON | OFF). Only returned if the requester has the s3:GetObjectLegalHold permission | No | String |
| x-amz-object-lock-mode | The Object Lock mode (GOVERNANCE | COMPLIANCE) in effect for this object. Only returned if the requester has the s3:GetObjectRetention permission Valid values: GOVERNANCE | COMPLIANCE | No | String |
| x-amz-object-lock-retain-until-date | The date and time when the Object Lock retention period expires. Constraints: Only returned if the requester has the s3:GetObjectRetention permission | No | String |
Response Body
This operation does not return a response body.
Response Errors
| Error Code | Description |
|---|---|
| NoSuchBucket | The specified bucket does not exist |
| NoSuchKey | The specified key does not exist |
| PreconditionFailed | At least one of the preconditions you specified did not hold |
| 403 | Forbidden. Authentication failed or you do not have permission to access the object |
| 304 | Not Modified. The condition specified in If-Modified-Since or If-None-Match headers was not met |
Full Examples
Example 1: Get object metadata
HEAD /hello.txt HTTP/1.1
Host: my-bucket.qstorage.quilibrium.com
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
x-amz-id-2: Example7qoYGN7uMuFuYS6m7a4l
x-amz-request-id: TX234S0F24A06C7
Date: Wed, 01 Mar 2024 12:00:00 GMT
Last-Modified: Wed, 01 Mar 2024 11:00:00 GMT
ETag: "7778aef83f66abc1fa1e8477f296d394"
Content-Length: 11
Content-Type: text/plain
Values in italics indicate variable response values.
Example 2: Get object metadata with conditional request
HEAD /hello.txt HTTP/1.1
Host: my-bucket.qstorage.quilibrium.com
If-Modified-Since: Wed, 01 Mar 2024 10:00:00 GMT
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
x-amz-id-2: Example7qoYGN7uMuFuYS6m7a4l
x-amz-request-id: TX234S0F24A06C7
Date: Wed, 01 Mar 2024 12:00:00 GMT
Last-Modified: Wed, 01 Mar 2024 11:00:00 GMT
ETag: "7778aef83f66abc1fa1e8477f296d394"
Content-Length: 11
Content-Type: text/plain
Values in italics indicate variable response values.
Try It Out
Test HeadObject
Retrieve metadata from an object without returning the object itself.
Coming Soon
This feature is currently under development and will be available soon.