You can call this operation to configure a Referer whitelist for a bucket. When you call this operation, you can configure the Referer whitelist and specify whether an empty Referer field is allowed.

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>true</AllowEmptyReferer>
    <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 Description
RefererConfiguration Container Yes The container that contains the Referer configurations.

Child node: AllowEmptyReferer and RefererList.

Parent node: none.

AllowEmptyReferer Boolean Yes Specifies whether the Referer field can be left empty in an access request.

Valid values: true and false. Default value: true.

Parent node: RefererConfiguration.

RefererList Container Yes 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 node: RefererConfiguration.

Child node: Referer.

Referer String No The Referer whitelist that you want to configure.

Parent node: RefererList.

Examples

Sample request
  • 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 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****:KU5h8YMUC78M30dXqf3JxrTZ****
    
    <? xml version="1.0" encoding="UTF-8"? >
    <RefererConfiguration>
    <AllowEmptyReferer>true</AllowEmptyReferer>
    <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 response

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 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.