PutBucketWebsite_关于Bucket的操作_API 参考_对象存储 OSS_阿里云技术文档

PutBucketWebsite接口用于将一个bucket设置成静态网站托管模式，以及设置跳转规则。

说明

静态网站是指所有的网页都由静态内容构成，包括客户端执行的脚本，例如JavaScript。OSS不支持需要服务器端处理的内容，例如PHP，JSP，APS.NET等。
如果您想使用自己的域名来访问基于bucket的静态网站，可以通过域名CNAME来实现。具体配置方法请参见绑定自定义域名。
用户将一个bucket设置成静态网站托管模式时，必须指定索引页面，错误页面则是可选的。指定的索引页面和错误页面是该bucket内的某个object。
将一个bucket设置成静态网站托管模式后，对静态网站根域名的匿名访问，OSS将返回索引页面；对静态网站根域名的签名访问，OSS将返回Get Bucket的结果。

website

website接口主要有两个功能：

设置默认主页和默认404页。
设置RoutingRule。RoutingRule用来指定3xx跳转规则以及镜像回源规则。

说明镜像回源支持公共云、金融云。

website字段样例：

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

请求语法

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）


名称	类型	描述	是否必须
WebsiteConfiguration	容器	根节点父节点：无	是
IndexDocument	容器	默认主页的容器父节点：WebsiteConfiguration	有条件，IndexDocument、ErrorDocument、RoutingRules三个容器至少指定一个。
Suffix	字符串	默认主页如果设置，则访问以正斜线（/）结尾的object时都会返回此默认主页。父节点：IndexDocument	有条件，父节点IndexDocument指定时必须指定。
ErrorDocument	容器	404页面的容器父节点：WebsiteConfiguration	有条件，IndexDocument、ErrorDocument、RoutingRules三个容器至少指定一个。
Key	容器	404页面如果指定，则访问的object不存在时则返回此404页面。父节点：ErrorDocument	有条件，父节点ErrorDocument指定时必须指定。
RoutingRules	容器	RoutingRule的容器父节点：WebsiteConfiguration	有条件，IndexDocument、ErrorDocument、RoutingRules三个容器至少指定一个。
RoutingRule	容器	指定跳转规则或者镜像回源规则，最多指定5个RoutingRule。父节点：RoutingRules	否
SupportSubDir	字符串	表示是否支持访问子目录时转到子目录下的默认主页。 false表示不转到子目录下的默认主页，而是转到根目录下的默认主页。true则表示转到子目录下的默认主页。假设访问bucket.oss-cn-hangzhou.aliyuncs.com/subdir/时，默认主页设置为index.html，则false表示转到bucket.oss-cn-hangzhou.aliyuncs.com/index.html，true表示转到bucket.oss-cn-hangzhou.aliyuncs.com/subdir/index.html。默认值：false 父节点：IndexDocument	否
Type	Http状态码	表示设置了默认主页后，访问以非正斜线（/）结尾的object，且该object不存在时的行为。说明只有在SupportSubDir为true时生效，且生效的顺序为RoutingRule之后，ErrorFile之前。假设默认主页设置为index.html，访问的文件路径是bucket.oss-cn-hangzhou.aliyuncs.com/abc，且abc这个object不存在，则type三种取值类型对应的行为如下： 0：检查abc/index.html是否存在（即`object + 正斜线（/）+ 主页`的形式），如果存在则返回302，Location头为`/abc/`的url编码（即`正斜线（/） + object + 正斜线（/）`的形式），如果不存在则返回404，继续检查ErrorFile。 1：直接返回404，报错NoSuchKey，继续检查ErrorFile。 2：检查abc/index.html是否存在，如果存在则返回该object的内容；如果不存在则返回404，继续检查ErrorFile。默认值：0 父节点：IndexDocument	否
RuleNumber	正整数	匹配和执行RoutingRule的序号，匹配时会按照此序号按顺序匹配规则。如果匹配成功，则执行此规则，后续的规则不再执行。父节点：RoutingRule	有条件，父节点RoutingRule指定时必须指定。
Condition	容器	匹配的条件如果指定的项都满足，则执行此规则。此容器下的各个节点关系是与，即需要所有条件都满足才算匹配。父节点：RoutingRule	有条件，父节点RoutingRule指定时必须指定。
KeyPrefixEquals	字符串	只有匹配此前缀的object才能匹配此规则。父节点：Condition	否
HttpErrorCodeReturnedEquals	HTTP状态码	访问指定object时返回此status才能匹配此规则。当跳转规则是镜像回源类型时，此字段必须为404。父节点：Condition	否
IncludeHeader	容器	只有请求中包含了指定header，且值为指定值时，才能匹配此规则。此容器可以最多重复5个。父节点：Condition	否
Key	字符串	只有请求中包含了此header，且值为Equals指定值时，才能匹配此规则。父节点：IncludeHeader	有条件，父节点IncludeHeader指定时必须指定。
Equals	字符串	只有请求中包含了Key指定的header，且值为指定的值时，才能匹配此规则。父节点：IncludeHeader	有条件，父节点IncludeHeader指定时必须指定。
Redirect	容器	指定匹配此规则后执行的动作。父节点：RoutingRule	有条件，父节点RoutingRule指定时必须指定。
RedirectType	字符串	指定跳转的类型，取值必须为以下几项。 Mirror（镜像回源） External（外部跳转，即OSS会返回一个3xx请求，指定跳转到另外一个地址。） Internal（内部跳转，即OSS会根据此规则将访问的object1转换成另外一个object2，相当于用户访问的是object2。） AliCDN（阿里云CDN跳转，主要用于阿里云的CDN。与External不同的是，OSS会额外添加一个header。阿里云CDN识别到此header后会主动跳转到指定的地址，返回给用户获取到的数据，而不是将3xx跳转请求返回给客户。）父节点：Redirect	有条件，父节点Redirect指定时必须指定
PassQueryString	bool型	执行跳转或者镜像回源时，是否要携带发起请求的请求参数。用户请求OSS时携带了请求参数”?a=b&c=d”，并且此项设置为true，那么如果规则是302跳转，则在跳转的Location头中会添加此请求参数。例如”Location:www.test.com?a=b&c=d”，跳转类型是镜像回源，则在发起的回源请求中也会携带此请求参数。默认值：false 取值：true或false 父节点：Redirect	否
MirrorURL	字符串	只有在RedirectType为Mirror时有意义，表示镜像回源的源站地址。假设以http://或者https://开头，必须以正斜线（/）结尾，OSS会在此字符串的基础上加上object构成回源的url。例如指定为`http://www.test.com/`，访问的object名称是myobject，则回源的url为`http://www.test.com/myobject`，如果指定为`http://www.test.com/dir1/`，那么回源的url为`http://www.test.com/dir1/myobject`。父节点：Redirect	有条件，如果RedirectType为Mirror则必须指定
MirrorPassQueryString	bool型	与PassQueryString作用相同，优先级比PassQueryString高，但只有在RedirectType为Mirror时生效。默认值：false 父节点：Redirect	否
MirrorFollowRedirect	bool型	如果镜像回源获取的结果是3xx，是否要继续跳转到指定的Location获取数据。例如发起镜像回源请求时，如果源站返回了302，并且指定了Location。如果此项为true，则oss会继续请求Location指定的地址（最多跳转10次，如果超过10次，则返回镜像回源失败）。如果为false，那么OSS就会返回302，并将Location透传出去。只有在RedirectType为Mirror时生效。默认值：true 父节点：Redirect	否
MirrorCheckMd5	bool型	是否要检查回源body的md5。当此项为true且源站返回的response中含有Content-Md5头时，OSS检查拉取的数据md5是否与此header匹配，如果不匹配，则不保存在oss上。只有在RedirectType为Mirror时生效。默认值：false 父节点：Redirect	否
MirrorHeaders	容器	用于指定镜像回源时携带的header。只有在RedirectType为Mirror时生效。父节点：Redirect	否
PassAll	bool型	是否透传请求中所有的header（除了保留的几个header以及以oss-/x-oss-/x-drs-开头的header）到源站。只有在RedirectType为Mirror时生效。默认值：false 父节点：MirrorHeaders	否
Pass	字符串	透传指定的header到源站，最多10个，每个header长度最多1024个字节，字符集为0-9、A-Z、a-z以及横杠。只有在RedirectType为Mirror时生效。父节点：MirrorHeaders	否
Remove	字符串	禁止透传指定的header到源站，这个字段可以重复，最多10个，一般与PassAll一起使用。每个header长度最多1024个字节，字符集与Pass相同。只有在RedirectType为Mirror时生效。父节点：MirrorHeaders	否
Set	容器	设置一个header传到源站，不管请求中是否携带这些指定的header，回源时都会设置这些header。该容器可以重复，最多10组。只有在RedirectType为Mirror时生效。父节点：MirrorHeaders	否
Key	字符串	设置header的key，最多1024个字节，字符集与Pass相同。只有在RedirectType为Mirror时生效。父节点：Set	有条件，当父节点Set指定时必须指定
Value	字符串	设置header的value，最多1024个字节，不能出现”\r\n” 。只有在RedirectType为Mirror时生效。父节点：Set	有条件，当父节点Set指定时必须指定。
Protocol	字符串	跳转时的协议。假设访问的文件为test，设定跳转到`www.test.com`，而且Protocol字段为https，那么Location头为`https://www.test.com/test`。只有在RedirectType为External或者AliCDN时生效。取值：http或https。父节点：Redirect	有条件，当RedirectType 为External或者AliCDN时需要指定。
HostName	字符串	跳转时的域名，需要符合域名规范。例如访问的object为test，Protocol为https，Hostname指定为`www.test.com`，那么Location头为`https://www.test.com/test`。只有在RedirectType为External或者AliCDN时生效。父节点：Redirect	有条件，当RedirectType 为External或者AliCDN时需要指定。
HttpRedirectCode	HTTP状态码	跳转时返回的状态码。只有在RedirectType为External或者AliCDN时生效。取值：301、302或307。父节点：Redirect	有条件，当RedirectType 为External或者AliCDN时需要指定。
ReplaceKeyPrefixWith	字符串	Redirect时object name的前缀将替换成这个值。如果前缀为空则将这个字符串插入到object name的最前面。说明仅允许存在ReplaceKeyWith或ReplaceKeyPrefixWith节点。假设指定了KeyPrefixEquals为abc/，指定了ReplaceKeyPrefixWith为def/，那么如果访问的object为abc/test.txt，Location头则为`http://www.test.com/def/test.txt`。只有在RedirectType为External或者AliCDN时生效。父节点：Redirect	有条件，当RedirectType为Internal、External或者AliCDN时需要指定。
ReplaceKeyWith	字符串	Redirect时object name将替换成这个值，可以支持变量（目前支持的变量是${key}，代表着该请求中的object name）。说明仅允许存在ReplaceKeyWith或ReplaceKeyPrefixWith节点。假设设置ReplaceKeyWith为prefix/${key}.suffix，访问的object为test，那么Location头则为`http://www.test.com/prefix/test.suffix`。只有在RedirectType为External或者AliCDN时生效。父节点：Redirect	有条件，当RedirectType为Internal、External或者AliCDN时需要指定。

示例

请求示例

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>

返回示例

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

完整示例

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

错误码


错误码	HTTP 状态码	描述
InvalidDigest	400	上传了Content-MD5请求头后，OSS会计算消息体的Content-MD5并检查一致性，如果不一致则返回此错误码。

PutBucketWebsite_关于Bucket的操作_API 参考_对象存储 OSS

PutBucketWebsite

website

请求语法

请求元素（Request Elements）

示例

SDK

错误码

版权声明

评论