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 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.
|
x-oss-object-acl | String | No | The access control list (ACL) of the symbolic link you want to create. Default value:
default.
Valid values:
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:
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 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 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 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
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. |