Help Center/ Object Storage Service/ API Reference/ Object APIs/ Basic Operations/ Obtaining Object Metadata
Updated on 2026-05-26 GMT+08:00
View PDF
Share

Obtaining Object Metadata

Function

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.

Authorization

To call this API, you must be the object owner or have the permissions to obtain object metadata. You are advised to use IAM or bucket policies for authorization. For details about OBS authorization methods, see Differences Between OBS Permissions Control Methods.

  • If you use IAM for authorization, you need to use either role/policy-based authorization or identity policy-based authorization and configure the required permissions:
    • If you use role/policy-based authorization (IAM v3 APIs in the old IAM version), you must have the obs:object:getObject (versioning disabled) and obs:object:getObjectVersion (versioning enabled or suspended) permissions. For details, see Creating a Custom IAM Policy.
    • If you use identity policy-based authorization (IAM v5 APIs in the new IAM version), you must have the obs:object:GetObject (versioning disabled) and obs:object:GetObjectVersion (versioning enabled or suspended) permissions, as shown in the following table. For details, see Creating a Custom IAM Identity Policy.

      Action

      Access Level

      Resource Type (*: Required)

      Condition Key

      Alias

      Dependencies

      obs:object:getObject (versioning disabled)

      obs:object:getObjectVersion (versioning enabled or suspended)

      Read

      object *

      -

      obs:object:getObjectRetention

      -
      • obs:EpochTime
      • obs:SourceIp
      • obs:TlsVersion
      • obs:CustomDomain
  • If you use bucket policies for authorization, you must have the obs:object:GetObject (versioning disabled) and obs:object:GetObjectVersion (versioning enabled or suspended) permissions. For details, see Creating a Custom Bucket Policy.

URI

HEAD /{object_key}

Calling Method

For details, see Calling APIs. Before calling this API, calculate the API signature and add it to the request.

You can debug this API in API Explorer.

Request Syntax

1
2
3
4
 
HEAD /ObjectName HTTP/1.1 
Host: bucketname.obs.region.myhuaweicloud.com 
Date: date
Authorization: authorization

URI Parameters

Table 1 describes the request parameters.

Table 1 URI parameters

Parameter

Type

Mandatory

Description

versionId

String

No

Definition

Version ID of the object.

Constraints

N/A

Range

The value must contain 32 characters.

Default Value

N/A

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

Description

Origin

String

No

Definition

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

Constraints

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

Range

The value that complies with the CORS

Default Value

N/A

Access-Control-Request-Headers

String

No

Definition

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

Constraints

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.

Range

The value that complies with the CORS

Default Value

N/A

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

String

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

Definition

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

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

Constraints

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

Range

AES256

Default Value

N/A

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

String

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

Definition

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

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

Constraints

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.

Range

N/A

Default Value

N/A

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

String

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

Definition

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==

Constraints

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.

Range

Base64-encoded MD5 value of the key ID.

Default Value

N/A

Request Body

This request contains no request body parameters.

Response Syntax

1
2
3
4
5
6
 
HTTP/1.1 status_code
Content-Type: type
Date: date
Content-Length: length
Etag: etag
Last-Modified: time

Response Headers

This response 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 Response headers

Header

Type

Description

x-obs-expiration

String

Definition

Expiration details

Constraints

N/A

Range

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

Default Value

N/A

x-obs-website-redirect-location

String

Definition

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.

Constraints

  • 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

N/A

x-obs-version-id

String

Definition

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

Constraints

The value must contain 32 characters.

Range

N/A

Default Value

N/A

Access-Control-Allow-Origin

String

Definition

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

Constraints

N/A

Range

The value that complies with the CORS

Default Value

N/A

Access-Control-Allow-Headers

String

Definition

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

Constraints

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

Range

The value that complies with the CORS

Default Value

N/A

Access-Control-Max-Age

Integer

Definition

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

Constraints

Each CORS rule can contain at most one MaxAgeSeconds.

Range

An integer greater than or equal to 0, in seconds

Default Value

3000

Access-Control-Allow-Methods

String

Definition

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.

Range

  • GET
  • PUT
  • HEAD
  • POST
  • DELETE

Access-Control-Expose-Headers

String

Definition

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.

Constraints

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

Range

N/A

Default Value

N/A

x-obs-server-side-encryption

String

Definition

The encryption method used by the server.

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

Constraints

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

Range

  • kms: SSE-KMS is used for encryption.
  • AES256: SSE-OBS and the AES256 algorithm are used.

Default Value

N/A

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

String

Definition

ID of a specified key used for SSE-KMS encryption. For details about how to obtain a key ID, see Viewing a Key.

Constraints

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 no default master key, OBS will create one and use it.

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

String

Definition

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

Constraints

N/A

Range

AES256: The AES256 algorithm is used.

Default Value

N/A

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

String

Definition

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==

Constraints

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

Range

Base64-encoded MD5 value of the key ID.

Default Value

N/A

x-obs-storage-class

String

Definition

Storage class of an object.

Constraints

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

Range

  • WARM: the Infrequent Access storage class
  • COLD: the Archive storage class
  • DEEP_ARCHIVE: the Deep Archive storage class

Default Value

N/A

x-obs-restore

String

Definition

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.

Constraints

  • This header is returned only when Archive or Deep Archive objects are being restored or has been restored.

Range

N/A

Default Value

N/A

x-obs-object-type

String

Definition

Object type

Constraints

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

Range

  • Appendable: objects generated by appending

Default Value

N/A

x-obs-next-append-position

Integer

Definition

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

Constraints

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

Range

N/A

Default Value

N/A

x-obs-uploadId

String

Definition

Indicates the ID of a multipart task.

Constraints

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

Range

N/A

Default Value

N/A

x-obs-tagging-count

String

Definition

Number of tags associated with an object.

Example: x-obs-tagging-count:1

Constraints

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

Range

N/A

Default Value

N/A

x-obs-object-lock-mode

String

Definition

WORM mode applied to the object.

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

Constraints

  • 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.

Range

Currently, only COMPLIANCE (compliance mode) is supported.

Default Value

N/A

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

String

Definition

When an object lock expires.

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

Constraints

  • The value must be a UTC time that complies with the ISO 8601 standard. Example: 2015-07-01T04:11:15.297Z
  • 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.

Range

The value must be later than the current time.

Default Value

N/A

x-obs-replication-status

String

Definition

Replication status of the object.

Constraints

Only the latest replication status is recorded. The historical replication status of an object cannot be viewed.

Range

  • FAILED: Status of the source object. It indicates that the replication task fails.
  • COMPLETED: Status of the source object. It indicates that the replication task is successful.
  • REPLICA: Status of the target object. It indicates that the object is a replica.

Default Value

N/A

Response Body

This response contains no elements.

Error Responses

No special errors. You can find all errors in Table 2.

Sample Request

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

Sample Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 
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

Sample Request: Obtaining Object Metadata from a Versioning-enabled Bucket

HEAD /object1?versionId=G001118A49821905FFFFD28739D419DA HTTP/1.1
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iqSPeUBl66PwXDApxjRKk6hlcN4=
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Date: WED, 01 Jul 2015 02:37:22 GMT
Content-Type: application/xml

Sample Response: Obtaining Object Metadata from a Versioning-enabled Bucket

x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCShLiL70qeT0g5qpMquCeztsnr1jJmRs
Accept-Ranges: bytes
x-obs-request-id: 0000018A4986DDCDD24538ACF6B54255
Server: OBS
ETag: \
x-obs-tagging-count: 0
Last-Modified: Thu, 31 Aug 2013 02:52:57 GMT
Content-Length: 0
Date: WED, 01 Jul 2015 02:37:22 GMT
Content-Type: text/plain
x-obs-version-id: G001118A49821905FFFFD28739D419DA

Using SDKs to Call APIs

You are advised to use OBS SDKs to call APIs. SDKs encapsulate APIs to simplify development. You can call SDK API functions to access OBS without manually calculating signatures.

Java

Python

C

Go

BrowserJS

.NET

Android

iOS

PHP

Node.js

Helpful Links

Parent Topic: Basic Operations