全部產品
Search
文件中心

Object Storage Service:PutBucketCors

更新時間:Jun 08, 2024

調用PutBucketCors介面為指定的儲存空間(Bucket)設定跨域資源共用CORS(Cross-Origin Resource Sharing)規則。

注意事項

  • 預設不開啟CORS

    Bucket預設不開啟CORS功能,所有跨域請求的Origin都不被允許。

  • 覆蓋語義

    PutBucketCors為覆蓋語義,即新配置的CORS規則將覆蓋已有的CORS規則。

  • 應用程式中使用CORS

    在應用程式中使用CORS功能時,需通過PutBucketCors介面手動上傳CORS規則來開啟CORS功能。

    例如從example.com通過瀏覽器的XMLHttpRequest功能來訪問OSS,需要通過本介面手動上傳CORS規則,且CORS規則需由XML文檔進行描述。

  • CORS規則匹配

    當OSS收到一個跨域請求或OPTIONS請求,會先讀取Bucket對應的CORS規則,然後進行相應的許可權檢查。OSS會依次檢查每一條規則,使用第一條匹配的規則來允許請求並返回對應的Header。如果所有規則都匹配失敗,則不附加任何CORS相關的Header。

    CORS規則匹配成功必須滿足以下三個條件:

    • 請求的Origin必須匹配一個AllowedOrigin項。

    • 請求的方法(例如GET、PUT等)或者OPTIONS請求的Access-Control-Request-Method頭對應的方法必須匹配一個AllowedMethod項。

    • OPTIONS請求的Access-Control-Request-Headers頭包含的每個header都必須匹配一個AllowedHeader項。

請求文法

PUT /?cors 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"?>
<CORSConfiguration>
    <CORSRule>
      <AllowedOrigin>the origin you want allow CORS request from</AllowedOrigin>
      <AllowedOrigin>…</AllowedOrigin>
      <AllowedMethod>HTTP method</AllowedMethod>
      <AllowedMethod>…</AllowedMethod>
        <AllowedHeader> headers that allowed browser to send</AllowedHeader>
          <AllowedHeader>…</AllowedHeader>
          <ExposeHeader> headers in response that can access from client app</ExposeHeader>
          <ExposeHeader>…</ExposeHeader>
          <MaxAgeSeconds>time to cache pre-fight response</MaxAgeSeconds>
    </CORSRule>
    <CORSRule>
      …
    </CORSRule>
…
</CORSConfiguration >

請求元素

名稱

類型

是否必選

樣本值

描述

CORSRule

容器

不涉及

CORS規則的容器。

每個Bucket最多支援配置10條CORS規則。上傳的XML文檔大小最大允許16 KB。

父節點:CORSConfiguration

AllowedOrigin

字串

*

指定允許的跨域請求來源。 OSS支援使用多個元素來指定多個允許的來源。

AllowedOrigin中只能使用一個星號(*)萬用字元。如果指定AllowedOrigin為星號(*),則表示允許所有來源的跨域請求。

父節點:CORSRule

AllowedMethod

枚舉值

GET

指定允許的跨域要求方法。取值範圍為GET、PUT、DELETE、POST、HEAD。

父節點:CORSRule

AllowedHeader

字串

Authorization

控制OPTIONS預取指令Access-Control-Request-Headers中指定的Header是否被允許。

Access-Control-Request-Headers中指定的每個Header都必須在AllowedHeader中有對應的項。

重要

AllowedHeader中只能使用一個星號(*)萬用字元,且不支援使用以下字元:

  • <

  • >

  • &

  • '

  • "

父節點:CORSRule

ExposeHeader

字串

x-oss-test

指定允許使用者從應用程式中訪問的回應標頭。例如一個JavaScript的XMLHttpRequest對象。

重要

ExposeHeader中不支援使用以下字元:

  • *

  • <

  • >

  • &

  • '

  • "

父節點:CORSRule

MaxAgeSeconds

整型

100

指定瀏覽器對特定資源的預取(OPTIONS)請求返回結果的緩衝時間。單位為秒。

單條CORS規則僅允許一個MaxAgeSeconds。

父節點:CORSRule

CORSConfiguration

容器

不涉及

Bucket的CORS規則容器。

父節點:無

ResponseVary

布爾

false

是否返回Vary: Origin頭。 取值範圍如下:

  • true:不管發送的是否是跨域請求或跨域請求是否成功,均會返回Vary: Origin頭。

  • false(預設):任何情況下均不返回Vary: Origin頭

重要

此欄位不能單獨配置,必須至少配置一項跨域規則才會生效。

此介面涉及的Host、Authorization等其他更多公用要求標頭的更多資訊,請參見公用要求標頭(Common Request Headers)

回應標頭

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

樣本

  • 請求樣本

    PUT /?cors HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Content-Length: 186
    Date: Fri, 04 May 2012 03:21:12 GMT
    Authorization: OSS qn6q**************:77Dv****************
    <?xml version="1.0" encoding="UTF-8"?>
    <CORSConfiguration>
        <CORSRule>
          <AllowedOrigin>*</AllowedOrigin>
          <AllowedMethod>PUT</AllowedMethod>
          <AllowedMethod>GET</AllowedMethod>
          <AllowedHeader>Authorization</AllowedHeader>
        </CORSRule>
        <CORSRule>
          <AllowedOrigin>http://example.com</AllowedOrigin>
          <AllowedOrigin>http://example.net</AllowedOrigin>
          <AllowedMethod>GET</AllowedMethod>
          <AllowedHeader> Authorization</AllowedHeader>
          <ExposeHeader>x-oss-test</ExposeHeader>
          <ExposeHeader>x-oss-test1</ExposeHeader>
          <MaxAgeSeconds>100</MaxAgeSeconds>
        </CORSRule>
        <ResponseVary>false</ResponseVary>
    </CORSConfiguration >
  • 返回樣本

    HTTP/1.1 200 OK
    x-oss-request-id: 50519080C4689A033D0*****
    Date: Fri, 04 May 2012 03:21:12 GMT
    Content-Length: 0
    Connection: keep-alive
    Server: AliyunOSS
    x-oss-server-time: 94

SDK

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

錯誤碼

錯誤碼

HTTP狀態代碼

描述

InvalidDigest

400

上傳了Content-MD5要求標頭後,OSS會計算訊息體的Content-MD5並檢查一致性,如果不一致則返回此錯誤碼。