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

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

Create a symbolic link

A symbolic link can have multiple versions. When you create a symbolic link in a versioning-enabled bucket, the version ID of the symbolic link is automatically generated by OSS and is returned as the x-oss-version-id header in the response. You can create a symbolic link to which the current version of an object points.

Note

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

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

const OSS = require("ali-oss");

const client = new OSS({
  // Set region to the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set region to oss-cn-hangzhou.
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the bucket name.
  bucket: 'yourbucketname'
});

async function putSymlink() {
  // Specify the name of the symbolic link to create.
  const symlinkName = "symlinkName";
  // Specify the target object for the symbolic link.
  const targetName = "targetName";
  // Specify the versionId of the target object.
  const versionId = "versionId";
  const result = await client.putSymlink(symlinkName, targetName, {
    versionId,
  });
  console.log(result);
}

putSymlink();

Get a symbolic link

By default, the GetSymlink operation obtains 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 code provides an example on how to query a symbolic link:

const OSS = require("ali-oss");

const client = new OSS({
  // Set region to the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set region to oss-cn-hangzhou.
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the bucket name.
  bucket: 'yourbucketname'
});

async function getSymlink() {
  // Specify the name of the symbolic link to get.
  const targetName = "targetName";
  // Specify the versionId of the symbolic link to get.
  const versionId = "versionId";

  // Get the content of the symbolic link for the specified versionId.
  const result = await client.getSymlink(targetName, {
    versionId,
  });
  console.log(result);
}

getSymlink();

References

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