You can call this operation to create a symbolic link that points to a target object. You can use the symbolic link to access the target object.

Usage notes

When you call the PutSymlink operation, take note of the following items:

  • When you use the PutSymlink operation to create a symbolic link, OSS does not check whether the target object exists, whether the storage class of the target object is valid, or whether you have the permissions to access the target object.
  • The ACL of the symbolic link and the ACL of the target object are checked when API operations such as GetObject are called to access the target object.
  • If a PutSymlink request carries a parameter that contains the x-oss-meta- prefix, the parameter is considered to be user metadata. Example: x-oss-meta-location. An object can have multiple parameters that contain the x-oss-meta- prefix. However, the total size of all user metadata cannot exceed 8 KB.
  • By default, if the object that you want to add already exists and you have permissions to access the object, the new object overwrites the existing object, and OSS returns the 200 OK message.

Versioning

You can use a symbolic link that is created for the target object to point to the current version of the target object.

You can have multiple versions of a symbolic link. Each version can point to a different target object. The version ID is automatically generated by OSS. x-oss-version-id is returned in the response 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.
  • By default, if x-oss-forbid-overwrite is not specified, the object with the same name is overwritten.
  • If the value of x-oss-forbid-overwrite is set to true, the object that has the same name cannot be overwritten. If the value of x-oss-forbid-overwrite is set to false, the object that has the same name can be overwritten.
Note
  • The x-oss-forbid-overwrite request header is invalid when the versioning status of the target bucket is Enabled or Suspended. In this case, the PutObject operation overwrites the object with the same name.
  • Specifying the x-oss-forbid-overwrite request header may degrade the queries per second (QPS) performance of OSS. If you want to use the x-oss-forbid-overwrite request header to perform a large number of operations (QPS greater than 1000), submit a ticket.
x-oss-symlink-target String Yes

The target object to which the symbolic link points.

The naming conventions for target objects are the same as those for objects.

  • Similar to ObjectName, TargetObjectName must be URL-encoded.
  • The target object to which a symbolic link points cannot be a symbolic link.
x-oss-storage-class String No

The storage class of the target object.

Valid values: Standard, IA, and Archive

  • An IA or Archive object smaller than 64 KB is charged as 64 KB. We recommend that you do not set the storage class in PutSymlink to IA or Archive.
  • If you specify the value of x-oss-storage-class when you upload an object to a bucket, the storage class of the uploaded object is the specified value of x-oss-storage-class regardless of the storage class of the bucket. For example, if you set the value of x-oss-storage-class to Standard when you upload an object to a bucket of the IA storage class, the storage class of the object is Standard.

Supported operations: PutObject, InitiateMultipartUpload, AppendObject, PutObjectSymlink, and CopyObject.

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 qn6qrrqxo2oawuk53otfjbyc:kZoYNv66bsmc10+dcGKw5x2****= x-oss-symlink-target: oss****
x-oss-storage-class: Standard
    Sample 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 request for a versioning-enabled 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 o3shiyktjw16xw1:NVXXKiyUJ2tg07PxINinU0eO****
x-oss-symlink-target: oss.jpg
    Sample 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****"

SDK

The SDKs of the PutSymlink operation for various programming languages:

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 with the same name already exists when the request contains the x-oss-forbid-overwrite header and the value of this header is set to true.
FileImmutable 409 The error message returned because you delete or modify the data. During the protection period, data in the bucket is protected.