Creates a symbolic link that points to a destination object. You can use the symbolic link to access the destination object.
- 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.
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.
PUT /ObjectName?symlink HTTP/1.1 Host: BucketName.oss-cn-hangzhou.aliyuncs.com Date: GMT Date Authorization: SignatureValue x-oss-symlink-target: TargetObjectName
|x-oss-forbid-overwrite||String||No||Specifies whether the PutSymlink operation overwrites the object that has the same name. |
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.
The destination object to which the symbolic link points.
The naming conventions for the destination object are the same as those for objects.
|x-oss-object-acl||String||No||The ACL of the object. Default value: default. |
For more information about object ACLs, see Object ACL.
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.
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.
The response to a PutSymlink request contains only common response headers. For more information, see Common response headers.
- 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: StandardSample 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 o3shiyktjw16xw1:NVXXKiyUJ2tg07PxINinU0eO**** x-oss-symlink-target: oss.jpgSample 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****"
You can use OSS SDKs for the following programming languages to call the PutSymlink operation:
|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.|