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

Obtaining Bucket Metadata

Functions

This API is used to obtain bucket metadata. For more information about object metadata, see Configuring, Editing, and Viewing Object Metadata.

Authorization Information

To call this API, you must be the bucket owner or have the permission to obtain bucket 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 need to grant the obs:bucket:HeadBucket permission. For details, see Creating a Custom IAM Policy.
    • If you use identity policy-based authorization (IAM v5 APIs in the new IAM version), you need to grant the obs:bucket:headBucket permission, 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:bucket:headBucket

      Read

      bucket *

      -

      -

      -
      • obs:EpochTime
      • obs:SourceIp
      • obs:TlsVersion
      • obs:CustomDomain
  • If you use bucket policies for authorization, you need to grant the obs:bucket:HeadBucket permission. For details, see Creating a Custom Bucket Policy.

Request Syntax

The following is an example request. Replace BucketName with your bucket name and RegionID with the ID of the region where your bucket resides. You can obtain the region ID by referring to Supported Regions.

HEAD / HTTP/1.1 
Host: BucketName.obs.RegionID.myhuaweicloud.com 
Date: GMT Date
Authorization: SignatureValue

Description of the OBS request structure

  • An OBS request consists of the request method, request URI, request headers, and request body. The following figure shows an example of a request for creating a bucket. The bucket name is configured in the Host header, and the signature information is configured in the Authorization header. For details about how to calculate the signature, see Using an Authorization Header. For more information, see Constructing a Request.

URI Parameters

The request of this API contains no URI parameters.

Request Headers

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

If you want to get CORS configuration information, you must use the headers in Table 1.

Table 1 Request headers for obtaining the CORS configuration

Header

Type

Mandatory (Yes/No)

Description

Origin

String

Yes

Definition

Origin of the cross-domain request specified by the pre-request. Generally, it is a domain name.

Range

An HTTP-compliant header value

Default Value

None

Access-Control-Request-Headers

String

No

Definition

HTTP headers in a request

Range

An HTTP-compliant header value

Default value:

None

Request Body

This request contains no request body parameters.

Response Syntax

HTTP/1.1 status_code
x-obs-bucket-location: region
Date: GMT Date

Description of the OBS response structure

  • An OBS response consists of a response status code, response headers, and the response body. The following figure shows an example of a response for obtaining the bucket's ACL configuration.

Response Headers

This response uses common headers. For details, see Table 1.

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

Table 2 Additional response headers

Header

Type

Description

x-obs-bucket-location

String

Definition

The region where the bucket resides.

Constraints

None

Range

None

Default Value

None

x-obs-storage-class

String

Definition

Default storage class of the bucket.

Constraints

None

Range

  • STANDARD (Standard storage)
  • WARM (Infrequent Access storage)
  • COLD (Archive storage)
  • DEEP_ARCHIVE (Deep Archive storage)

Default Value

None

x-obs-version

String

Definition

OBS version of the bucket.

Constraints

None

Range

  • 3.0: bucket of the latest version
  • --: bucket of an earlier version

Default Value

None

x-obs-fs-file-interface

String

Definition

Whether it is a parallel file system

Constraints

If this header field is not carried, the bucket is not a parallel file system.

Range

The value can be Enabled (parallel file system).

Default Value

None

x-obs-epid

String

Definition

Enterprise project ID for the current bucket. Users who have enabled the enterprise project function can obtain the ID from the enterprise project service.

Constraints:

The value is a UUID. This parameter is not required if you have not enabled an enterprise project.

Range

See How Do I Obtain an Enterprise Project ID?

Default Value

None

x-obs-az-redundancy

String

Definition

Specifies an AZ redundancy type.

Value 3az indicates that data is stored in multiple AZs in the same region.

If this header field is not carried, data is stored in a single AZ.

Constraints

Multi-AZ redundancy is not available for Archive and Deep Archive storage. If the region where the bucket is located does not support multi-AZ storage, single-AZ storage is used by default.

Range

If multi-AZ storage is configured for the bucket, 3az is returned. If single-AZ storage is configured for the bucket, None is returned.

Default Value

None

Access-Control-Allow-Origin

String

Definition

Indicates that the origin is included in the response if the origin in the request meets the CORS configuration requirements when CORS is configured for buckets.

Constraints

None

Range

The value that complies with the CORS

Default Value

None

Access-Control-Allow-Headers

String

Definition

Indicates that the headers are included in the response if headers in the request meet the CORS configuration requirements when CORS is configured for buckets.

Constraints

None

Range

The value that complies with the CORS

Default Value

None

Access-Control-Max-Age

Integer

Definition

Value of MaxAgeSeconds in the CORS configuration of the server when CORS is configured for buckets.

Constraints

None

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.

Constraints

None

Range

  • GET
  • PUT
  • HEAD
  • POST
  • DELETE

Default Value

None

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 in this parameter.

Constraints

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

Range

None

Default Value

None

Response Body

The response of this API does not contain a response body.

Error Responses

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

Sample Request: Getting CORS Configuration (with No Headers Specified)

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

Sample Response: Getting CORS Configuration (with No Headers Specified)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF260000016439C734E0788404623FA8
Content-Type: application/xml
x-obs-storage-class: STANDARD
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSxwLpq9Hzf3OnaXr+pI/OPLKdrtiQAF
Date: WED, 01 Jul 2015 02:30:25 GMT
x-obs-bucket-location: region
x-obs-version: 3.0
Content-Length: 0

Sample Request: Getting Bucket Metadata and CORS Configuration

1
2
3
4
5
6
7
8
 
HEAD / HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Accept: */*
Date: WED, 01 Jul 2015 02:30:25 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:niCQCuGIZpETKIyx1datxHZyYlk=
Origin:www.example.com
Access-Control-Request-Headers:AllowedHeader_1

Sample Response: Getting Bucket Metadata and CORS Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF260000016439C734E0788404623FA8
Content-Type: application/xml
x-obs-storage-class: STANDARD
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSxwLpq9Hzf3OnaXr+pI/OPLKdrtiQAF
Date: WED, 01 Jul 2015 02:30:25 GMT
x-obs-bucket-location: region
Access-Control-Allow-Origin: www.example.com 
Access-Control-Allow-Methods: POST,GET,HEAD,PUT 
Access-Control-Allow-Headers: AllowedHeader_1 
Access-Control-Max-Age: 100 
Access-Control-Expose-Headers: ExposeHeader_1 
x-obs-version: 3.0
Content-Length: 0

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

.NET

PHP

iOS

Go

BrowserJS

.NET

Android

Harmony: not supported

Node.js

References

Parent Topic: Basic Operations