全部產品
Search
文件中心

:GetBucketWebsite

更新時間:Jun 19, 2024

調用GetBucketWebsite介面查看儲存空間(Bucket)的靜態網站託管狀態以及跳轉規則。

請求文法

GET /?website HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

要求標頭

此介面僅涉及公用要求標頭。更多資訊,請參見公用要求標頭(Common Request Headers)

回應標頭

此介面僅涉及公用回應標頭。更多資訊,請參見公用回應標頭(Common Response Headers)

響應元素

  • WebsiteConfiguration的內容

    名稱

    類型

    樣本值

    描述

    WebsiteConfiguration

    容器

    不涉及

    根節點。

    父節點:無

  • IndexDocument的內容

    名稱

    類型

    樣本值

    描述

    IndexDocument

    容器

    不涉及

    預設首頁的容器。

    父節點:WebsiteConfiguration

    Suffix

    字串

    index.html

    預設首頁。

    父節點:IndexDocument

  • ErrorDocument的內容

    名稱

    類型

    樣本值

    描述

    ErrorDocument

    容器

    不涉及

    錯誤頁面的容器。

    父節點:WebsiteConfiguration

    Key

    字串

    error.html

    錯誤頁面。

    父節點:ErrorDocument

    HttpStatus

    字串

    404

    返回錯誤頁面時的HTTP狀態代碼。

    父節點:ErrorDocument

  • RoutingRules|RoutingRule|RuleNumber的內容

    名稱

    類型

    樣本值

    描述

    RoutingRules

    容器

    不涉及

    RoutingRule的容器。

    父節點:WebsiteConfiguration

    RoutingRule

    容器

    不涉及

    跳轉規則或者鏡像回源規則。

    父節點:RoutingRules

    RuleNumber

    正整數

    1

    匹配並執行跳轉規則或者鏡像回源規則的序號。

    按照此序號順序進行規則匹配,如果匹配成功,則執行此規則,且後續的規則不再執行。

    父節點:RoutingRule

  • RoutingRules|RoutingRule|Condition的內容

    名稱

    類型

    樣本值

    描述

    Condition

    容器

    不涉及

    匹配的條件,需滿足所有指定的項才執行此規則。

    父節點:RoutingRule

    KeyPrefixEquals

    字串

    abc

    只有匹配此首碼的Object才能匹配此規則。

    父節點:Condition

    HttpErrorCodeReturnedEquals

    HTTP狀態代碼

    404

    訪問指定Object時返回此狀態代碼才能匹配此規則。當跳轉規則是鏡像回源類型時,此欄位必須為404。

    父節點:Condition

    IncludeHeader

    容器

    不涉及

    只有請求中包含了指定Header且值為指定值時,才能匹配此規則。此容器可以最多重複5個。

    父節點:IncludeHeader

    Key

    字串

    host

    只有請求中包含了此頭且值為Equals指定值時,才能匹配此規則。

    父節點:IncludeHeader

    Equals

    字串

    test.oss-cn-beijing-internal.aliyuncs.com

    只有請求中包含了Key指定的頭且值為指定的值時,才能匹配此規則。

    父節點:IncludeHeader

  • RoutingRules|RoutingRule|Redirect的內容

    名稱

    類型

    樣本值

    描述

    Redirect

    容器

    不涉及

    指定匹配此規則後執行的動作。

    父節點:RoutingRule

    RedirectType

    字串

    Mirror

    跳轉類型。

    • Mirror:鏡像回源。

    • External:外部跳轉,即OSS會返回一個3xx請求,指定跳轉到另外一個地址。

    • AliCDN:阿里雲CDN跳轉,主要用於阿里雲的CDN。與External不同的是,OSS會額外添加一個Header。阿里雲CDN識別到此Header後會主動跳轉到指定的地址,返回給使用者擷取到的資料,而不是將3xx跳轉請求返回給使用者。

    父節點:Redirect

    PassQueryString

    布爾值

    false

    執行跳轉或者鏡像回源時,是否要攜帶發起請求的請求參數。

    當使用者請求OSS時攜帶了請求參數”?a=b&c=d”且此項設定為true,如果規則是302跳轉,則在跳轉的Location頭中會添加此請求參數。例如請求時攜帶了”Location:example.com?a=b&c=d”,跳轉類型是鏡像回源,則在發起的回源請求中也會攜帶此請求參數。

    預設值:false

    父節點:Redirect

    MirrorURL

    字串

    http://example.com

    鏡像回源的來源站點地址。只有當RedirectType為Mirror時才生效。

    來源站點地址必須以http://https://開頭,且以正斜線(/)結尾,OSS會在此地址後帶上Object組成回源URL。

    例如要訪問的Object名稱為myobject,如果指定此項為http://example.com/,則回源URL為http://example.com/myobject,如果指定此項為http://example.com/dir1/,則回源URL為http://example.com/dir1/myobject

    父節點:Redirect

    MirrorPassQueryString

    布爾值

    false

    與PassQueryString作用相同,優先順序比PassQueryString高。只有當RedirectType為Mirror時才生效。

    預設值:false

    父節點:Redirect

    MirrorFollowRedirect

    布爾值

    true

    如果鏡像回源擷取的結果為3xx,是否要繼續跳轉到指定的Location擷取資料。只有當RedirectType為Mirror時才生效。

    例如發起鏡像回源請求時,來源站點返回了302,並且指定了Location。

    • true:OSS會繼續請求Location對應的地址。

      最多能跳轉10次,如果跳轉超過10次,則報錯。

    • false:OSS返回302,並透傳Location。

    預設值:true

    父節點:Redirect

    MirrorCheckMd5

    布爾值

    false

    是否要檢查回源主體的MD5。只有當RedirectType為Mirror時才生效。

    當設定此項為true且來源站點返回的response中含有Content-MD5頭時,OSS會檢查拉取的資料MD5是否與此頭匹配,如果不匹配,則不儲存在OSS上。

    預設值:false

    父節點:Redirect

    MirrorHeaders

    容器

    不涉及

    用於指定鏡像回源時攜帶的頭。只有當RedirectType為Mirror時才生效。

    父節點:Redirect

    PassAll

    布爾值

    true

    是否透傳請求中所有的Header(除了保留的幾個Header以及以oss-/x-oss-/x-drs-開頭的Header)到來源站點。只有當RedirectType為Mirror時才生效。

    預設值:false

    父節點:MirrorHeaders

    Pass

    字串

    myheader-key1

    透傳指定的Header到來源站點。只有當RedirectType為Mirror時才生效。

    每個Header長度最多為1024個位元組,字元集為0~9、A~Z、a~z以及短劃線(-)。

    此欄位最多可指定10個。

    父節點:MirrorHeaders

    Remove

    字串

    myheader-key3

    禁止透傳指定的Header到來源站點,此欄位可以重複,最多10個,一般與PassAll一起使用。每個Header長度最多1024個位元組,字元集與Pass相同。只有當RedirectType為Mirror時才生效。

    父節點:MirrorHeaders

    Set

    容器

    不涉及

    設定一個Header傳到來源站點,不管請求中是否攜帶這些指定的Header,回源時都會設定這些Header。該容器可以重複,最多10組。只有當RedirectType為Mirror時才生效。

    父節點:MirrorHeaders

    Key

    字串

    myheader-key5

    設定Header的key,最多1024個位元組,字元集與Pass相同。只有當RedirectType為Mirror時才生效。

    父節點:Set

    Value

    字串

    myheader-value5

    設定Header的value,最多1024個位元組,且不能出現”\r\n” 。只有當RedirectType為Mirror時才生效。

    父節點:Set

    Protocol

    字串

    http

    跳轉協議。只有當RedirectType為External或AliCDN時才生效。

    例如訪問的檔案為test,設定跳轉到example.com,且設定Protocol為https,則Location的頭為https://example.com/test

    取值:httphttps

    父節點:Redirect

    HostName

    字串

    example.com

    跳轉時的網域名稱,網域名稱需符合網域名稱規範。只有當RedirectType為External或AliCDN時才生效。

    例如訪問的Object為test,Protocol為https,Hostname指定為example.com,則Location的頭為https://example.com/test

    父節點:Redirect

    HttpRedirectCode

    HTTP狀態代碼

    301

    跳轉時返回的狀態代碼。只有當RedirectType為External或者AliCDN時才生效。

    取值:301、302、307

    父節點:Redirect

    ReplaceKeyPrefixWith

    字串

    def/

    執行Redirect時檔案名稱首碼將替換成此值。只有當RedirectType為External或者AliCDN時才生效。

    例如ReplaceKeyPrefixWith指定為def/,訪問的檔案名稱為abc/test.txt,根據KeyPrefixEquals是否為空白,Location頭變化如下:

    • 當KeyPrefixEquals指定為abc/,則Location的頭為http://example.com/def/test.txt

    • 當KeyPrefixEquals指定為空白,則Location的頭為http://example.com/def/abc/test.txt

    父節點:Redirect

    ReplaceKeyWith

    字串

    prefix/${key}.suffix

    執行Redirect時檔案名稱將替換成此值。只有當RedirectType為External或者AliCDN時才生效。

    此參數支援變數${key},${key}表示該請求中的檔案名稱。例如ReplaceKeyWith為prefix/${key}.suffix,訪問的檔案名稱為test,則Location的頭為http://example.com/prefix/test.suffix

    父節點:Redirect

樣本

請求樣本

Get /?website HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com   
Date: Thu, 13 Sep 2012 07:51:28 GMT
Authorization: OSS qn6q**************:77Dv****************            

返回樣本

  • 已設定靜態網站規則返回樣本

    HTTP/1.1 200
    x-oss-request-id: 534B371674E88A4D8906008B
    Date: Thu, 13 Sep 2012 07:51:28 GMT
    Connection: keep-alive
    Content-Length: 218  
    Server: AliyunOSS
    
    <?xml version="1.0" encoding="UTF-8"?>
    <WebsiteConfiguration xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <IndexDocument>
    <Suffix>index.html</Suffix>
        </IndexDocument>
        <ErrorDocument>
           <Key>error.html</Key>
           <HttpStatus>404</HttpStatus>
        </ErrorDocument>
    </WebsiteConfiguration>
  • 未設定靜態網站規則的返回樣本

    HTTP/1.1 404 
    x-oss-request-id: 534B371674E88A4D8906008B
    Date: Thu, 13 Sep 2012 07:56:46 GMT
    Connection: keep-alive
    Content-Length: 308  
    Server: AliyunOSS
    
    <?xml version="1.0" encoding="UTF-8"?>
    <Error xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
        <Code>NoSuchWebsiteConfiguration</Code>
        <Message>The specified bucket does not have a website configuration.</Message>
        <BucketName>oss-example</BucketName>
        <RequestId>505191BEC4689A033D00236F</RequestId>
        <HostId>oss-example.oss-cn-hangzhou.aliyuncs.com</HostId>
    </Error>

完整返回樣本

GET /?website HTTP/1.1
Date: Fri, 27 Jul 2018 09:07:41 GMT
Host: test.oss-cn-hangzhou-internal.aliyuncs.com
Authorization: OSS qn6q**************:77Dv****************
User-Agent: aliyun-sdk-python-test/0.4.0


<?xml version="1.0" encoding="UTF-8"?>
<WebsiteConfiguration>
  <IndexDocument>
    <Suffix>index.html</Suffix>
  </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>
        <IncludeHeader>
          <Key>host</Key>
          <Equals>test.oss-cn-beijing-internal.aliyuncs.com</Equals>
        </IncludeHeader>
        <KeyPrefixEquals>abc/</KeyPrefixEquals>
        <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
      </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>
  </RoutingRules>
</WebsiteConfiguration>

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Fri, 27 Jul 2018 09:07:41 GMT
Content-Type: application/xml
Content-Length: 2102
Connection: keep-alive
x-oss-request-id: 5B5AE0DD2F7938C45FCED4BA
x-oss-server-time: 47

SDK

此介面所對應的各語言SDK如下:

錯誤碼

錯誤碼

HTTP狀態代碼

描述

NoSuchBucket

404

目標Bucket不存在。

AccessDenied

403

沒有相應的操作許可權。只有Bucket的擁有者才可以查看Bucket的靜態網站託管狀態。

NoSuchWebsiteConfiguration

404

目標Bucket未設定靜態網站託管功能。