PutSymlink - Object Storage Service - Alibaba Cloud Documentation Center

Creates a symbolic link that points to a destination object. You can use the symbolic link to access the destination object.

Usage notes

When you call the PutSymlink operation to create a symbolic link, Object Storage Service (OSS) does not check whether the destination object exists, whether the storage class of the destination object is valid, or whether you can access the destination object.
The access control list (ACL) of a symbolic link and the ACL of the destination object to which the symbolic link points are checked when API operations such as GetObject are called to access the destination object.
If a PutSymlink request contains a parameter whose name is prefixed with x-oss-meta-, the parameter is considered the user metadata of the symbolic link. Example: x-oss-meta-location. An object can have multiple similar parameters. However, the total size of all user metadata of the object cannot exceed 8 KB.
By default, if the object that you want to create already exists, and you have the permissions to access the existing object, the new object overwrites the existing object, and OSS returns 200 OK.

Versioning

You can create a symbolic link for a destination object and point the symbolic link to the current version of the destination object.

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 returned in the response as the x-oss-version-id header.

Request syntax

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

Request headers

Header	Type	Required	Description
x-oss-forbid-overwrite	String	No	Specifies whether the PutSymlink operation overwrites the object that has the same name. If you do not specify the x-oss-forbid-overwrite header or if you set the x-oss-forbid-overwrite header to false, the object that has the same name is overwritten. If you set the x-oss-forbid-overwrite header to true, the object that has the same name cannot be overwritten. If you specify the x-oss-forbid-overwrite header, the queries per second (QPS) performance of OSS may be degraded. If you want to specify the x-oss-forbid-overwrite header in a large number of requests (QPS greater than 1,000), contact technical support. Note The x-oss-forbid-overwrite header does not take effect when versioning is enabled or suspended for the destination bucket. In this case, the PutSymlink operation overwrites the object that has the same name.
x-oss-symlink-target	String	Yes	The destination object to which the symbolic link points. The naming conventions for the destination object are the same as those for objects. Similar to ObjectName, TargetObjectName must be URL-encoded. The destination object to which a symbolic link points cannot be a symbolic link.
x-oss-object-acl	String	No	The ACL of the object. Default value: default. Valid values: default: The ACL of the object is the same as the ACL of the bucket in which the object is stored. private: The ACL of the object is private. Only the owner of the object and authorized users have the read and write permissions on the object. public-read: The ACL of the object is public-read. Only the owner of the object and authorized users have the read and write permissions on the object. Other users have only the read permissions on the object. Exercise caution when you set the ACL of the object to this value. public-read-write: The ACL of the object is public-read-write. All users have the read and write permissions on the object. Exercise caution when you set the ACL of the object to this value. For more information about object ACLs, see Object ACLs.
x-oss-storage-class	String	No	The storage class of the object. If you specify the x-oss-storage-class header when you upload an object, the storage class of the uploaded object is the specified header value regardless of the storage class of the bucket to which the object is uploaded. For example, if you set x-oss-storage-class to Standard when you upload an object to an Infrequent Access (IA) bucket, the object is stored as a Standard object. Valid values: Standard IA Archive IA and Archive objects have a minimum billable size of 64 KB. We recommend that you do not set the storage class to IA or Archive in PutSymlink requests. For more information about storage classes, see Overview.

For more information about the common request headers included in a PutSymlink request, such as Host and Date, see Common request headers.

Response headers

The response to a PutSymlink request contains only common response headers. For more information, see Common response headers.

Examples

Sample requests

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: OSS qn6q**************:77Dv**************** 
x-oss-symlink-target: oss****
x-oss-storage-class: Standard

Sample success responses

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****"

Sample requests for a versioned bucket

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: OSS qn6q**************:77Dv****************
x-oss-symlink-target: oss.jpg

Sample success responses

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

You can use OSS SDKs for the following programming languages to call the PutSymlink operation:

Error codes

Error code	HTTP status code	Description
InvalidArgument	400	The error message returned because the value of StorageClass is invalid.
FileAlreadyExists	409	The error message returned because an object that has the same name already exists and the x-oss-forbid-overwrite header is set to true in the request.
FileImmutable	409	The error message returned because the data that you want to delete or modify is protected by a retention policy.