All Products
Search
Document Center

Object Storage Service:PutSymlink

Last Updated:Apr 28, 2024

Creates a symbolic link that points to a destination object. You can use the symbolic link to access the destination object.

Usage notes

  • 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.

Versioning

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.

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.

  • If you do not specify the x-oss-forbid-overwrite header or if you set the x-oss-forbid-overwrite header to false, the object that has the same name is overwritten.

  • If you set the x-oss-forbid-overwrite header to true, the object that has the same name cannot be overwritten.

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.

x-oss-symlink-target

String

Yes

The destination object to which the symbolic link points.

The naming conventions for the destination object are the same as those for objects.

  • Similar to ObjectName, TargetObjectName must be URL-encoded.

  • The destination object to which a symbolic link points cannot be a symbolic link.

x-oss-object-acl

String

No

The ACL of the object. Default value: default.

Valid values:

  • default: The ACL of the object is the same as the ACL of the bucket in which the object is stored.

  • private: The ACL of the object is private. Only the owner of the object and authorized users have the read and write permissions on the object.

  • public-read: The ACL of the object is public-read. Only the owner of the object and authorized users have the read and write permissions on the object. Other users have only the read permissions on the object. Exercise caution when you set the ACL of the object to this value.

  • public-read-write: The ACL of the object is public-read-write. All users have the read and write permissions on the object. Exercise caution when you set the ACL of the object to this value.

For more information about object ACLs, see Object ACLs.

x-oss-storage-class

String

No

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.

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

Response headers

The response to a PutSymlink request contains 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 qn6q**************:77Dv**************** 
    x-oss-symlink-target: oss****
    x-oss-storage-class: Standard

    Sample 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 qn6q**************:77Dv****************
    x-oss-symlink-target: oss.jpg

    Sample 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****"

OSS SDKs

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 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.