Configures the Referer whitelist of a bucket. You can also specify whether empty Referer fields are allowed and whether query strings are truncated when you call PutBucketReferer to configure Referer for a bucket.

Request syntax

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>false</AllowTruncateQueryString>
  <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>

Request elements

Element Type Required Example Description
RefererConfiguration Container Yes N/A The container that contains the Referer configurations.

Child nodes: AllowEmptyReferer, AllowTruncateQueryString, and RefererList

Parent nodes: none
AllowEmptyReferer Enumerated string Yes false Specifies whether to allow the request whose Referer field is empty. Default value: true. Valid values:
  • true: Requests that have an empty Referer field are allowed.
  • false: Requests that have an empty Referer field are denied.

Parent nodes: RefererConfiguration
AllowTruncateQueryString Enumerated string No false Specifies whether query strings are truncated. Default value: true. Valid values:
  • true: Query strings are truncated.
  • false: Query strings are not truncated.

Parent nodes: RefererConfiguration
RefererList Container Yes N/A The container that contains the Referer whitelist.
Note The PutBucketReferer operation replaces the existing Referer whitelist with the Referer whitelist specified in RefererList. If RefererList is not specified in the request, that is, no Referer elements are included, this operation clears the existing Referer whitelist.

Parent nodes: RefererConfiguration

Child nodes: Referer
Referer String No http://www.aliyun.com The specified Referer whitelist.

Parent nodes: RefererList

Examples

Sample requests
  • Sample request that does not contain Referer elements 
    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>
  • Sample request that contains Referer elements 
    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>false</AllowTruncateQueryString>
<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>

Sample responses

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

SDK

You can use OSS SDKs for the following programming languages to call PutBucketReferer:

Error codes

Error code HTTP status code Description
AccessDenied 403 The error message returned because you are not authorized to perform the PutBucketReferer operation. Only the owner of a bucket can initiate PutBucketReferer requests to the bucket.
InvalidDigest 400 The error message returned because the Content-MD5 value of the message body is inconsistent with the Content-MD5 value in the request header.