All Products
Search
Document Center

Object Storage Service:Create symbolic links

Last Updated:Feb 29, 2024

Symbolic links in Object Storage Service (OSS) work like file shortcuts on Windows and allow you to quickly access associated objects.

Usage notes

  • A symbolic link that points to a Standard object or an Infrequent Access (IA) object provides immediate access to the object.

  • If you want to access an Archive, Cold Archive, or Deep Cold Archive object by using a symbolic link, you must first restore the object. For more information, see Restore objects.

Procedure

Use the OSS console

  1. Log on to the OSS console.

  2. In the left-side navigation pane, click Buckets. On the Buckets page, find and click the desired bucket.

  3. In the left-side navigation tree, choose Object Management > Objects.

  4. Find the object for which you want to create a symbolic link and choose more > Configure Symbolic Link in the Actions column.

  5. In the Configure Symbolic Link panel, configure Symbolic Link File or Folder and click OK.

    The value that you specify for the Symbolic Link File or Folder parameter must comply with the naming conventions. Assume that the object for which you want to create a symbolic link is in the /test/ directory:

    • If Absolute Path is selected and the symbolic link is named t1-symlink, the path to the symbolic link is /t1-symlink.

    • If Relative Path is selected and the symbolic link is named t2-symlink, the path to the symbolic link is /test/t2-symlink.

    Important

    If the name of the symbolic link object does not include the extension, such as myphoto for the myphoto.jpg object, you can preview the symbolic link object when you access the object in the OSS console or by using its URL. When you use an OSS tool or the OSS console to download the symbolic link object, the format of the downloaded object is unknown, and the object cannot be directly opened. To open the object, you must add the correct object name extension to the symbolic link object.

Use ossbrowser

You can use ossbrowser to perform the same object-level operations that you perform in the OSS console. You can follow the on-screen instructions in ossbrowser to create symbolic links. For more information about how to use ossbrowser, see Use ossbrowser.

Use OSS SDKs

The following sample code provides examples on how to create a symbolic link by using OSS SDKs for common programming languages. For more information about how to create a symbolic link by using OSS SDKs for other programming languages, see Overview.

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 that you want to create. 
        String symLink = "yourSymLink";
        // Specify the name of the object to which you want the symbolic link to point. 
        String destinationObjectName = "yourDestinationObjectName";

        // 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 for the user metadata to property-value. 
            metadata.addUserMetadata("property", "property-value");

            // Specify whether to overwrite the object that has the same name as the symbolic link. 
            // metadata.setHeader("x-oss-forbid-overwrite", "true");
            // Specify the access control list (ACL) of the object. 
            // metadata.setHeader(OSSHeaders.OSS_OBJECT_ACL, CannedAccessControlList.Default);
            // Specify the storage class of the object. 
            // metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard);

            // Create a CreateSymlinkRequest to create the symbolic link. 
            CreateSymlinkRequest createSymlinkRequest = new CreateSymlinkRequest(bucketName, symLink, destinationObjectName);

            // Configure 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();
            }
        }
    }
}            
<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\OssClient;
use OSS\Core\OssException;

// 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. 
$accessKeyId = getenv("OSS_ACCESS_KEY_ID");
$accessKeySecret = getenv("OSS_ACCESS_KEY_SECRET");
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Specify the name of the bucket. Example: examplebucket. 
$bucket= "examplebucket";
// Specify the name of the object to which the symbolic link points. Example: exampleobject.txt. 
$object = "exampleobject.txt";
// Specify the name of the symbolic link. Example: examplesymlink.txt. 
$symlink = "examplesymlink.txt";

$options[OssClient::OSS_HEADERS] = array(
    // Specify whether to overwrite the object that has the same name as the symbolic link. In this example, this parameter is set to true, which indicates that the object with the same name cannot be overwritten. 
    'x-oss-forbid-overwrite'=>"true",
    // Specify the access control list (ACL) of the object. In this example, this parameter is set to private, which indicates that only the owner of the object and authorized users have read and write permissions on the object. 
    'x-oss-object-acl' =>"private",
    // Specify the storage class of the object. In this example, the storage class is set to Standard. 
    'x-oss-storage-class' =>"Standard"
);
try {
    $ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint);
    $ossClient->putSymlink($bucket, $symlink, $object,$options);
} catch (OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}
const OSS = require('ali-oss')

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: 'yourRegion',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the name of the bucket. 
  bucket: 'examplebucket',
});

const headers = {
   // Specify the storage class of the object. 
   'x-oss-storage-class':'Standard', 
   // Specify the access control list (ACL) of the object. 
   'x-oss-object-acl':'private',
   // Specify whether to overwrite the object that has the same name as the symbolic link. In this example, this parameter is set to true, which indicates that the object with the same name cannot be overwritten. 
   'x-oss-forbid-overwrite': 'true '
};

async function put () {
  try {
    // Specify symlinkobject.txt as the name of the symbolic link and exampleobject.txt as the name of the object to which you want the symbolic link to point.  
    const result = await client.putSymlink('symlinkobject.txt', 'exampleobject.txt'
    // ,{ headers }
    );
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

put();
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 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. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. For more information about the endpoints of other regions, see Regions and endpoints. 
# Specify the name of the bucket. Example: examplebucket. For more information about the naming conventions for buckets, see Bucket naming conventions. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the name of the object to which you want the symbolic link to point. Example: exampleobject.txt. // For more information about the naming conventions for objects, see Object naming conventions. 
object_name = 'exampleobject.txt'
# Specify the name of the symbolic link. Example: examplesymlick.txt. 
symlink = 'examplesymlick.txt';

# headers = dict()
# Specify whether to overwrite the object that has the same name as the symbolic link. In this example, x-oss-forbid-overwrite is set to true. This indicates that the object that has the same name cannot be overwritten. 
# headers['x-oss-forbid-overwrite'] = 'true'
# Specify the access control list (ACL) of the object. In this example, this parameter is set to OBJECT_ACL_PRIVATE, which indicates that the ACL of the object is private. Only the owner of the object and authorized users have read and write permissions on the object. 
# headers[OSS_OBJECT_ACL] = oss2.OBJECT_ACL_PRIVATE
# Specify the storage class of the object. In this example, the storage class is set to Standard. 
# headers['x-oss-storage-class'] = oss2.BUCKET_STORAGE_CLASS_STANDARD
# bucket.put_symlink(object_name, symlink, headers=headers)
# Create the symbolic link. 
bucket.put_symlink(object_name, symlink)           
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <title>Document</title>
</head>

<body>
  <button id='upload'>Upload</button>
  <button id='symlink'>Create Symbolic Link</button>  
  <!-- Import the SDK file -->
  <script type="text/javascript" src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"></script>
  <script type="text/javascript">
    const client = new OSS({
       // Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
       region: 'yourRegion',
       // Specify the temporary AccessKey pair obtained from STS. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
       accessKeyId: 'yourAccessKeyId',
       accessKeySecret: 'yourAccessKeySecret',
       // Specify the security token obtained from STS. 
       stsToken: 'yourSecurityToken',
       // Specify the name of the bucket. Example: examplebucket. 
       bucket: "examplebucket",
     });

    const upload = document.getElementById('upload')
    const symlink = document.getElementById('symlink')
    const getSymlink = document.getElementById("getSymlink")

    // Specify the content of the object to upload. 
    const file = new Blob(['examplecontent'])
    // Specify the name of the object to upload to the bucket. 
    const fileName = 'exampleobject.txt'

    // Upload the object. 
    upload.addEventListener('click', () => {
      client.put(fileName, file).then(r => console.log(r))
    })
    
    // Create a symbolic link named symlink.txt. 
    symlink.addEventListener('click', () => {
      client.putSymlink('symlink.txt', fileName).then(r => console.log(r))
    })

  </script>
</body>

</html>
using Aliyun.OSS;
using System.Text;
// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
var endpoint = "yourEndpoint";
// 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. 
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// Specify the name of the bucket. Example: examplebucket. 
var bucketName = "examplebucket";
var targetObjectName = "yourTargetObjectName";
var symlinkObjectName = "yourSymlinkObjectName";
var objectContent = "More than just cloud.";
// Create an OSSClient instance. 
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
    // Upload the object to which the symbolic link points. 
    byte[] binaryData = Encoding.ASCII.GetBytes(objectContent);
    MemoryStream requestContent = new MemoryStream(binaryData);
    client.PutObject(bucketName, targetObjectName, requestContent);
    // Create the symbolic link. 
    client.CreateSymlink(bucketName, symlinkObjectName, targetObjectName);
    // Query the name of the object to which the symbolic link points. 
    var ossSymlink = client.GetSymlink(bucketName, symlinkObjectName);
    Console.WriteLine("Target object is {0}", ossSymlink.Target);
}
catch (Exception ex)
{
    Console.WriteLine("Failed with error info: {0}", ex.Message);
}
// Create a request. 
PutSymlinkRequest putSymlink = new PutSymlinkRequest();
// Specify the name of the bucket. 
putSymlink.setBucketName("yourBucketName");
// Specify the name of the symbolic link. 
putSymlink.setObjectKey("yourSymLink");
// Specify the name of the object to which you want the symbolic link to point. 
putSymlink.setTargetObjectName("yourTargetObjectName");

ObjectMetadata metadata = new ObjectMetadata();
// Specify whether to overwrite the object that has the same name. In this example, this parameter is set to true, which indicates that the object that has the same name cannot be overwritten. 
//metadata.setHeader("x-oss-forbid-overwrite", "true");
// Specify the access control list (ACL) of the object. In this example, the ACL is set to private. 
//metadata.setHeader("x-oss-object-acl", "private");
// Specify the storage class of the object. In this example, the storage class is set to Standard. 
//metadata.setHeader("x-oss-storage-class", "Standard");
putSymlink.setMetadata(metadata);

OSSAsyncTask task = oss.asyncPutSymlink(putSymlink, new OSSCompletedCallback<PutSymlinkRequest, PutSymlinkResult>() {
    @Override
    public void onSuccess(PutSymlinkRequest request, PutSymlinkResult result) {
        Log.d("PutSymlink", "PutSymlink success");
    }

    @Override
    public void onFailure(PutSymlinkRequest request, ClientException clientException,
                          ServiceException serviceException) {
        // Handle request exceptions. 
        if (clientException != null) {
            // Handle client exceptions, such as network exceptions. 
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            // Handle server-side exceptions. 
            Log.e("ErrorCode", serviceException.getErrorCode());
            Log.e("RequestId", serviceException.getRequestId());
            Log.e("HostId", serviceException.getHostId());
            Log.e("RawMessage", serviceException.getRawMessage());
        }
    }
});
task.waitUntilFinished();
package main

import (
    "fmt"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
    "os"
)

func main() {
    // 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. 
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // Create an OSSClient instance. 
    // Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. Specify your actual endpoint. 
    client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // Specify the name of the bucket. Example: examplebucket. 
    bucketName := "examplebucket"
    // Specify the name of the symbolic link. Example: examplesymlink. 
    symObjectKey := "examplesymlink.txt"
    // Specify the name of the object to which the symbolic link points. Example: exampleobject.txt. 
    objectName := "exampleobject.txt"

    bucket, err := client.Bucket(bucketName)
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // Create the symbolic link. 
    option := [] oss.Option{
        // Specify whether to overwrite the object that has the same name as the symbolic link. A value of true specifies that the object is overwritten. A value of false specifies that the object is not overwritten. 
        oss.ForbidOverWrite(true),
        // Specify the access control list (ACL) of the object. In this example, the ACL is set to private. 
        oss.ObjectACL(oss.ACLPrivate),
        // Specify the storage class of the object. In this example, the storage class is set to Standard. 
        oss.StorageClass(oss.StorageStandard),

    }
    err = bucket.PutSymlink(symObjectKey,objectName ,option...)

    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

}
OSSPutSymlinkRequest *request = [OSSPutSymlinkRequest new];
// Specify the name of the bucket. Example: examplebucket. 
request.bucketName = @"examplebucket";
// Specify the name of the symbolic link. 
request.objectKey = @"examplesymlink";
// Specify the full path of the object. The full path cannot contain the bucket name. 
request.targetObjectName = @"exampleobject.txt";

OSSTask *putSymlinkTask = [client putSymlink:request];
[putSymlinkTask continueWithBlock:^id _Nullable(OSSTask * _Nonnull task) {
    if (!task.error) {
        NSLog(@"put symlink success");
    } else {
        NSLog(@"put symlink failed, error: %@", task.error);
    }
    return nil;
}];
#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
            
    /* Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. */
    std::string Endpoint = "yourEndpoint";
    /* Specify the name of the bucket. Example: examplebucket. */
    std::string BucketName = "examplebucket";
    /* Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. */
    std::string ObjectName = "exampledir/exampleobject.txt";
    /* Specify the full path of the symbolic link. Example: shortcut/myobject.txt. */
    std::string LinkName = "shortcut/myobject.txt";

    /* Initialize resources, such as network resources. */
    InitializeSdk();

    ClientConfiguration conf;
    /* 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. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);



    /* Configure the HTTP headers. */
    auto meta = ObjectMetaData();
    meta.setContentType("text/plain");

    /* Configure the user metadata of the object. */
    meta.UserMetaData()["meta"] = "meta-value";

    /* Create the symbolic link. */
    CreateSymlinkRequest request(BucketName, ObjectName, meta);
    request.SetSymlinkTarget(LinkName);
    auto outcome = client.CreateSymlink(request);

    if (!outcome.isSuccess()) {
        /* Handle exceptions. */
        std::cout << "CreateSymlink fail" <<
        ",code:" << outcome.error().Code() <<
        ",message:" << outcome.error().Message() <<
        ",requestId:" << outcome.error().RequestId() << std::endl;
        return -1;
    }

    /* Release resources, such as network resources. */
    ShutdownSdk();
    return 0;
}
#include "oss_api.h"
#include "aos_http_io.h"
/* Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. */
const char *endpoint = "yourEndpoint";
/* Specify the name of the bucket. Example: examplebucket. */
const char *bucket_name = "examplebucket";
/* Specify the full path of the object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt. */
const char *object_name = "exampledir/exampleobject.txt";
/* Specify the full path of the symbolic link that you want to create. */
const char *link_object_name = "yourLinkObjectName";
void init_options(oss_request_options_t *options)
{
    options->config = oss_config_create(options->pool);
    /* Use a char* string to initialize data of the aos_string_t type. */
    aos_str_set(&options->config->endpoint, endpoint);
    /* 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. */
    aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
    aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
    /* Specify whether to use CNAME. The value 0 indicates that CNAME is not used. */
    options->config->is_cname = 0;
    /* Specify network parameters, such as the timeout period. */
    options->ctl = aos_http_controller_create(options->pool, 0);
}
int main(int argc, char *argv[])
{
    /* Call the aos_http_io_initialize method in main() to initialize global resources, such as network resources and memory resources. */
    if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
        exit(1);
    }
    /* Create a memory pool to manage memory. aos_pool_t is equivalent to apr_pool_t. The code used to create a memory pool is included in the APR library. */
    aos_pool_t *pool;
    /* Create a memory pool. The value of the second parameter is NULL. This value indicates that the pool does not inherit other memory pools. */
    aos_pool_create(&pool, NULL);
    /* Create and initialize options. This parameter includes global configuration information, such as endpoint, access_key_id, access_key_secret, is_cname, and curl. */
    oss_request_options_t *oss_client_options;
    /* Allocate the memory resources in the memory pool to the options. */
    oss_client_options = oss_request_options_create(pool);
    /* Initialize oss_client_options. */
    init_options(oss_client_options);
    /* Initialize the parameters. */
    aos_string_t bucket;
    aos_string_t object;
    aos_string_t sym_object;
    aos_table_t *resp_headers = NULL; 
    aos_status_t *resp_status = NULL; 
    aos_str_set(&bucket, bucket_name);
    aos_str_set(&object, object_name);
    aos_str_set(&sym_object, link_object_name);
    resp_status = oss_put_symlink(oss_client_options, &bucket, &sym_object, &object, &resp_headers);
    if (aos_status_is_ok(resp_status)) {
        printf("put symlink succeeded\n");
    } else {
        printf("put symlink failed\n");      
    }
    /* Release the memory pool. This operation releases the memory resources allocated for the request. */
    aos_pool_destroy(pool);
    /* Release the allocated global resources. */
    aos_http_io_deinitialize();
    return 0;
}

Use ossutil

You can create a symbolic link by using ossutil. For more information, see create-symlink (create a symbolic link).

Use the OSS API

If your business requires a high level of customization, you can directly call RESTful APIs. To directly call an API, you must include the signature calculation in your code. For more information, see PutSymlink.

FAQ

Can I create a symbolic link that points to a private object?

Yes, you can create a symbolic link that points to a private object. You can create a symbolic link that points to an object whose ACL is private, public-read, or public-read-write.

How do I determine whether an object is a symbolic link?

You can call the HeadObject or GetObject operation on the object and check the response.

If the requested object is a symbolic link, the content of the object to which the symbolic link points is returned. Response headers Content-Length, ETag, and Content-Md5 are metadata items of the requested object.