Querying Object Metadata

Functions

Users with the read permission on objects can perform the HeadObject operation to obtain metadata of objects. The object metadata is included in the response.

SSE-C headers are required if you want to obtain the metadata of an object encrypted using SSE-C. For details, see Table 2.

Versioning

By default, this operation returns the latest metadata of an object. If the object has a delete marker, status code 404 is returned. To obtain the object metadata of a specified version, the versionId parameter can be used to specify the desired version.

Request Syntax

HEAD /ObjectName HTTP/1.1
Host: bucketname.obs.region.example.com
Date: date
Authorization: authorization

Request Parameters

Table 1 describes the request parameters.

Table 1 Request parameters

Parameter

Type

Mandatory (Yes/No)

Description

versionId

String

No

Explanation:

Version ID of the object.

Restrictions:

None

Value range:

The value must contain 32 characters.

Default value:

None

Request Headers

This request uses common headers. For details, see Table 3.

In addition, the request can use additional headers shown in Table 2.

Table 2 Request headers

Header

Type

Mandatory (Yes/No)

Description

Origin

String

No

Explanation:

Origin specified in a preflight request that makes a cross-domain request, usually as a domain name.

Restrictions:

You can enter multiple origins, with one separated from another using a line break. Each origin can contain at most one wildcard character (*).

Value range:

The value that complies with the CORS

Default value:

None

Access-Control-Request-Headers

String

No

Explanation:

Indicates the HTTP headers that are allowed in a request. The request can use multiple HTTP headers.

Restrictions:

You can enter multiple allowed headers, with one separated from another using a line break. Each header can contain at most one wildcard character (*). Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

Value range:

The value that complies with the CORS

Default value:

None

x-obs-server-side-encryption-customer-algorithm

String

No. This header is required when SSE-C is used.

Explanation:

Indicates the decryption algorithm used when SSE-C is used.

Example: x-obs-server-side-encryption-customer-algorithm:AES256

Restrictions:

This header must be used together with x-obs-server-side-encryption-customer-key and x-obs-server-side-encryption-customer-key-MD5.

Value range:

AES256

Default value:

None

x-obs-server-side-encryption-customer-key

String

No. This header is required when SSE-C is used.

Explanation:

Indicates the decryption key used when SSE-C is used.

Example: x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw=

Restrictions:

This header is a Base64-encoded 256-bit key and must be used together with x-obs-server-side-encryption-customer-algorithm and x-obs-server-side-encryption-customer-key-MD5.

Value range:

None

Default value:

None

x-obs-server-side-encryption-customer-key-MD5

String

No. This header is required when SSE-C is used.

Explanation:

Indicates the MD5 value of the decryption key when SSE-C is used. The MD5 value is used to check whether any error occurs during the transmission of the key.

Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

Restrictions:

This header is a Base64-encoded 128-bit MD5 value and must be used together with x-obs-server-side-encryption-customer-algorithm and x-obs-server-side-encryption-customer-key.

Value range:

Base64-encoded MD5 value of the key ID.

Default value:

None

Request Elements

This request involves no elements.

Response Syntax

HTTP/1.1 status_code
Content-Type: type
Date: date
Content-Length: length
Etag: etag
Last-Modified: time

Response Headers

The response to the request uses common headers. For details, see Table 1.

In addition to the common response headers, the headers listed in Table 3 may be used.

Table 3 Additional response headers

Header

Type

Description

x-obs-expiration

String

Explanation:

Expiration details

Restrictions:

None

Value range:

When an object has its lifecycle rule, the object expiration time is subject to its lifecycle rule. This header field is use expiry-date to describe the object expiration date. If the lifecycle rule is configured only for the entire bucket not individual objects, the object expiration time is subject to the bucket lifecycle rule. This header field uses the expiry-date and rule-id to describe the detailed expiration information of objects. If no lifecycle rule is configured, this header field is not contained in the response.

Default value:

None

x-obs-website-redirect-location

String

Explanation:

Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response.

To another object in the same bucket:

x-obs-website-redirect-location:/anotherPage.html

To an external URL:

x-obs-website-redirect-location:http://www.example.com/

OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation.

Restrictions:

  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

  • OBS supports redirection for objects in the root directory of a bucket, not for those in folders.

Default value:

None

x-obs-version-id

String

Explanation:

Version ID of the object. If the object has no version number specified, the response does not contain this header.

Restrictions:

The value must contain 32 characters.

Value range:

None

Default value:

None

Access-Control-Allow-Origin

String

Explanation:

Returned if the request origin meets the CORS configured on the server.

Restrictions:

None

Value range:

The value that complies with the CORS

Default value:

None

Access-Control-Allow-Headers

String

Explanation:

Returned if the request headers meet the CORS configured on the server.

Restrictions:

At most one asterisk (*) is allowed. Spaces, ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

Value range:

The value that complies with the CORS

Default value:

None

Access-Control-Max-Age

Integer

Explanation:

MaxAgeSeconds in the CORS rules of the bucket. It specifies the time your client can cache the response for a cross-origin request.

Restrictions:

Each CORS rule can contain at most one MaxAgeSeconds.

Value range:

An integer greater than or equal to 0, in seconds

Default value:

3000

Access-Control-Allow-Methods

String

Explanation:

Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets.

Value range:

  • GET

  • PUT

  • HEAD

  • POST

  • DELETE

Access-Control-Expose-Headers

String

Explanation:

ExposeHeader in the CORS rules of the bucket. It specifies additional headers allowed in the response by a CORS rule, which are used to provide extra information to clients. By default, a browser can access only headers Content-Length and Content-Type. If the browser needs to access other headers, you need to configure them as additional headers.

Restrictions:

Spaces, asterisks (*), ampersands (&), colons (:), less-than signs (<), and full-width characters are not allowed.

Value range:

None

Default value:

None

x-obs-server-side-encryption

String

Explanation:

The encryption method used by the server.

Example: x-obs-server-side-encryption:kms

Restrictions:

This header is included in a response if SSE-KMS is used.

Value range:

  • kms

  • AES256

Default value:

None

x-obs-server-side-encryption-kms-key-id

String

Explanation:

ID of a specified key used for SSE-KMS encryption.

Restrictions:

This header can only be used when you specify kms for the x-obs-server-side-encryption header.

Default value:

If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.

x-obs-server-side-encryption-customer-algorithm

String

Explanation:

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

Example: x-obs-server-side-encryption-customer-algorithm:AES256

Restrictions:

None

Value range:

AES256

Default value:

None

x-obs-server-side-encryption-customer-key-MD5

String

Explanation:

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

Restrictions:

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==.

Value range:

Base64-encoded MD5 value of the key ID.

Default value:

None

x-obs-storage-class

String

Explanation:

Storage class of an object.

Restrictions:

This header is returned only when the storage class of an object is not Standard.

Value range:

  • WARM

  • COLD

Default value:

None

x-obs-restore

String

Explanation:

Restore status of an object.

For example, ongoing-request="true" indicates that the object is being restored. ongoing-request="false", expiry-date="Wed, 7 Nov 2012 00:00:00 GMT" indicates that the object has been restored, where expiry-date indicates when the restored object expires.

Restrictions:

This header is returned only when a Cold object is being restored or has been restored.

Value range:

None

Default value:

None

x-obs-object-type

String

Explanation:

Object type

Restrictions:

This header is returned only when the object is not a Normal object.

Value range:

Appendable

Default value:

None

x-obs-next-append-position

Integer

Explanation:

Indicates the position that should be provided in the next request.

Restrictions:

This header is returned only when the object is an Appendable object.

Value range:

None

Default value:

None

x-obs-uploadId

String

Explanation:

Indicates the ID of a multipart task.

Restrictions:

This header is returned only when the object is created from a multipart upload.

Value range:

None

Default value:

None

x-obs-tagging-count

String

Explanation:

Number of tags associated with an object.

Example: x-obs-tagging-count:1

Restrictions:

This header is returned only when you have the permission to read tags.

Value range:

None

Default value:

None

x-obs-object-lock-mode

String

Explanation:

WORM mode applied to the object.

Example: x-obs-object-lock-mode:COMPLIANCE

Restrictions:

  • This parameter is returned only when the object has any object-level WORM retention policy configured or has a default bucket-level WORM policy applied.

  • The user must have the GetObjectRetention permission.

Value range:

Currently, only COMPLIANCE (compliance mode) is supported.

Default value:

None

x-obs-object-lock-retain-until-date

String

Explanation:

When an object lock expires.

Example: x-obs-object-lock-retain-until-date:2015-07-01T04:11:15Z

Restrictions:

  • The value must be a UTC time that complies with the ISO 8601 standard. Example: 2015-07-01T04:11:15Z

  • This parameter is returned only when the object has any object-level WORM retention policy configured or has a default bucket-level WORM policy applied.

  • The user must have the GetObjectRetention permission.

Value range:

The value must be later than the current time.

Default value:

None

Response Elements

This response contains no elements.

Error Responses

No special error responses are returned. For details about error responses, see Table 2.

Sample Request

HEAD /object1 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 04:19:25 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:/cARjk81l2iExMfQqn6iT3qEZ74=

Sample Response

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 8DF400000163D3E4BB5905C41B6E65B6
Accept-Ranges: bytes
ETag: "3b46eaf02d3b6b1206078bb86a7b7013"
Last-Modified: WED, 01 Jul 2015 01:19:21 GMT
Content-Type: binary/octet-stream
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSD3nAiTaBoeyt9oHp9vTYtXnLDmwV6D
Date: WED, 01 Jul 2015 04:19:21 GMT
Content-Length: 4572
last updated: 2024-12-11 10:27 UTC - commit: 1084b97f9d241d7af788bdfaa536dba9679533f7