全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

GET Bucket Website

最近更新时间:2026-11-16 10:51:00

该接口用于获取指定存储空间(Bucket)的静态网站托管规则。使用该接口的用户必须是主账号或具有ks3:GetBucketWebsite权限的用户。

请求

请求语法

GET /?website HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}

请求参数

该接口不使用请求参数。

请求头

该接口仅使用常用请求头部。

请求体

该接口不使用请求体。

相应

响应头

该接口仅返回常用响应头。

响应体

响应体为一段描述静态网站托管规则的 XML:

<WebsiteConfiguration>
    <IndexDocument>
        <Suffix>index.html</Suffix>
        <SupportSubDir>true</SupportSubDir>
    </IndexDocument>
    <ErrorDocument>
        <Key>error.html</Key>
    </ErrorDocument>
    <RoutingRules>
        <RoutingRule>
            <Condition>
                <KeyPrefixEquals>abc/</KeyPrefixEquals>
                <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
            </Condition>
            <Redirect>
                <Protocol>https</Protocol>
                <HostName>www.example.com</HostName>
                <HttpRedirectCode>302</HttpRedirectCode>
                <ReplaceKeyPrefixWith>report-404/</ReplaceKeyPrefixWith>
            </Redirect>
        </RoutingRule>
    </RoutingRules>
</WebsiteConfiguration>

返回 XML 中的参数详情如下所示:

  • WebsiteConfiguration 的内容

参数名称

描述

WebsiteConfiguration

包含静态网站托管规则的容器。

  • 类型:容器

  • 父节点:无

  • 默认首页 IndexDocument 的内容

参数名称

描述

IndexDocument

默认首页的容器。

  • 类型:容器

  • 父节点:WebsiteConfiguration

Suffix

默认首页。访问所有 /结尾的域名或访问结尾不带/的跟域名时,将返回该目录下的 Suffix 对象。例如 Suffix 设置为 index.html 后,访问 http://example.com/docment/ 时,则默认返回根目录下的 index.html 文件。

  • 类型:String

  • 父节点:IndexDocument

  • 字符长度:1~1024

Suffix仅支持填写文件名称,不支持携带斜杠。

SupportSubDir

访问子目录时,是否跳转到该子目录下的默认首页文件。取值范围如下:

  • true:跳转到该子目录下的默认首页文件。

  • false(默认):不跳转到该子目录下的默认首页文件(Suffix),而是转到根目录下的默认首页文件(Suffix)。

假设默认首页 Suffix 设置为 index.html,访问http://example.com/subdir/时,如果设置 SupportSubDir 为 false或不设置,则会跳转到http://example.com/index.html。如果设置 SupportSubDir 为 true,则会跳转到http://example.com/subdir/index.html。

  • 类型:布尔

  • 父节点:IndexDocument

  • 默认404页 ErrorDocument 的内容

参数名称

描述

ErrorDocument

404页面的容器。

  • 类型:容器。

  • 父节点:WebsiteConfiguration

Key

错误页面。指定错误页面后,如果访问(GET/HEAD)的文件不存在,则返回此错误页面。

  • 类型:String

  • 父节点:ErrorDocument

如果是Range GET请求,文件本身不存在时,会返回错误页面的完整文件。

HttpStatus

返回错误页面时返回的HTTP状态码。

  • 取值:200、404(默认)

  • 父节点:ErrorDocument

  • 重定向规则 RoutingRules 的内容

参数名称

描述

RoutingRules

RoutingRule 的容器。

  • 类型:容器

  • 父节点:WebsiteConfiguration

RoutingRule

指定跳转规则,最多指定50个RoutingRule。

  • 类型:容器

  • 父节点:RoutingRules

Condition

设置重定向规则的匹配条件。只有当设置的条件全部匹配后,才会执行具体的重定向规则(Redirect)。

  • 类型:容器

  • 父节点:RoutingRule

如果Condition内的子节点均不填写或填写值均为空,表示针对所有请求(GET/HEAD)均进行重定向规则。

KeyPrefixEquals

只有匹配此前缀的Object才会执行重定向规则。

  • 类型:String

  • 父节点:Condition

如果设置KeyPrefixEquals的同时也设置了HttpErrorCodeReturnedEquals,则两个条件同时匹配时,才会执行重定向规则。

HttpErrorCodeReturnedEquals

只有匹配此 HTTP 状态码的请求才会执行重定向规则。例如设置HttpErrorCodeReturnedEquals 为 404,表示当访问指定对象不存在时,执行重定向规则(Redirect)。

  • 取值范围:仅支持填写4XX状态码,如403或404

  • 类型:String

  • 父节点:Condition

如果设置HttpErrorCodeReturnedEquals的同时也设置了KeyPrefixEquals,则两个条件同时匹配时,才会执行重定向规则。

Redirect

设置重定向规则。

  • 类型:容器

  • 父节点:RoutingRule

Protocol

重定向请求时使用的协议,支持 http 和 https 协议。默认使用 http 协议。

  • 取值:http(默认)、https

  • 父节点:Redirect

HostName

跳转时的域名。

  • 类型:String

  • 父节点:Redirect

1. 未配置HostName时,默认继承原请求的域名。

2. HostName不能包含斜杠。

3. 假设要访问的文件为test,设置Hostname为example.com,并且设置Protocol为https,则返回的Location头为https://example.com/test。

HttpRedirectCode

跳转时返回的状态码。

  • 取值:301(默认)、302、307

  • 类型:String

  • 父节点:Redirect

ReplaceKeyPrefixWith

重定向时 Object 的前缀将替换成该值。替换方式为替换原始请求中所匹配到的前缀部分( KeyPrefixEquals)。注意ReplaceKeyPrefixWith 不能与 ReplaceKeyWith 同时设置。

  • 类型:String

  • 父节点:Redirect

1. 假如要访问的 Object 为 abc/test.txt,如果设置 KeyPrefixEquals为abc/,ReplaceKeyPrefixWith 为 def/,则 Location 头为http://example.com/def/test.txt。

2. 当 ReplaceKeyPrefixWith 和 ReplaceKeyWith 均不填写时,重定向会保留原始请求的路径(默认不带查询参数),仅更换指定域名(HostName)。

3. 如果 KeyPrefixEquals 值为空或不使用 KeyPrefixEquals 参数,则会将 ReplaceKeyPrefixWith 设置的值插入 Key 的前面,等同于添加前缀。

4. ReplaceKeyPrefixWith 支持设置值为空,为空表示删除指定前缀(keyPrefixEquals)。

ReplaceKeyWith

所有命中请求的 Object,完整的 Key 将替换成 ReplaceKeyWith 指定的值。替换方式为替换整个原始请求 Object 的 Key。注意 ReplaceKeyWith 不能与 ReplaceKeyPrefixWith 同时设置。

  • 类型:String

  • 父节点:Redirect

1. ReplaceKeyWith 支持设置变量,目前支持的变量为 ${key},表示该请求 Object 的 Key。比如要访问的 Object 为 test,如果设置 ReplaceKeyWith 设置为prefix/${key}.suffix,则返回 Location 的头为http://example.com/prefix/test.suffix。

2. 如果想把 docs 目录下所有对象的请求重定向到 documents/error.html,可以将 Condition 中的 KeyPrefixEquals 设置为 docs,Redirect 中的 ReplaceKeyWith 设置为 documents/error.html。则对于比如对象 Key 为 docs/a.html 和 docs/b.html 的文件,重定向的结果均为 documents/error.html。

3. 当 ReplaceKeyWith 和 ReplaceKeyPrefixWith 均不填写时,重定向会保留原始请求的路径(默认不带查询参数),仅更换指定域名(HostName)。

4. ReplaceKeyWith 支持设置为空,为空表示重定向的请求路径均为空(参数是否为空由 PassQueryString 控制)。

PassQueryString

执行跳转规则时,是否携带请求参数,默认不携带。

  • 取值:true、false(默认)

  • 父节点:Redirect

比如用户请求 KS3 时携带了请求参数?a=b&c=d,并且设置 PassQueryString 为 true,则跳转的 Location 头中会添加此请求参数。

示例

请求示例

GET /?website HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 01 Mar 2016 12:00:00 GMT
Authorization: authorization string

响应示例

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 312
Connection: keep-alive
Date: Wed, 16 Aug 2017 12:23:54 GMT
Server: KS3
x-kss-request-id: NTk5NDM5NWFfMjQ4OGY3Xzc3NGRf****

<WebsiteConfiguration>
    <IndexDocument>
        <Suffix>index.html</Suffix>
        <SupportSubDir>true</SupportSubDir>
    </IndexDocument>
    <ErrorDocument>
        <Key>error.html</Key>
    </ErrorDocument>
    <RoutingRules>
        <RoutingRule>
            <Condition>
                <KeyPrefixEquals>docs/</KeyPrefixEquals>
            </Condition>
            <Redirect>
                <ReplaceKeyPrefixWith>documents/</ReplaceKeyPrefixWith>
            </Redirect>
        </RoutingRule>
    </RoutingRules>
</WebsiteConfiguration>

错误码

错误码

HTTP状态码

描述

404 Not Found

NoSuchBucketWebsiteConfiguration

规则不存在。

404 Not Found

NoSuchBucket

桶不存在。

403 Forbidden

AccessDenied

缺少权限。

400 Bad Request

InvalidRequest

请求不合法。

文档导读
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈