How to manage symbolic links in a versioning-enabled bucket - Object Storage Service

This topic describes how to manage symbolic links in a versioning-enabled bucket.

Precautions

In this topic, the public endpoint of the China (Hangzhou) region is used. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint. For details about supported regions and endpoints, see OSS regions and endpoints.
In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials.
In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Configuration examples for common scenarios.
To create a symbolic link, you must have the oss:PutObject permission. To get a symbolic link, you must have the oss:GetObject permission. For more information, see Attach a custom policy to a RAM user.

Create a symbolic link

You can create a symbolic link that points to the current version of a target object.

Note

In a versioning-enabled bucket, you cannot create a symbolic link for a delete marker.

A symbolic link can have multiple versions. Each version can point to a different target object. The version ID is automatically generated by OSS and returned in the x-oss-version-id response header.

The following code shows how to create a symbolic link:

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.*;

public class Demo {
    public static void main(String[] args) throws Exception {
        // The endpoint of the China (Hangzhou) region is used in this example. Specify your actual endpoint.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Get access credentials from environment variables. Before running this sample code, configure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the bucket name, for example, examplebucket.
        String bucketName = "examplebucket";
        // Specify the symbolic link name.
        String symLink = "yourSymLink";
        // Specify the full path of the object. Do not include the bucket name in the full path.
        String destinationObjectName = "exampledir/object";
        // Specify the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou.
        String region = "cn-hangzhou";

        // Create an OSSClient instance.
        // When the OSSClient instance is no longer in use, call the shutdown method to release resources.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();

        try {
            // Create the metadata of the file to upload.
            ObjectMetadata metadata = new ObjectMetadata();
            metadata.setContentType("text/plain");
            // Set the value of the custom metadata property to property-value.
            metadata.addUserMetadata("property", "property-value");

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

            // Set the metadata.
            createSymlinkRequest.setMetadata(metadata);
            // Specify the version ID of the object.
            createSymlinkRequest.setVersionId("CAEQFhiCgID3rZDy3hgiIGQxOTIxOWU0M2NlYzQ2ODdhMTQwOGRlZGQxMzEx****");

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

Get a symbolic link

The GetSymlink operation gets the current version of a symbolic link by default. You can also specify a version ID to get a specific version. If the current version of the symbolic link is a delete marker, OSS returns a 404 Not Found error and includes x-oss-delete-marker = true and the version ID x-oss-version-id in the response header.

Note

To get a symbolic link, you must have read permissions for it.

The following code shows how to get a symbolic link:

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.*;

public class Demo {
    public static void main(String[] args) throws Exception {
        // The endpoint of the China (Hangzhou) region is used in this example. Specify your actual endpoint.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Get access credentials from environment variables. Before running this sample code, configure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the bucket name, for example, examplebucket.
        String bucketName = "examplebucket";
        // Specify the symbolic link name.
        String symLink = "yourSymLink";
        // Specify the version ID of the symbolic link.
        String versionId  = "CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****";
        // Specify the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou.
        String region = "cn-hangzhou";

        // Create an OSSClient instance.
        // When the OSSClient instance is no longer in use, call the shutdown method to release resources.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();

        try {            
            GenericRequest genericRequest = new GenericRequest(bucketName, symLink, versionId);
            OSSSymlink symbolicLink = ossClient.getSymlink(genericRequest);
            // Print the name of the symbolic link.
            System.out.println(symbolicLink.getSymlink());
            // Print the name of the object to which the symbolic link points.
            System.out.println(symbolicLink.getTarget());
            System.out.println(symbolicLink.getRequestId());
            // Print the version ID of the symbolic link.
            System.out.println(symbolicLink.getMetadata().getVersionId());
        } 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();
            }
        }
    }
}

References

For more information about the API operation to create a symbolic link, see PutSymlink.
For more information about the API operation to get a symbolic link, see GetSymlink.