All Products
Search
Document Center

Object Storage Service:Manage symbolic links

Last Updated:Dec 13, 2023

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

Usage notes

  • In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access Object Storage Service (OSS) by using other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about the regions and endpoints supported by OSS, see 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 Create an OSSClient instance.

  • To create a symbolic link, you must have the oss:PutObject permission. To query 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 an object.

Note

In a versioning-enabled bucket, a symbolic link cannot be created for a delete marker.

A symbolic link can have multiple versions. You can call the PutSymlink operation to point each version of a symbolic link to different objects. In this case, the IDs of the versions are generated by OSS and are included in the response as the value of the x-oss-version-id header.

The following sample code provides an example on how to create a symbolic link:

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.*;

public class Demo {
    public static void main(String[] args) throws Exception {
        // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the name of the symbolic link. 
        String symLink = "yourSymLink";
        // Specify the full path of the object. Do not include the bucket name in the full path. 
        String destinationObjectName = "exampledir/object";

        // Create an OSSClient instance. 
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);

        try {
            // Create metadata for the object that you want to upload. 
            ObjectMetadata metadata = new ObjectMetadata();
            metadata.setContentType("text/plain");
            // Set the property parameter to property-value. 
            metadata.addUserMetadata("property", "property-value");

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

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

Query a symbolic link

By default, the GetSymlink operation queries the current version of a symbolic link. You can specify the version ID in the request to query the specified version of a symbolic link. If the current version of the symbolic link is a delete marker, OSS returns 404 Not Found and includes x-oss-delete-marker = true and x-oss-version-id in the response.

Note

To query a symbolic link, you must have read permissions on the symbolic link.

The following sample code provides an example on how to query a symbolic link:

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.*;

public class Demo {
    public static void main(String[] args) throws Exception {
        // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the source bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the name of the symbolic link. 
        String symLink = "yourSymLink";
        // Specify the version ID of the symbolic link that you want to query. 
        String versionId  = "CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****";

        // Create an OSSClient instance. 
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);

        try {            
            GenericRequest genericRequest = new GenericRequest(bucketName, symLink, versionId);
            OSSSymlink symbolicLink = ossClient.getSymlink(genericRequest);
            // Display 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());
            // Display 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 that you can call to create a symbolic link, see PutSymlink.

  • For more information about the API operation that you can call to query a symbolic link, see GetSymlink.