All Products
Search
Document Center

Object Storage Service:CloudBox symbolic links

Last Updated:Aug 08, 2025

The symbolic link (symlink) feature lets you quickly access frequently used objects in an OSS on CloudBox bucket. After you create a symbolic link by calling the PutSymlink operation, you can use the symbolic link to quickly access the target object file.

Usage notes

  • When you call the PutSymlink operation to create a symbolic link, Object Storage Service (OSS) does not check whether the destination object exists, whether the storage class of the destination object is valid, or whether you can access the destination object.

  • The access control list (ACL) of a symbolic link and the ACL of the destination object to which the symbolic link points are checked when API operations such as GetObject are called to access the destination object.

  • If a PutSymlink request contains a parameter whose name is prefixed with x-oss-meta-, the parameter is considered the user metadata of the symbolic link. Example: x-oss-meta-location. An object can have multiple similar parameters. However, the total size of all user metadata of the object cannot exceed 8 KB.

  • By default, if the object that you want to create already exists, and you have the permissions to access the existing object, the new object overwrites the existing object, and OSS returns 200 OK.

Procedure

Use an Alibaba Cloud SDK

You can create symbolic links only using the OSS SDK for Java. The SDK version must be 3.15.0 or later.

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.*;
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 for the OSS on CloudBox bucket.
        String endpoint = "https://cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com";
        // Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the OSS on CloudBox bucket. For example, examplebucket.
        String bucketName = "examplebucket";
        // Specify the region where the OSS on CloudBox bucket is located.
        String region = "cn-hangzhou";
        // Specify the CloudBox ID.
        String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";
        // Specify the name for the symbolic link.
        String symLink = "yourSymLink";
        // Specify the name of the object file that the symbolic link points to.
        String destinationObjectName = "yourDestinationObjectName";

        // Create an OSSClient instance.
        // When the OSSClient instance is no longer needed, call the shutdown method to release its resources.
        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 {
            // Set metadata for the symbolic link.
            // ObjectMetadata metadata = new ObjectMetadata();
            // metadata.setContentType("text/plain");
            // Set the value of the custom metadata property to property-value.
            // metadata.addUserMetadata("property", "property-value");

            // Specify whether to overwrite an object with the same name when you create the symbolic link.
            // metadata.setHeader("x-oss-forbid-overwrite", "true");
            // Specify the access permissions for the object.
            // metadata.setHeader(OSSHeaders.OSS_OBJECT_ACL, CannedAccessControlList.Default);
            // Specify the storage class for the object.
            // metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard);

            // Create a CreateSymlinkRequest object.
            CreateSymlinkRequest createSymlinkRequest = new CreateSymlinkRequest(bucketName, symLink, destinationObjectName);

            // Set the metadata.
            // createSymlinkRequest.setMetadata(metadata);

            // Create the symbolic link.
            ossClient.createSymlink(createSymlinkRequest);

        } 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();
            }
        }
    }
}            

Use ossutil

For more information about how to create a symbolic link using ossutil, see put-symlink.

Use a REST API

If your program requires a high level of customization, you can make REST API requests directly. This requires you to manually write code to calculate the signature. For more information, see PutSymlink.