PutBucketCors

Usage notes

• Disabled-by-default design

  By default, CORS is disabled for a bucket. All cross-origin requests are not allowed.

• Overwriting mechanism

  If you call the PutBucketCors operation to configure a new CORS rule for a bucket for which a CORS rule is already configured, the existing rule is overwritten.

• Use of CORS in applications

  Before you can use CORS in applications, you must call the PutBucketCors operation to configure a CORS rule to enable CORS.

  For example, if you want to use the XMLHttpRequest feature of your browser to access Object Storage Service (OSS) from the domain name example.com, you must call the PutBucketCors operation to configure a CORS rule that is described by an XML message body.

• CORS rule matching

  When OSS receives a cross-origin request or an OPTIONS request that is destined for a bucket, OSS reads the CORS rules that are configured for the bucket and attempts to match the rules one after another. If OSS finds the first match, OSS returns a corresponding header. If no match is found, OSS does not include CORS headers in the response.

  OSS considers that a cross-origin request or an OPTIONS request matches a CORS rule only when the request meets the following conditions:

  • The origin from which the cross-origin request is sent matches the value of one AllowedOrigin element in the CORS rule.
  • The method of the cross-origin request such as GET or PUT or the method that corresponds to the Access-Control-Request-Method header in the OPTIONS request matches the value of one AllowedMethod element in the CORS rule.
  • Each header that is included in Access-Control-Request-Headers in the OPTIONS request matches the value of one AllowedHeader element in the CORS rule.

Request syntax

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 >

Request elements

For more information about the common request headers contained in PutBucketCors requests such as Host and Authorization, see Common request headers.

Response headers

The response to a PutBucketCors request contains only common response headers. For more information, see Common response headers.

Examples

• Sample requests

  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 qn6qrrqxo2oawuk53otf****:KU5h8YMUC78M30dXqf3JxrT*****
  <?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 >

• Sample responses

  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

SDKs

You can use OSS SDKs for the following programming languages to call the PutBucketCors operation:

• Java
• Python
• PHP
• Go
• C++
• C
• .NET
• Node.js
• Ruby

Error codes