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

Usage notes

  • 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 can access the target object.
  • The ACL of a symbolic link and the ACL of the target object to which the symbolic link points are checked when API operations such as GetObject are called to access the target 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 parameters whose names contain the x-oss-meta- prefix. 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 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 target object and point the symbolic link to the current version of the target object.

A symbolic link can have multiple versions. You can use the PutSymlink operation to point each version of a symbolic link to different target 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 structure

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 as that of the symbolic link you want to create.
  • If x-oss-forbid-overwrite is not specified or the value of x-oss-forbid-overwrite is set to false, an existing object that has the same name as that of the symbolic link you want to create is overwritten.
  • If the value of x-oss-forbid-overwrite is set to true, an existing object that has the same name as that of the symbolic link you want to create cannot be overwritten.

If you specify the x-oss-forbid-overwrite request 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), submit a ticket.

Note The x-oss-forbid-overwrite request header does not take effect when versioning is enabled or suspended for the bucket in which the symbolic link you want to create is stored. In this case, the PutSymlink operation overwrites the existing object that has the same name as that of the symbolic link you want to create.
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-object-acl String No The access control list (ACL) of the symbolic link you want to create. Default value: default.
Valid values:
  • default: The ACL of the symbolic link is the same as that of the bucket in which the symbolic link is stored.
  • private: The symbolic link is a private resource. Only the owner of this symbolic link and authorized users have permissions to read and write this symbolic link.
  • public-read: The symbolic link is a public-read resource. Only the owner of this symbolic link and authorized users have permissions to write this symbolic link. Other users can only read the symbolic link. Exercise caution when you set the ACL of the symbolic link to this value.
  • public-read-write: The symbolic link is a public-read-write resource. All users have permissions to read and write the symbolic link. Exercise caution when you set the ACL of the symbolic link to this value.

For more information about ACLs, see ACL.

x-oss-storage-class String No

The storage class of the symbolic link.

If you specify the storage class when you upload the object, the specified storage class applies regardless of the storage class of the bucket in which the object is stored. For example, if you set x-oss-storage-class to Standard when you upload an object to an IA bucket, the storage class of the uploaded object is Standard.

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 headers included in PutSymlink requests such as Host and Date, see Common request headers.

Response headers

The response headers involved in this API operation contain 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 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 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 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

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 with the same name already exists and the request contains the x-oss-forbid-overwrite=true header.
FileImmutable 409 The error message returned because the data you want to delete or modify is protected by a retention policy.