全部产品
Search

搜索本产品

    对象存储 OSS：PutBucketCors

    文档中心

    对象存储 OSS：PutBucketCors

    更新时间：Apr 28, 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并检查一致性，如果不一致则返回此错误码。