Object Storage Service:PutSymlink

Use cases

PutSymlink is unique to Object Storage Service (OSS). Use symbolic links to:

• Create shorter, human-readable aliases for objects with long or complex keys.

• Maintain backward-compatible paths when reorganizing your object key structure.

• Point multiple logical paths to a single physical object to save storage.

Usage notes

• OSS does not validate the destination object when creating a symbolic link. OSS does not check whether the destination object exists, whether its storage class is valid, or whether you have access to it.

• The destination object cannot be a symbolic link.

• By default, if an object with the same name already exists and you have the required permissions, PutSymlink overwrites the existing object and returns 200 OK.

• When API operations such as GetObject access the destination object through a symbolic link, OSS checks both the access control list (ACL) of the symbolic link and the ACL of the destination object.

• Request headers prefixed with x-oss-meta- are treated as user metadata of the symbolic link. Example: x-oss-meta-location. An object can have multiple user metadata parameters, but the total size of all user metadata cannot exceed 8 KB.

Versioning

A symbolic link can point to the current version of a destination object. Each version of a symbolic link can point to a different object.

When versioning is enabled on the bucket, PutSymlink generates a new version ID for the symbolic link and returns it in the x-oss-version-id response header.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account have no permissions by default. Grant permissions through RAM Policy or Bucket Policy.

Request syntax

PUT /ObjectName?symlink HTTP/1.1
Host: BucketName.oss-<RegionId>.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
x-oss-symlink-target: TargetObjectName

Request headers

For more information about common request headers such as Host and Date, see Common request headers.

Response headers

The response contains only common response headers. For more information, see Common response headers.

Examples

PUT /link-to-oss.jpg?symlink HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Cache-control: no-cache
Content-Disposition: attachment;filename=oss_download.jpg
Date: Tue, 08 Nov 2016 02:00:25 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-symlink-target: oss****
x-oss-storage-class: Standard

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 08 Nov 2016 02:00:25 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 582131B9109F4EE66CDE56A5
ETag: "0A477B89B4602AA8DECB8E19BFD4****"

PUT /link-to-oss.jpg?symlink HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 06:50:48 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-symlink-target: oss.jpg

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 09 Apr 2019 06:50:48 GMT
Content-Length: 0
Connection: keep-alive
x-oss-version-id: CAEQNRiBgMClj7qD0BYiIDQ5Y2QyMjc3NGZkODRlMTU5M2VkY2U3MWRiNGRh****
x-oss-request-id: 5CAC40C8B7AEADE01700064B
ETag: "136A5E127272200EDAB170DD84DE****"

OSS SDKs

Use OSS SDKs for the following programming languages to call the PutSymlink operation:

• Java

• Go V2

• C

• C++

• .NET

• Android

• iOS

• Node.js

• Browser.js

ossutil

For the ossutil command that corresponds to PutSymlink, see put-symlink.

Error codes

The following table lists error codes specific to PutSymlink.

For common error codes that apply to all OSS operations, see Common error codes.