Configure static website hosting and redirection rules with put-bucket-website - Object Storage Service

Enable static website hosting and configure redirection rules for a bucket.

Prerequisites

Permissions: By default, an Alibaba Cloud account has the oss:PutBucketWebsite permission. To run this command as a RAM user or Security Token Service (STS) user, grant the oss:PutBucketWebsite permission. For more information, see Attach a custom policy to a RAM user.
Feature overview: Before enabling static website hosting, review Overview of static website hosting.

Command syntax

ossutil api put-bucket-website --bucket <value> --website-configuration <value> [flags]

Parameter	Type	Required	Description
`--bucket`	string	Yes	The name of the bucket.
`--website-configuration`	string	Yes	The website configuration. Accepts XML or JSON format. Use the `file://` prefix to load configuration from a file.

This command corresponds to the PutBucketWebsite API operation. For a full description of all parameters, see PutBucketWebsite. For supported global flags, see Global command-line options.

--website-configuration structure

The --website-configuration parameter accepts both XML and JSON formats. The top-level fields are:

Field	Description
`IndexDocument`	The default homepage. Contains `Suffix` (file name, e.g., `index.html`), `SupportSubDir` (boolean), and `Type` (string).
`ErrorDocument`	The error page returned on HTTP errors. Contains `Key` (file name) and `HttpStatus` (HTTP status code).
`RoutingRules`	An ordered list of routing rules. Each rule contains a `RuleNumber`, `Condition`, and `Redirect` block.

XML structure:

<WebsiteConfiguration>
  <IndexDocument>
    <Suffix>string</Suffix>
    <SupportSubDir>boolean</SupportSubDir>
    <Type>string</Type>
  </IndexDocument>
  <ErrorDocument>
    <Key>string</Key>
    <HttpStatus>string</HttpStatus>
  </ErrorDocument>
  <RoutingRules>
    <RoutingRule>
      <RuleNumber>integer</RuleNumber>
      <Condition>
        <KeyPrefixEquals>string</KeyPrefixEquals>
        <HttpErrorCodeReturnedEquals>integer</HttpErrorCodeReturnedEquals>
      </Condition>
      <Redirect>
        <HttpRedirectCode>integer</HttpRedirectCode>
        <RedirectType>string</RedirectType>
        <MirrorPassQueryString>boolean</MirrorPassQueryString>
        <MirrorFollowRedirect>boolean</MirrorFollowRedirect>
        <MirrorHeaders>
          <PassAll>boolean</PassAll>
          <Pass>string</Pass>
          ...
          <Remove>string</Remove>
          ...
          <Set>
            <Value>string</Value>
            <Key>string</Key>
          </Set>
          ...
        </MirrorHeaders>
        <MirrorURL>string</MirrorURL>
        <EnableReplacePrefix>boolean</EnableReplacePrefix>
        <ReplaceKeyWith>string</ReplaceKeyWith>
        <PassQueryString>boolean</PassQueryString>
        <MirrorCheckMd5>boolean</MirrorCheckMd5>
        <Protocol>string</Protocol>
        <HostName>string</HostName>
        <TransparentMirrorResponseCodes>string</TransparentMirrorResponseCodes>
        <ReplaceKeyPrefixWith>string</ReplaceKeyPrefixWith>
      </Redirect>
    </RoutingRule>
    ...
  </RoutingRules>
</WebsiteConfiguration>

JSON structure:

{
  "IndexDocument": {
    "Suffix": "string",
    "SupportSubDir": boolean,
    "Type": "string"
  },
  "ErrorDocument": {
    "Key": "string",
    "HttpStatus": "string"
  },
  "RoutingRules": {
    "RoutingRule": [
      {
        "RuleNumber": integer,
        "Condition": {
          "KeyPrefixEquals": "string",
          "HttpErrorCodeReturnedEquals": integer
        },
        "Redirect": {
          "RedirectType": "string",
          "HttpRedirectCode": integer,
          "Protocol": "string",
          "HostName": "string",
          "PassQueryString": boolean,
          "ReplaceKeyWith": "string",
          "ReplaceKeyPrefixWith": "string",
          "EnableReplacePrefix": boolean,
          "MirrorURL": "string",
          "MirrorPassQueryString": boolean,
          "MirrorFollowRedirect": boolean,
          "MirrorCheckMd5": boolean,
          "TransparentMirrorResponseCodes": "string",
          "MirrorHeaders": {
            "PassAll": boolean,
            "Pass": ["string", ...],
            "Remove": ["string", ...],
            "Set": [
              {
                "Key": "string",
                "Value": "string"
              },
              ...
            ]
          }
        }
      },
      ...
    ]
  }
}

Examples

The following examples configure static website hosting for a bucket named examplebucket.

Configuration with routing rules

The following example adds three routing rules.

Using an XML configuration file

Create website-configuration.xml:

<?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>
    <HttpStatus>404</HttpStatus>
  </ErrorDocument>
  <RoutingRules>
    <RoutingRule>
      <RuleNumber>1</RuleNumber>
      <Condition>
        <KeyPrefixEquals>abc/</KeyPrefixEquals>
        <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
      </Condition>
      <Redirect>
        <RedirectType>Mirror</RedirectType>
        <PassQueryString>true</PassQueryString>
        <MirrorURL>http://example.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>example.com</HostName>
        <PassQueryString>false</PassQueryString>
        <ReplaceKeyWith>prefix/${key}.suffix</ReplaceKeyWith>
        <HttpRedirectCode>301</HttpRedirectCode>
      </Redirect>
    </RoutingRule>
    <RoutingRule>
      <Condition>
        <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
      </Condition>
      <RuleNumber>3</RuleNumber>
      <Redirect>
        <ReplaceKeyWith>prefix/${key}</ReplaceKeyWith>
        <HttpRedirectCode>302</HttpRedirectCode>
        <EnableReplacePrefix>false</EnableReplacePrefix>
        <PassQueryString>false</PassQueryString>
        <Protocol>http</Protocol>
        <HostName>example.com</HostName>
        <RedirectType>External</RedirectType>
      </Redirect>
    </RoutingRule>
  </RoutingRules>
</WebsiteConfiguration>

Run the command:

ossutil api put-bucket-website --bucket examplebucket --website-configuration file://website-configuration.xml

Using a JSON configuration file

Create website-configuration.json:

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

Run the command:

ossutil api put-bucket-website --bucket examplebucket --website-configuration file://website-configuration.json

Passing the configuration inline

ossutil api put-bucket-website --bucket examplebucket --website-configuration "{\"IndexDocument\":{\"Suffix\":\"index.html\",\"SupportSubDir\":\"true\",\"Type\":\"0\"},\"ErrorDocument\":{\"Key\":\"error.html\",\"HttpStatus\":\"404\"},\"RoutingRules\":{\"RoutingRule\":[{\"RuleNumber\":\"1\",\"Condition\":{\"KeyPrefixEquals\":\"abc/\",\"HttpErrorCodeReturnedEquals\":\"404\"},\"Redirect\":{\"RedirectType\":\"Mirror\",\"PassQueryString\":\"true\",\"MirrorURL\":\"http://example.com/\",\"MirrorPassQueryString\":\"true\",\"MirrorFollowRedirect\":\"true\",\"MirrorCheckMd5\":\"false\",\"MirrorHeaders\":{\"PassAll\":\"true\",\"Pass\":[\"myheader-key1\",\"myheader-key2\"],\"Remove\":[\"myheader-key3\",\"myheader-key4\"],\"Set\":{\"Key\":\"myheader-key5\",\"Value\":\"myheader-value5\"}}}},{\"RuleNumber\":\"2\",\"Condition\":{\"KeyPrefixEquals\":\"abc/\",\"HttpErrorCodeReturnedEquals\":\"404\",\"IncludeHeader\":{\"Key\":\"host\",\"Equals\":\"test.oss-cn-beijing-internal.aliyuncs.com\"}},\"Redirect\":{\"RedirectType\":\"AliCDN\",\"Protocol\":\"http\",\"HostName\":\"example.com\",\"PassQueryString\":\"false\",\"ReplaceKeyWith\":\"prefix/${key}.suffix\",\"HttpRedirectCode\":\"301\"}},{\"RuleNumber\":\"3\",\"Condition\":{\"HttpErrorCodeReturnedEquals\":\"404\"},\"Redirect\":{\"ReplaceKeyWith\":\"prefix/${key}\",\"HttpRedirectCode\":\"302\",\"EnableReplacePrefix\":\"false\",\"PassQueryString\":\"false\",\"Protocol\":\"http\",\"HostName\":\"example.com\",\"RedirectType\":\"External\"}}]}}"