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. OSS 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 a custom domain name.
  • When setting a bucket to the static website hosting mode, you must specify the index page. The error page is optional. The specified index document and error document 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 main functions:

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

The following code provides an example of the website field:

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

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 elements

Element Type Description Required
WebsiteConfiguration Container Specifies the root node.

Parent node: none

Yes
IndexDocument Container Specifies 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 Specifies the default homepage.

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

Parent node: IndexDocument

Conditional. This element must be specified if its parent node IndexDocument is specified.
ErrorDocument Container Specifies 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 Specifies the default 404 page.

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

Parent node: ErrorDocument

Conditional. This element must be specified if its parent node ErrorDocument is specified.
RoutingRules Container Specifies 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 routing 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.

Assume that 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 element takes effect only when SupportSubDir is set to true. It takes effect after RoutingRule and before ErrorFile.

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

  • 0: checks whether abc/index.html (in object + slash (/) + homepage format) exists .If it exists, OSS returns 302 and the Location header /abc/ (in 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 error message 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 Specifies the sequence number used to match and execute routing rules. Routing rules are matched based on this sequence number. If a match succeeds, the rule is executed and the subsequent rules are not executed.

Parent node: RoutingRule

Conditional. This element 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, that is, a request must meet all the conditions to be considered a match.

Parent node: RoutingRule

Conditional. This element 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 routing rule is the mirroring-based back-to-origin rule, the element 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 element 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 element 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 element must be specified if its parent node RoutingRule is specified.
RedirectType String Specifies the redirecting type. Valid values:
  • Mirror: back-to-origin
  • External: external redirection. OSS returns a 3xx request to redirect the access 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 redirection. Unlike the External type, OSS adds an additional header to the request. After identifying the header, CDN redirects the access to the specified IP address and returns the obtained data instead of the 3xx redirecting request to the user.

Parent node: Redirect

Conditional. This element 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 element is set to true, this parameter is added to the Location header when the rule is 302 redirection. 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 parameter "a=b&c=d" 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 element takes effect only when the value of RedirectType is Mirror.

URLs start with http:// or https:// must end with a forward slash (/). OSS adds the object 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 element must be specified if RedirectType is set to Mirror.
MirrorPassQueryString Boolean This element plays the same role as PassQueryString and has a higher priority than PassQueryString. However, this element take effects 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 status code when receiving 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 element 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 checksum on the body of the response returned by the origin.

When the value of this element is true and the response returned by the origin includes a Content-Md5 header, OSS checks whether the MD5 checksum of the obtained data matches the header. If it is not matched, OSS does not store the data. This element 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 element 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 element 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 element can contain only letters, digits, and hyphens (-). This element 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 element is used together with PassAll. The header can be a maximum of 1,024 bytes in length. The character set of this element is the same as that of Pass. This element 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 element 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 element is the same as that of Pass. This element takes effect only when the value of RedirectType is Mirror.

Parent node: Set

Conditional. This element 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 element takes effect only when the value of RedirectType is Mirror.

Parent node: Set

Conditional. This element must be specified if its parent node Set is specified.
Protocol String Specifies 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 element takes effect only when the value of RedirectType is External or AliCDN.

Valid values: http and https.

Parent node: Redirect

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

Parent node: Redirect

Conditional. This element must be specified if the value of RedirectType is External or AliCDN.
HttpRedirectCode HTTP status code Specifies the returned status code in redirections. This element takes effect only when the value of RedirectType is External or AliCDN.

Valid values: 301, 302, and 307.

Parent node: Redirect

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

Assume that KeyPrefixEquals is set to abc/and ReplaceKeyPrefixWith is set to def/. If you access the object abc/test.txt, the Location header is http://www.test.com/def/test.txt. This element takes effect only when the value of RedirectType is External or AliCDN.

Parent node: Redirect

Conditional. This element must be specified if the value of RedirectType is Internal, External, or AliCDN.
ReplaceKeyWith String Specifies the string to replace the requested object name in redirections. This element can be a variable. The ${key} variable that indicates the object name in the request is supported.
Note Only ReplaceKeyWith or ReplaceKeyPrefixWith is allowed.

Assume that ReplaceKeyWith is set to prefix/${key}.suffix. If you access the object test, the Location header is http://www.test.com/prefix/test.suffix. This element takes effect only when the value of RedirectType is External or AliCDN.

Parent node: Redirect

Conditional. This element must be specified if the value of RedirectType is Internal, External, or AliCDN.

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 responses
    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
  • Example
    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

SDKs

Error codes

Error code HTTP status code Description
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.