Updated on 2026-09-20 GMT+08:00

Configuring Direct Reading for a Bucket

Function

This API is used to configure direct reading for a bucket.

Restrictions

To configure direct reading for a bucket, you must be the bucket owner or have the required permission (obs:bucket:PutDirectColdAccessConfiguration granted using IAM or PutDirectColdAccessConfiguration granted using a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Creating a Custom Bucket Policy.
The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.

Method

obsClient.setBucketDirectColdAccess(SetBucketDirectColdAccessRequest request)

Request Parameters

**Table 1** List of request parameters
Parameter	Type	Mandatory (Yes/No)	Description
request	Table 2	Yes	Explanation: Request parameters for configuring direct reading for a bucket. For details, see Table 2.

**Table 2** SetBucketDirectColdAccessRequest
Parameter	Type	Mandatory (Yes/No)	Description
bucketName	String	Yes	Explanation: Bucket name. Restrictions: A bucket name must be unique across all accounts and regions. A bucket name: Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed. Cannot be formatted as an IP address. Cannot start or end with a hyphen (-) or period (.). Cannot contain two consecutive periods (..), for example, my..bucket. Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket. If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket properties comply with those set in the first creation request. Default value: None
access	BucketDirectColdAccess	Yes	Explanation: Cross-region replication configuration of a bucket. Value range: For details, see Table 3. Default value: None

**Table 3** BucketDirectColdAccess
Parameter	Type	Mandatory (Yes/No)	Description
status	RuleStatusEnum	Yes	Explanation: Direct reading status of Archive objects in a bucket. Value range: For details, see Table 4. Default value: None

**Table 4** RuleStatusEnum
Constant	Default Value	Description
ENABLED	Enabled	Direct reading is enabled for a bucket.
DISABLED	Disabled	Direct reading is disabled for a bucket.

Responses

**Table 5** Common response headers
Parameter	Type	Description
statusCode	int	Explanation: HTTP status code. Value range: A status code is a group of digits that can be 2xx (indicating successes) or 4xx or 5xx (indicating errors). It indicates the status of a response. For more information, see Status Code. Default value: None
responseHeaders	Map<String, Object>	Explanation: HTTP response header list, composed of tuples. In a tuple, the String key indicates the name of the header, and the Object value indicates the value of the header. Default value: None

Sample Code

This example configures direct reading for a bucket.

import android.util.Log;
import com.obs.services.ObsClient;
import com.obs.services.exception.ObsException;
import com.obs.services.model.BucketDirectColdAccess;
import com.obs.services.model.DirectColdAccessEnum;
import com.obs.services.model.HeaderResponse;

// Note: Network operations must be performed in a child thread. Otherwise, NetworkOnMainThreadException will be thrown.
new Thread(() -> {
    // Security warning: Hard-coded AK and SK are risky. You are advised to obtain the AK and SK from the security credential management system.
    String ak = System.getenv("ACCESS_KEY_ID");
    String sk = System.getenv("SECRET_ACCESS_KEY");
    String endPoint = "https://your-endpoint";

    ObsClient obsClient = null;
    try {
        obsClient = new ObsClient(ak, sk, endPoint);

        String bucketName = "examplebucket";

        // Enable direct reading for the bucket.
        BucketDirectColdAccess access = new BucketDirectColdAccess();
        access.setDirectColdAccess(DirectColdAccessEnum.ENABLED);

        HeaderResponse response = obsClient.setBucketDirectColdAccess(bucketName, access);
        Log.i("ObsDemo", "Enabled direct reading for the bucket successfully. statusCode: " + response.getStatusCode());
    } catch (ObsException e) {
        Log.e("ObsDemo", "Failed to enable direct reading for the bucket. HTTP status code: " + e.getResponseCode()
                + ". Error code: " + e.getErrorCode()
                + ". Error message: " + e.getErrorMessage());
    } finally {
        if (obsClient != null) {
            try {
                obsClient.close();
            } catch (Exception e) {
                Log.e("ObsDemo", "Failed to close ObsClient.", e);
            }
        }
    }
}).start();

Parent topic: Direct Reading