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.
Note
|
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.
|
x-oss-storage-class | String | No |
The storage class of the target object. Valid values: Standard, IA, and Archive
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 responsesHTTP/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 responsesHTTP/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. |