PutSymlink接口用于为OSS的目标文件（TargetObject）创建软链接（Symlink），您可以通过该软链接访问TargetObject。

注意事项

调用PutSymlink接口时，有以下注意事项：

  • 使用PutSymlink接口创建软链接时不会检查目标文件是否存在、目标文件类型是否合法以及目标文件是否有访问权限。
  • Symlink自身的访问权限（ACL）以及目标文件的ACL检查仅会在GetObject等需要访问目标文件的API中进行。
  • 使用PutSymlink接口时，携带以x-oss-meta-为前缀的参数，则被视为user meta，例如x-oss-meta-location。一个Object可以有多个类似的参数，但所有的user meta总大小不能超过8 KB。
  • 默认情况下，如果试图添加的文件已经存在，并且有访问权限，则新添加的文件将覆盖原来的文件，成功添加后将返回200 OK。

版本控制

您可以通过TargetObject创建的软链接指向TargetObject的当前版本。

软链接本身也可以有多个版本，每个不同的版本可以指向不同的TargetObject，版本ID由OSS自动生成，在响应Header中返回x-oss-version-id。

请求语法

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 字符串 否 指定PutSymlink操作时是否覆盖同名Object。
  • 不指定x-oss-forbid-overwrite时，默认覆盖同名Object。
  • 指定x-oss-forbid-overwrite为true时，表示禁止覆盖同名Object；指定x-oss-forbid-overwrite为false时，表示允许覆盖同名Object。
说明
  • 当目标Bucket处于已开启或已暂停版本控制状态时，x-oss-forbid-overwrite请求Header设置无效，即允许覆盖同名Object。
  • 设置x-oss-forbid-overwrite请求Header会导致QPS处理性能下降，如果您有大量的操作需要使用x-oss-forbid-overwrite请求Header（QPS > 1000），请联系技术支持，避免影响您的业务。
x-oss-symlink-target 字符串 是

软链接指向的目标文件。

合法值：命名规范同Object

  • TargetObjectName同ObjectName一样，需要对其进行URL编码。
  • 软链接的目标文件类型不能为软链接。
x-oss-storage-class 字符串 否

指定Object的存储类型。

取值：Standard、IA、Archive

  • IA与Archive类型的单个文件如不足64 KB，会按64 KB计量计费。建议在使用Symlink接口时不要将Object的存储类型指定为IA或Archive。
  • 对于任意存储类型的Bucket，若上传Object时指定此参数，则此次上传的Object将存储为指定的类型。例如，在IA类型的Bucket中上传Object时，若指定x-oss-storage-class为Standard，则该Object直接存储为Standard。

支持的接口：PutObject、InitMultipartUpload、AppendObject、 PutObjectSymlink、CopyObject

示例

  • 请求示例 
    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
    返回示例 
    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****"
  • 版本控制请求示例 
    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
    返回示例 
    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

PutSymlink接口所对应的各语言SDK如下：

错误码

错误码 HTTP 状态码 描述
InvalidArgument 400 StorageClass的值不合法。
FileAlreadyExists 409 当请求Header中携带x-oss-forbid-overwrite=true时，表示禁止覆盖同名文件。如果文件已存在，则返回此错误。
FileImmutable 409 Bucket内的数据处于被保护状态时，若您尝试删除或修改这些数据，将返回此错误码。