使用PutBucketReferer为存储空间设置防盗链Referer白名单与黑名单-对象存储-阿里云

调用PutBucketReferer接口设置存储空间（Bucket）级别的Referer访问白名单以及黑名单。

权限说明

阿里云账号默认拥有全部权限。阿里云账号下的RAM用户或RAM角色默认没有任何权限，需要阿里云账号或账号管理员通过RAM Policy或Bucket Policy授予操作权限。

API	Action	说明
PutBucketReferer	oss:PutBucketReferer	设置Bucket的防盗链。

请求语法

PUT /?referer HTTP/1.1
Date: GMT Date
Content-Length：ContentLength
Content-Type: application/xml
Host: BucketName.oss.aliyuncs.com
Authorization: SignatureValue

<?xml version="1.0" encoding="UTF-8"?>
<RefererConfiguration>
  <AllowEmptyReferer>false</AllowEmptyReferer>
  <AllowTruncateQueryString>true</AllowTruncateQueryString>
  <TruncatePath>true</TruncatePath>
  <RefererList>
    <Referer>http://www.aliyun.com</Referer>
    <Referer>https://www.aliyun.com</Referer>
    <Referer>http://www.*.com</Referer>
    <Referer>https://www.?.aliyuncs.com</Referer>
  </RefererList>
  <RefererBlacklist>
    <Referer>http://www.refuse.com</Referer>
    <Referer>https://*.hack.com</Referer>
    <Referer>http://ban.*.com</Referer>
    <Referer>https://www.?.deny.com</Referer>
  </RefererBlacklist>
</RefererConfiguration>

当您在OSS ON云盒中调用该接口时，您需要将Host替换为云盒Endpoint。更多信息，请参见云盒Endpoint。

请求元素

名称	类型	是否必选	示例值	描述
RefererConfiguration	容器	是	不涉及	保存Referer配置内容的容器。子节点：AllowEmptyReferer、AllowTruncateQueryString、RefererList 父节点：无
AllowEmptyReferer	枚举字符串	是	false	指定是否允许Referer字段为空的请求访问OSS。取值如下： true（默认值）：允许Referer字段为空的请求访问OSS。 false：不允许Referer字段为空的请求访问OSS。父节点：RefererConfiguration
AllowTruncateQueryString	枚举字符串	否	true	指定匹配Referer时，是否截断URL中的QueryString。取值如下： true：截断QueryString。 false（默认值）：不截断QueryString。父节点：RefererConfiguration
TruncatePath	枚举字符串	否	true	指定匹配Referer时，是否截断URL中包括Path在内的后续所有部分。取值如下： true：截断URL中包括Path在内的后续所有部分。重要如果TruncatePath取值为true，则AllowTruncateQueryString取值必须为true。原因是QueryString为URL中Path后续的一部分，截断Path的同时也会截断QueryString。 false（默认值）：不截断URL中包括Path在内的后续所有部分。父节点：RefererConfiguration
RefererList	容器	是	不涉及	保存Referer访问白名单的容器。说明 PutBucketReferer为覆盖语义，即RefererList中新指定的白名单列表将覆盖已配置的白名单列表。当您上传的RefererList为空时（即不包含Referer请求元素），此操作将清空RefererList中已配置的白名单列表。父节点：RefererConfiguration 子节点：Referer
RefererBlacklist	容器	否	不涉及	保存Referer访问黑名单的容器。说明 PutBucketReferer为覆盖语义，即RefererBlacklist中新指定的黑名单列表将覆盖已配置的黑名单列表。当您上传的RefererBlacklist为空时（即不包含Referer请求元素），此操作将清空RefererBlacklist中已配置的黑名单列表。父节点：RefererConfiguration 子节点：Referer
Referer	字符串	否	http://www.aliyun.com	指定Referer访问白名单或黑名单记录。父节点：RefererList或RefererBlacklist

此接口还涉及其他公共请求头，例如Host、Authorization等。更多信息，请参见公共请求头（Common Request Headers）。

响应头

此接口仅涉及公共响应头。更多信息，请参见公共响应头（Common Response Headers）。

示例

请求示例

不包含Referer的请求示例

PUT /?referer HTTP/1.1
Host: BucketName.oss.example.com
Content-Length: 247
Date: Thu, 17 Apr 2025 03:21:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

<?xml version="1.0" encoding="UTF-8"?>
<RefererConfiguration>
  <AllowEmptyReferer>true</AllowEmptyReferer>
  <RefererList/>
</RefererConfiguration>

仅包含白名单Referer的请求示例

PUT /?referer HTTP/1.1
Host: BucketName.oss.example.com
Content-Length: 247
Date: Thu, 17 Apr 2025 03:21:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

<?xml version="1.0" encoding="UTF-8"?>
<RefererConfiguration>
  <AllowEmptyReferer>false</AllowEmptyReferer>
  <AllowTruncateQueryString>true</AllowTruncateQueryString>
  <TruncatePath>true</TruncatePath>
  <RefererList>
    <Referer>http://www.aliyun.com</Referer>
    <Referer>https://www.aliyun.com</Referer>
    <Referer>http://www.*.com</Referer>
    <Referer>https://www.?.aliyuncs.com</Referer>
  </RefererList>
</RefererConfiguration>

同时包含白名单Referer以及黑名单Referer的请求示例

PUT /?referer HTTP/1.1
Host: BucketName.oss.example.com
Content-Length: ***
Date: Thu, 17 Apr 2025 03:21:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

<?xml version="1.0" encoding="UTF-8"?>
<RefererConfiguration>
  <AllowEmptyReferer>false</AllowEmptyReferer>
  <AllowTruncateQueryString>true</AllowTruncateQueryString>
  <TruncatePath>true</TruncatePath>
  <RefererList>
    <Referer>http://www.aliyun.com</Referer>
    <Referer>https://www.aliyun.com</Referer>
    <Referer>http://www.*.com</Referer>
    <Referer>https://www.?.aliyuncs.com</Referer>
  </RefererList>
  <RefererBlacklist>
    <Referer>http://www.refuse.com</Referer>
    <Referer>https://*.hack.com</Referer>
    <Referer>http://ban.*.com</Referer>
    <Referer>https://www.?.deny.com</Referer>
  </RefererBlacklist>
</RefererConfiguration>

返回示例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 04 May 2012 03:21:12 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS
x-oss-server-time: 110

SDK

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

命令行工具ossutil

PutBucketReferer接口所对应的ossutil命令，请参见put-bucket-referer。

错误码

错误码	HTTP状态码	描述
AccessDenied	403	没有操作权限。只有Bucket的拥有者才能发起PutBucketReferer请求。
InvalidDigest	400	上传了Content-MD5请求头后，OSS会计算消息体的Content-MD5并检查一致性。如果不一致，则返回此错误码。
InlineDataTooLarge	400	防盗链Referer名单超过了20 KB大小上限，请减少名单中的条目以满足限制要求。