You can call this operation to set a bucket to the static website hosting mode and set redirection rules.

Note
  • Static websites are websites where all web pages consist of only static content, including scripts such as JavaScript running on the client. A bucket in static website hosting mode does not support content that needs to be processed by the server, such as PHP, JSP, and ASP.NET content.
  • To use your own domain name to access bucket-based static websites, you can use CNAME. For more information, see Bind custom domain names.
  • When you set a bucket to the static website hosting mode, you can specify the index page and the error page. The specified index page and error page must be objects in the bucket.
  • After a bucket is set to the static website hosting mode, OSS returns the index page for anonymous access to the root domain name of the static website, and returns the result of GetBucket for signed access to the root domain name of the static website.

website

The PutBucketWebsite operation has two functions:

  • Configure the default homepage and the default 404 page.
  • Configure RoutingRule. RoutingRule is used to specify the redirection-based back-to-origin rule and mirroring-based back-to-origin rule.
    Note Mirroring-based back-to-origin supports Alibaba Cloud public cloud and Finance Cloud.

The following code provides an example of the website parameter:

<WebsiteConfiguration>
  <IndexDocument>
    <Suffix>index.html</Suffix>
    <SupportSubDir>true</SupportSubDir>
    <Type>0</Type>
  </IndexDocument>
  <ErrorDocument>
    <Key>error.html</Key>
  </ErrorDocument>
  <RoutingRules>
    <RoutingRule>
      <RuleNumber>1</RuleNumber>
      <Condition>
        <KeyPrefixEquals>abc/</KeyPrefixEquals>
        <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
      </Condition>
      <Redirect>
        <RedirectType>Mirror</RedirectType>
        <PassQueryString>true</PassQueryString>
        <MirrorURL>http://www.test.com/</MirrorURL>
        <MirrorPassQueryString>true</MirrorPassQueryString>
        <MirrorFollowRedirect>true</MirrorFollowRedirect>
        <MirrorCheckMd5>false</MirrorCheckMd5>
        <MirrorHeaders>
          <PassAll>true</PassAll>
          <Pass>myheader-key1</Pass>
          <Pass>myheader-key2</Pass>
          <Remove>myheader-key3</Remove>
          <Remove>myheader-key4</Remove>
          <Set>
            <Key>myheader-key5</Key>
            <Value>myheader-value5</Value>
          </Set>
        </MirrorHeaders>
      </Redirect>
    </RoutingRule>
    <RoutingRule>
      <RuleNumber>2</RuleNumber>
      <Condition>
        <KeyPrefixEquals>abc/</KeyPrefixEquals>
        <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
        <IncludeHeader>
          <Key>host</Key>
          <Equals>test.oss-cn-beijing-internal.aliyuncs.com</Equals>
        </IncludeHeader>
      </Condition>
      <Redirect>
        <RedirectType>AliCDN</RedirectType>
        <Protocol>http</Protocol>
        <HostName>www.test.com</HostName>
        <PassQueryString>false</PassQueryString>
        <ReplaceKeyWith>prefix/${key}.suffix</ReplaceKeyWith>
        <HttpRedirectCode>301</HttpRedirectCode>
      </Redirect>
    </RoutingRule>
  </RoutingRules>
</WebsiteConfiguration>

Request structure

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

<? xml version="1.0" encoding="UTF-8"? >
<WebsiteConfiguration>
    <IndexDocument>
        <Suffix>index.html</Suffix>
    </IndexDocument>
    <ErrorDocument>
        <Key>errorDocument.html</Key>
    </ErrorDocument>
</WebsiteConfiguration>

Request parameters

Parameter Type Description Required
WebsiteConfiguration Container The root node.

Parent node: none

Yes
IndexDocument Container The container for the default homepage.

Parent node: WebsiteConfiguration

Conditional. You must specify at least one of the following containers: IndexDocument, ErrorDocument, and RoutingRules.
Suffix String The default homepage.

If this parameter is set, the default homepage is returned for access to objects whose names end with a forward slash (/).

Parent node: IndexDocument

Conditional. This parameter must be specified if its parent node IndexDocument is specified.
ErrorDocument Container The container for the default 404 page.

Parent node: WebsiteConfiguration

Conditional. You must specify at least one of the following containers: IndexDocument, ErrorDocument, and RoutingRules.
Key Container The default 404 page.

If this parameter is specified, the 404 page is returned when the target object does not exist.

Parent node: ErrorDocument

Conditional. This parameter must be specified if its parent node ErrorDocument is specified.
RoutingRules Container The container for RoutingRule.

Parent node: WebsiteConfiguration

Conditional. You must specify at least one of the following containers: IndexDocument, ErrorDocument, and RoutingRules.
RoutingRule Container Specifies routing rules or mirroring-based back-to-origin rules. You can specify a maximum of five redirection rules.

Parent node: RoutingRules

No
SupportSubDir String Specifies whether to search for the default homepage of a subfolder when you access the subfolder.

A value of false indicates that the request is redirected to the default homepage of the root folder instead of that of the subfolder. A value of true indicates that the request is redirected to the default homepage of the subfolder.

If the default homepage for access to bucket.oss-cn-hangzhou.aliyuncs.com/subdir/ is set to index.html. A value of false indicates that the request is redirected to bucket.oss-cn-hangzhou.aliyuncs.com/index.html, and a value of true indicates that the request is redirected to bucket.oss-cn-hangzhou.aliyuncs.com/subdir/index.html.

Default value: false

Parent node: IndexDocument

No
Type HTTP status code Specifies the operation to perform when the default homepage is set, the name of the accessed object does not end with a forward slash (/), and the object does not exist.
Note This parameter takes effect only when SupportSubDir is set to true. It takes effect after RoutingRule and before ErrorFile.

If the default homepage for access to bucket.oss-cn-hangzhou.aliyuncs.com/abc is set to index.html and the abc object does not exist. The operations corresponding to the valid values of Type are as follows:

  • 0: checks whether abc/index.html (in the object + slash (/) + homepage format) exists. If it exists, OSS returns 302 and the Location header /abc/ (in the forward slash (/) + object + forward slash (/) format) in the response is URL-encoded. If it does not exist, OSS returns 404 and continues to check ErrorFile.
  • 1: OSS returns 404 and NoSuchKey and continues to check ErrorFile.
  • 2: checks whether abc/index.html exists. If it exists, the content of the object is returned. If it does not exist, OSS returns 404 and continues to check ErrorFile.

Default value: 0

Parent node: IndexDocument

No
RuleNumber Positive integer The sequence number used to match and run redirection rules. Redirection rules are matched based on this sequence number. If a match succeeds, the rule is run and the subsequent rules are not executed.

Parent node: RoutingRule

Conditional. This parameter must be specified if its parent node RoutingRule is specified.
Condition Container Specifies the matching conditions.

If all of the specified conditions are met, the rule is executed. The nodes in the container are in the AND relationship. A request must meet all the conditions to be considered a match.

Parent node: RoutingRule

Conditional. This parameter must be specified if its parent node RoutingRule is specified.
KeyPrefixEquals String Specifies that objects whose names contain the specified prefix can match the rule.

Parent node: Condition

No
HttpErrorCodeReturnedEquals HTTP status code Specifies that the rule is matched only when the specified object is accessed and the specified status code is returned. If the redirection rule is the mirroring-based back-to-origin rule, the parameter value must be 404.

Parent node: Condition

No
IncludeHeader Container Specifies that the rule is matched only when the specified header is included in the request and the header value equals the specified value. A maximum of five containers can be specified.

Parent node: Condition

No
Key String Specifies that the rule is matched only when the specified header is included in the request and the header value equals the value specified by Equals.

Parent node: IncludeHeader

Conditional. This parameter must be specified if its parent node IncludeHeader is specified.
Equals String Specifies that the rule is matched only when the header specified by Key is included in the request and the header value equals the specified value.

Parent node: IncludeHeader

Conditional. This parameter must be specified if its parent node IncludeHeader is specified.
Redirect Container Specifies the operation to perform after the rule is matched.

Parent node: RoutingRule

Conditional. This parameter must be specified if its parent node RoutingRule is specified.
RedirectType String The redirecting type. Valid values:
  • Mirror: back-to-origin
  • External: external redirection. OSS returns the 3xx HTTP redirect code and the Location header for your to redirect the request to another IP address.
  • Internal: internal redirection. OSS redirects the access from object1 to object2 based on the rule. In this case, the user accesses object2 instead of object1.
  • AliCDN: Alibaba Cloud CDN-based redirection. OSS adds an additional header to the request, which is different from the External type. After CDN identifies the header, CDN redirects the access to the specified IP address and returns the obtained data instead of the redirect request to the user.

Parent node: Redirect

Conditional. This parameter must be specified if its parent node Redirect is specified.
PassQueryString Boolean Specifies whether the request parameter is carried when the redirection- or mirroring-based back-to-origin is performed.

For example, if the parameter ? a=b&c=d is carried in a request sent to OSS and this parameter is set to true, this parameter is added to the Location header when the HTTP redirect code is 302. For example, if the request is Location:www.test.com? a=b&c=d and the redirecting type is mirroring-based back-to-origin, the ?a=b&c=d parameter is also carried in the back-to-origin request.

Default value: false

Valid values: true and false

Parent node: Redirect

No
MirrorURL String Specifies the IP address of the origin for mirroring-based back-to-origin. This parameter takes effect only when the value of RedirectType is Mirror.

URLs that start with http:// or https:// must end with a forward slash (/). OSS adds the object name to the string to form the back-to-origin URL. For example, the object to access is myobject. If the specified URL is http://www.test.com/, the back-to-origin URL is http://www.test.com/myobject. If the specified URL is http://www.test.com/dir1/, the back-to-origin URL is http://www.test.com/dir1/myobject.

Parent node: Redirect

Conditional. This parameter must be specified if RedirectType is set to Mirror.
MirrorPassQueryString Boolean This parameter plays the same role as PassQueryString and has a higher priority than PassQueryString. However, this parameter take effect only when RedirectType is set to Mirror.

Default value: false

Parent node: Redirect

No
MirrorFollowRedirect Boolean Specifies whether the access is redirected to the specified Location if the origin returns a 3xx HTTP status code and when the origin receives a mirroring-based back-to-origin request.

For example, when a mirroring-based back-to-origin request is initiated, the origin returns 302, and Location is specified.

  • In this case, if the value of MirrorFollowRedirect is true, OSS continues to send requests to the IP address specified by Location. A request can be redirected for a maximum of 10 times. If a request is redirected for more than 10 times, a mirroring-based back-to-origin failure is returned.
  • If the value of MirrorFollowRedirect is false, OSS returns 302 and passes through the Location. This parameter takes effect only when the value of RedirectType is Mirror.

Default value: true

Parent node: Redirect

No
MirrorCheckMd5 Boolean Specifies whether OSS checks the MD5 hash on the body of the response returned by the origin.

When the value of this parameter is true and the response returned by the origin includes a Content-Md5 header, OSS checks whether the MD5 hash of the obtained data matches the header. If it is not matched, OSS does not store the data. This parameter takes effect only when the value of RedirectType is Mirror.

Default value: false

Parent node: Redirect
No
MirrorHeaders Container Specifies the headers carried in the response that is returned when you use mirroring-based back-to-origin. This parameter takes effect only when the value of RedirectType is Mirror.

Parent node: Redirect

No
PassAll Boolean Specifies whether OSS passes through all request headers (except for reserved headers and headers that start with oss-, x-oss-, and x-drs-) to the origin. This parameter takes effect only when the value of RedirectType is Mirror.

Default value: false

Parent node: MirrorHeaders

No
Pass String Specifies the headers to pass through to the origin. A maximum of 10 headers can be specified. The header can be a maximum of 1,024 bytes in length. The parameter can contain only letters, digits, and hyphens (-). This parameter takes effect only when the value of RedirectType is Mirror.

Parent node: MirrorHeaders

No
Remove String Specifies the headers that are not allowed to be passed through to the origin. A maximum of 10 headers can be specified, including repeated headers. This parameter is used together with PassAll. The header can be a maximum of 1,024 bytes in length. The character set of this parameter is the same as that of Pass. This parameter takes effect only when the value of RedirectType is Mirror.

Parent node: MirrorHeaders

No
Set Container Specifies the headers that are sent to the origin. The specified headers are configured in the data returned by the origin regardless of whether they are carried in the request. A maximum of 10 containers can be specified. This parameter takes effect only when the value of RedirectType is Mirror.

Parent node: MirrorHeaders

No
Key String Specifies the key of the header. The key can be a maximum of 1,024 bytes in length. The character set of this parameter is the same as that of Pass. This parameter takes effect only when the value of RedirectType is Mirror.

Parent node: Set

Conditional. This parameter must be specified if its parent node Set is specified.
Value String Specifies the value of the header. The value can be a maximum of 1,024 bytes in length and cannot contain \r\n. This parameter takes effect only when the value of RedirectType is Mirror.

Parent node: Set

Conditional. This parameter must be specified if its parent node Set is specified.
Protocol String The protocol used for redirection. For example, if you access the object test, and Protocol is set to https, and Hostname is set to www.test.com, the Location header is https://www.test.com/test. This parameter takes effect only when the value of RedirectType is External or AliCDN.

Valid values: http and https.

Parent node: Redirect

Conditional. This parameter must be specified if the value of RedirectType is External or AliCDN.
HostName String The domain name used for redirection. It must comply with the naming conventions for domain names. For example, if you access the test object, Protocol is set to https, and Hostname is set to www.test.com, the Location header is https://www.test.com/test.

Parent node: Redirect

Conditional. This parameter must be specified if the value of RedirectType is External or AliCDN.
HttpRedirectCode HTTP status code The HTTP redirect code in the response. This parameter takes effect only when the value of RedirectType is External or AliCDN.

Valid values: 301, 302, and 307.

Parent node: Redirect

Conditional. This parameter must be specified if the value of RedirectType is External or AliCDN.
ReplaceKeyPrefixWith String Specifies the string to replace the prefix of the object name in the redirect request. If the prefix of the object is empty, this string is added before the object name.
Note Only ReplaceKeyWith or ReplaceKeyPrefixWith is allowed.

If KeyPrefixEquals is set to abc/ and ReplaceKeyPrefixWith is set to def/, and you access the abc/test.txt object, the Location header is http://www.test.com/def/test.txt.

Parent node: Redirect

No
ReplaceKeyWith String Specifies the string to replace the requested object name in redirections. This parameter can be a variable. The ${key} variable that indicates the object name in the request is supported.
Note Only ReplaceKeyWith or ReplaceKeyPrefixWith is allowed.

If ReplaceKeyWith is set to prefix/${key}.suffix. If you access the object test, the Location header is http://www.test.com/prefix/test.suffix.

Parent node: Redirect

No
KeySuffixEquals String Specifies that only objects whose names contain the specified suffix match the rule.

The default value is null, indicating that no suffix is specified.

Parent node: Condition

No
EnableReplacePrefix Boolean If this parameter is set to true, the prefix of object names is replaced with the value specified by ReplaceKeyPrefixWith. If this parameter is not specified or empty, the prefix of object names is truncated.
Note When the ReplaceKeyWith parameter is not empty, this parameter cannot be set to true.

Default value: false

Parent node: Redirect

No

Examples

  • Sample requests
    PUT /? website HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Content-Length: 209
    Date: Fri, 04 May 2012 03:21:12 GMT
    Authorization: OSS qn6qrrqx******k53otfjbyc:KU5h8YM******0dXqf3JxrTZHiA=
    
    <? xml version="1.0" encoding="UTF-8"? >
    <WebsiteConfiguration>
      <IndexDocument>
        <Suffix>index.html</Suffix>
          <SupportSubDir>true</SupportSubDir>
          <Type>0</Type>
      </IndexDocument>
      <ErrorDocument>
        <Key>error.html</Key>
      </ErrorDocument>
    </WebsiteConfiguration>
  • Sample response
    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906008B
    Date: Fri, 04 May 2012 03:21:12 GMT
    Content-Length: 0
    Connection: keep-alive
    Server: AliyunOSS
  • Complete sample code
    PUT /? website HTTP/1.1
    Date: Fri, 27 Jul 2018 09:03:18 GMT
    Content-Length: 2064
    Host: test.oss-cn-hangzhou-internal.aliyuncs.com
    Authorization: OSS a1nBN******QMf8u:sNKIHT6ci/z231yIT5vYnetDLu4=
    User-Agent: aliyun-sdk-python-test/0.4.0
    
    <WebsiteConfiguration>
      <IndexDocument>
        <Suffix>index.html</Suffix>
        <SupportSubDir>true</SupportSubDir>
        <Type>0</Type>
      </IndexDocument>
      <ErrorDocument>
        <Key>error.html</Key>
      </ErrorDocument>
      <RoutingRules>
        <RoutingRule>
          <RuleNumber>1</RuleNumber>
          <Condition>
            <KeyPrefixEquals>abc/</KeyPrefixEquals>
            <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
          </Condition>
          <Redirect>
            <RedirectType>Mirror</RedirectType>
            <PassQueryString>true</PassQueryString>
            <MirrorURL>http://www.test.com/</MirrorURL>
            <MirrorPassQueryString>true</MirrorPassQueryString>
            <MirrorFollowRedirect>true</MirrorFollowRedirect>
            <MirrorCheckMd5>false</MirrorCheckMd5>
            <MirrorHeaders>
              <PassAll>true</PassAll>
              <Pass>myheader-key1</Pass>
              <Pass>myheader-key2</Pass>
              <Remove>myheader-key3</Remove>
              <Remove>myheader-key4</Remove>
              <Set>
                <Key>myheader-key5</Key>
                <Value>myheader-value5</Value>
              </Set>
            </MirrorHeaders>
          </Redirect>
        </RoutingRule>
        <RoutingRule>
          <RuleNumber>2</RuleNumber>
          <Condition>
            <KeyPrefixEquals>abc/</KeyPrefixEquals>
            <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
            <IncludeHeader>
              <Key>host</Key>
              <Equals>test.oss-cn-beijing-internal.aliyuncs.com</Equals>
            </IncludeHeader>
          </Condition>
          <Redirect>
            <RedirectType>AliCDN</RedirectType>
            <Protocol>http</Protocol>
            <HostName>www.test.com</HostName>
            <PassQueryString>false</PassQueryString>
            <ReplaceKeyWith>prefix/${key}.suffix</ReplaceKeyWith>
            <HttpRedirectCode>301</HttpRedirectCode>
          </Redirect>
        </RoutingRule>
      </RoutingRules>
    </WebsiteConfiguration>
    
    HTTP/1.1 200 OK
    Server: AliyunOSS
    Date: Fri, 27 Jul 2018 09:03:18 GMT
    Content-Length: 0
    Connection: keep-alive
    x-oss-request-id: 5B5ADFD6ED3CC49176CBE29D
    x-oss-server-time: 47

SDK

Error codes

Error code HTTP status code Description
InvalidDigest 400 The error message returned because the Content-MD5 header value of the message body is different from the Content-MD5 header value in the request header.