Configures cross-origin resource sharing (CORS) rules for a bucket.
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 nameexample.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 oneAllowedMethod
element in the CORS rule. - Each header that is included in
Access-Control-Request-Headers
in the OPTIONS request matches the value of oneAllowedHeader
element in the CORS rule.
- The origin from which the cross-origin request is sent matches the value of one
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
Element | Type | Required | Example | Description |
---|---|---|---|---|
CORSRule | Container | Yes | N/A | The container that stores CORS rules.
You can configure up to 10 CORS rules for a bucket. The XML message body in a request can be up to 16 KB in size. Parent nodes: CORSConfiguration |
AllowedOrigin | String | Yes | * | The origin from which you want to allow cross-origin requests. You can use multiple
elements to specify multiple allowed origins.
You can use only one asterisk (*) as the wildcard for AllowedOrigin. If you set AllowedOrigin to an asterisk (*), all cross-origin requests are allowed. Parent nodes: CORSRule |
AllowedMethod | Enumeration | Yes | GET | The cross-origin request method that is allowed. Valid values: GET, PUT, DELETE, POST,
and HEAD
Parent nodes: CORSRule |
AllowedHeader | String | No | Authorization | Specifies whether the headers specified by Access-Control-Request-Headers in the OPTIONS preflight request are allowed.
Each header specified by Notice You can use only one asterisk (*) as the wildcard for AllowedHeader. The following
characters are not supported:
Parent nodes: CORSRule |
ExposeHeader | String | No | x-oss-test | The response headers for allowed access requests from applications, such as an XMLHttpRequest
object in JavaScript.
Notice The following characters are not supported:
Parent nodes: CORSRule |
MaxAgeSeconds | Integer | No | 100 | The period of time within which the browser can cache the response for an OPTIONS
preflight request that is destined to specific resources. Unit: seconds.
You can specify only one MaxAgeSeconds element in a CORS rule. Parent nodes: CORSRule |
CORSConfiguration | Container | Yes | N/A | The container that stores the CORS rule that you want to configure for the bucket.
Parent nodes: none |
ResponseVary | Boolean | No | false | Specifies whether to return the Vary: Origin header. Default value: false. Valid values:
Notice This element is valid only when at least one CORS rule is configured.
|
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:
Error codes
Error code | HTTP status code | Description |
---|---|---|
InvalidDigest | 400 | The error message returned because the Content-MD5 value that is calculated by OSS based on the message body is different from the Content-MD5 value that is specified in the request header. |