PutBucketCors

Usage notes

Take note of the following items when you call PutBucketCors:

• Disabled-by-default design

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

• Overwriting mechanism

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

• Usage in applications

  When you use CORS in applications, you must call PutBucketCors to configure a CORS rule to enable CORS.

  For example, if you want to use the XMLHttpRequest function of your browser to access OSS from the domain name example.com, you must call PutBucketCORS 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 sent for a bucket, OSS reads the CORS rules configured for the bucket and checks the permission of the request. OSS matches the rules one by one. When OSS finds the first match, OSS returns a corresponding header. If no match is found, OSS does not include any CORS header in the response.

  The following conditions must be met before OSS determines that a CORS rule matches the request:

  • The origin from which the request is initiated must match the value of one AllowedOrigin element in the CORS rule.
  • The method of the request such as GET or PUT or the method corresponding to the Access-Control-Request-Method header in an OPTIONS request must match the value of one AllowedMethod element in the CORS rule.
  • Each header included in Access-Control-Request-Headers in an OPTIONS request must match the value of one AllowedHeader element in the CORS rule.

Request structure

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 included in a PutBucketCors request, 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

SDK

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