文档

PutBucketReferer

更新时间:

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

请求语法

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: Fri, 04 May 2012 03:21:12 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otf****:KU5h8YMUC78M30dXqf3JxrTZH****
    
    <?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: Fri, 04 May 2012 03:21:12 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otf****:KU5h8YMUC78M30dXqf3JxrTZ****
    
    <?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: Fri, 04 May 2012 03:21:12 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otf****:KU5h8YMUC78M30dXqf3JxrTZ****
    
    <?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如下:

错误码

错误码

HTTP状态码

描述

AccessDenied

403

没有操作权限。只有Bucket的拥有者才能发起PutBucketReferer请求。

InvalidDigest

400

上传了Content-MD5请求头后,OSS会计算消息体的Content-MD5并检查一致性。如果不一致,则返回此错误码。

InlineDataTooLarge

400

防盗链Referer名单超过了20 KB大小上限,请减少名单中的条目以满足限制要求。

  • 本页导读 (1)
文档反馈