全部產品
Search
文件中心

:PutBucketReferer

更新時間:Jun 19, 2024

調用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>

請求元素

名稱

類型

是否必選

樣本值

描述

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 qn6q**************:77Dv****************
    
    <?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 qn6q**************:77Dv****************
    
    <?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 qn6q**************:77Dv****************
    
    <?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大小上限,請減少名單中的條目以滿足限制要求。