Create buckets upload and download objects on OSS on CloudBox - Object Storage Service

OSS on CloudBox lets you store, monitor, and process data locally on your CloudBox hardware—suitable for low-latency workloads and unified storage management across multiple branches.

This guide covers three essential operations: creating an OSS on CloudBox bucket, uploading an object, and downloading an object.

Prerequisites

Before you begin, ensure that you have:

A cloud box purchased and deployed. See Purchase a cloud box.
A Virtual Private Cloud (VPC) and a vSwitch created in OSS on CloudBox. See Create a VPC and a vSwitch.
A VPC internal network configured with a single tunnel for secure connectivity. To request this, contact technical support.

OSS on CloudBox is available only in the following regions: China (Hangzhou), China (Shanghai), China (Shenzhen), China (Heyuan), China (Beijing), and China (Chengdu).

How it works

OSS on CloudBox extends standard OSS to run inside your CloudBox hardware. The following differences from standard OSS apply to all operations in this guide:

Difference	Details
Dedicated data endpoint	Each CloudBox bucket has its own endpoint in the format `https://<cloud-box-id>.<region>.oss-cloudbox.aliyuncs.com`. Use this endpoint—not a standard OSS endpoint—when initializing the SDK client.
CloudBox ID required	All SDK operations require a `cloudBoxId` parameter that identifies your specific CloudBox device.
Java SDK only (v3.15.0+)	Only OSS SDK for Java version 3.15.0 or later supports OSS on CloudBox. Other language SDKs are not supported.
Signature Version 4	The SDK client must use `SignVersion.V4` for authentication.
Console limitations	The OSS console supports bucket creation only. To upload or download objects, use OSS SDK for Java or ossutil.

Step 1: Create an OSS on CloudBox bucket

Using the OSS console

Log on to the OSS console.
In the left-side navigation pane, choose Data Service > OSS on CloudBox Buckets.
Click Create Bucket in the upper-left corner.
In the Create Bucket panel, enter a bucket name, keep the default settings for other parameters, and click OK.

Bucket naming rules:

3 to 63 characters
Lowercase letters, digits, and hyphens (-) only
Must start and end with a lowercase letter or digit
Must be unique within the same cloud box

The console supports bucket creation only. To upload or download objects, use OSS SDK for Java or ossutil.

Using OSS SDK for Java

The example below creates a bucket named examplebucket in the cn-hangzhou region. Set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables before running the code.

Replace the placeholder values before running:

Placeholder	Description	Example
`<your-cloud-box-id>`	Your CloudBox device ID	`cb-f8z7yvzgwfkl9q0h****`
`<your-region>`	The region where your cloud box is deployed	`cn-hangzhou`
`<your-bucket-name>`	The name for your new bucket	`examplebucket`

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.CreateBucketRequest;
import com.aliyun.oss.common.auth.DefaultCredentialProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Specify the data endpoint of the OSS on CloudBox bucket.
        String endpoint = "https://cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com";
        // Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the bucket name.
        String bucketName = "examplebucket";
        // Specify the region where the cloud box is deployed.
        String region = "cn-hangzhou";
        // Specify the ID of the cloud box.
        String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";

        // Create an OSSClient instance with Signature Version 4 and the CloudBox ID.
        ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
        conf.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(new DefaultCredentialProvider(credentialsProvider.getCredentials()))
                .clientConfiguration(conf)
                .region(region)
                .cloudBoxId(cloudBoxId)
                .build();

        try {
            // Create the bucket. The default ACL is private.
            // To set the ACL to public-read, uncomment the following two lines:
            // CreateBucketRequest createBucketRequest = new CreateBucketRequest(bucketName);
            // createBucketRequest.setCannedACL(CannedAccessControlList.PublicRead);
            CreateBucketRequest createBucketRequest = new CreateBucketRequest(bucketName);
            ossClient.createBucket(createBucketRequest);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Using ossutil

Use the put-bucket command. See put-bucket.

Using the OSS API

Call the PutBucket RESTful API directly. Include signature calculation in your code. See PutBucket.

Step 2: Upload an object

The OSS console does not support object uploads to OSS on CloudBox buckets. Use OSS SDK for Java or ossutil instead.

Using OSS SDK for Java

The example below uploads a local file to an OSS on CloudBox bucket. Set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables before running the code.

Replace the placeholder values before running:

Placeholder	Description	Example
`<your-cloud-box-id>`	Your CloudBox device ID	`cb-f8z7yvzgwfkl9q0h****`
`<your-region>`	The region where your cloud box is deployed	`cn-hangzhou`
`<your-bucket-name>`	The name of the target bucket	`examplebucket`
`<object-name>`	The full path of the object in the bucket (excluding bucket name)	`exampledir/exampleobject.txt`
`<local-file-path>`	The full path of the local file to upload	`D:\localpath\examplefile.txt`

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.PutObjectRequest;
import java.io.File;
import com.aliyun.oss.common.auth.DefaultCredentialProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Specify the data endpoint of the OSS on CloudBox bucket.
        String endpoint = "https://cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com";
        // Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the bucket name.
        String bucketName = "examplebucket";
        // Specify the region where the cloud box is deployed.
        String region = "cn-hangzhou";
        // Specify the ID of the cloud box.
        String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";
        // Specify the full path of the object in the bucket. Do not include the bucket name.
        String objectName = "exampledir/exampleobject.txt";
        // Specify the full path of the local file to upload.
        // If omitted, the file is uploaded from the project directory.
        String filePath = "D:\\localpath\\examplefile.txt";

        // Create an OSSClient instance with Signature Version 4 and the CloudBox ID.
        ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
        conf.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(new DefaultCredentialProvider(credentialsProvider.getCredentials()))
                .clientConfiguration(conf)
                .region(region)
                .cloudBoxId(cloudBoxId)
                .build();

        try {
            // Upload the local file to the specified object path in the bucket.
            PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, objectName, new File(filePath));
            // To set the storage class and ACL at upload time, uncomment and configure:
            // ObjectMetadata metadata = new ObjectMetadata();
            // metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard.toString());
            // metadata.setObjectAcl(CannedAccessControlList.Private);
            // putObjectRequest.setMetadata(metadata);
            ossClient.putObject(putObjectRequest);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Using ossutil

Use the cp command with simple upload. See Upload objects.

Using the OSS API

Call the PutObject RESTful API directly. Include signature calculation in your code. See PutObject.

Step 3: Download an object

The OSS console does not support object downloads from OSS on CloudBox buckets. Use OSS SDK for Java or ossutil instead.

Using OSS SDK for Java

The example below downloads an object to a local file path. Set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables before running the code.

Replace the placeholder values before running:

Placeholder	Description	Example
`<your-cloud-box-id>`	Your CloudBox device ID	`cb-f8z7yvzgwfkl9q0h****`
`<your-region>`	The region where your cloud box is deployed	`cn-hangzhou`
`<your-bucket-name>`	The name of the bucket	`examplebucket`
`<object-name>`	The full path of the object in the bucket (excluding bucket name)	`exampledir/exampleobject.txt`
`<local-file-path>`	The full local path where the downloaded object will be saved	`D:\localpath\examplefile.txt`

If a file with the same name already exists at the local path, it will be overwritten. If no local path is specified, the object is saved to the project directory.

package com.aliyun.oss.demo;

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.GetObjectRequest;
import java.io.File;
import com.aliyun.oss.common.auth.DefaultCredentialProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Specify the data endpoint of the OSS on CloudBox bucket.
        String endpoint = "https://cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com";
        // Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the bucket name.
        String bucketName = "examplebucket";
        // Specify the region where the cloud box is deployed.
        String region = "cn-hangzhou";
        // Specify the ID of the cloud box.
        String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";
        // Specify the full path of the object in the bucket. Do not include the bucket name.
        String objectName = "exampledir/exampleobject.txt";
        // Specify the full local path where the downloaded object will be saved.
        String pathName = "D:\\localpath\\examplefile.txt";

        // Create an OSSClient instance with Signature Version 4 and the CloudBox ID.
        ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
        conf.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(new DefaultCredentialProvider(credentialsProvider.getCredentials()))
                .clientConfiguration(conf)
                .region(region)
                .cloudBoxId(cloudBoxId)
                .build();

        try {
            // Download the object to the specified local file path.
            ossClient.getObject(new GetObjectRequest(bucketName, objectName), new File(pathName));
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Using ossutil

Use the cp command. See Download objects.

Using the OSS API

Call the GetObject RESTful API directly. Include signature calculation in your code. See GetObject.

What's next

Upload objects — learn about additional upload methods including multipart upload
Download objects — learn about additional download options