PUT Bucket CORS

Last updated:2021-06-15 20:56:34

Description

You can call this operation to configure CORS settings for your bucket. If the settings exist, KS3 replaces them.

To call this operation, you must have permission to perform the PutBucketCORS operation. The owner of a bucket has this permission by default and can grant it to others.

By configuring CORS settings for your bucket, you enable your bucket to respond to requests from different origins. For example, you can call this operation if you want to enable a request whose origin is http://www.example.com to access your KS3 bucket at my.example.bucket.com by using the XMLHttpRequest capability of the browser.

To enable CORS for your bucket, you must create a CORS configuration file in XML format. The file contains rules that identify the allowed origins, the supported HTTP methods for each origin, and information related to other operations. You can add up to 100 rules to a configuration file. Add the XML file as a CORS subresource to the bucket. The file cannot exceed 64 KB in size.

For example, the following CORS configuration contains two CORSRule elements, each specifying a CORS rule.

  • The first rule allows cross-origin PUT, POST, and DELETE requests from the origin https://www.example.com. The rule also uses Access-Control-Request-Headers to allow all headers in an OPTIONS preflight request. KS3 returns a requested header to OPTIONS preflight requests.
  • The second rule allows CORS requests from all origins by using the GET method. The asterisk (*) indicates all origins.
<CORSConfiguration>
<CORSRule>
<AllowedOrigin>http://www.example.com</AllowedOrigin>
<AllowedMethod>PUT</AllowedMethod>
<AllowedMethod>POST</AllowedMethod>
<AllowedMethod>DELETE</AllowedMethod>

<AllowedHeader>*</AllowedHeader>
</CORSRule>
<CORSRule>
<AllowedOrigin>*</AllowedOrigin>
<AllowedMethod>GET</AllowedMethod>
</CORSRule>
</CORSConfiguration>

You can also set optional parameters to configure CORS settings for your bucket. For example, the following CORS rule allows CORS requests sent from the origin http://www.example.com by using the PUT and POST methods.

<CORSConfiguration>
<CORSRule>
<AllowedOrigin>http://www.example.com</AllowedOrigin>
<AllowedMethod>PUT</AllowedMethod>
<AllowedMethod>POST</AllowedMethod>
<AllowedHeader>*</AllowedHeader>
<MaxAgeSeconds>3000</MaxAgeSeconds>
<ExposeHeader>x-kss-server-side-encryption</ExposeHeader>
</CORSRule>
</CORSConfiguration>

In the preceding example, the CORS rule contains the following optional parameters:

  • MaxAgeSeconds: the period of time in seconds within which the browser caches the response of KS3 for an OPTIONS preflight request to specified resources. In the preceding example, this parameter is set to 3000. By caching the response, the browser does not need to send preflight requests to KS3 if the original request needs to be repeated.
  • ExposeHeader: the response header that you are allowed to access from an application, such as from a JavaScript XMLHttpRequest object. In the preceding example, this parameter is set to x-kss-server-side-encryption.

When KS3 receives a cross-origin request for a bucket, it checks whether the request matches the configured CORS rules. For a rule to match a request, the following conditions must be met:

  • The origin header of the request must match the AllowedOrigin elements in the CORS rule.
  • The request method such as PUT, GET, and HEAD, or the Access-Control-Request-Method header header of an OPTIONS preflight request must match one of the AllowedMethod elements.
  • Each header specified in Access-Control-Request-Headers of an OPTIONS preflight request must match an AllowedHeader element.

Request

Request syntax

PUT /?cors HTTP/1.1
Host: {BucketName}.{endpoint}
Content-Length: {length}
Date: {date}
Authorization: {SignatureValue}
Content-MD5: {MD5}

<CORSConfiguration>
<CORSRule>
<AllowedOrigin>{Origin you want to allow cross-domain requests from}</AllowedOrigin>
<AllowedOrigin>...</AllowedOrigin>
...
<AllowedMethod>{HTTP method}</AllowedMethod>
<AllowedMethod>...</AllowedMethod>
...
<MaxAgeSeconds>{Time in seconds your browser to cache the pre-flight OPTIONS response for a resource}</MaxAgeSeconds>
<AllowedHeader>{Headers that you want the browser to be allowed to send}</AllowedHeader>
<AllowedHeader>...</AllowedHeader>
...
<ExposeHeader>{Headers in the response that you want accessible from client application}</ExposeHeader>
<ExposeHeader>...</ExposeHeader>
...
</CORSRule>
<CORSRule>
...
</CORSRule>
...
</CORSConfiguration>

References:

Request parameters

No request parameter is used.

Request headers

This operation uses only common request headers. For more information, see Public Request Header.

Request body

Parameter Description Required
CORSConfiguration The container that stores CORS rules. It can store up to 100 CORS rules.
Type: container
Child node: CORSRules
Parent node: none
Yes
CORSRule A collection of origins and methods. You can configure up to 100 rules.
Type: container
Child nodes: AllowedOrigin, AllowedMethod, MaxAgeSeconds, ExposeHeader, and ID
Parent node: CORSConfiguration
Yes
ID The unique identifier of a rule. An ID can contain up to 255 characters. It can help you quickly find a rule.
Type: String
Parent node: CORSRule
Yes
AllowedMethod The HTTP methods allowed for an origin. You must define at least one origin and one method in a CORS rule.
Type: Enumeration (GET, PUT, HEAD, POST, and DELETE)
Parent node: CORSRule
Yes
AllowedOrigin The origins from which CORS requests are allowed. An origin can contain at most one asterisk (*) as the wildcard. You must define at least one origin and one method in a CORS rule. Example: http://*.example.com. If you set the AllowedOrigin parameter to an asterisk (*), requests from all origins are allowed.
Type: String
Parent node: CORSRule
Yes
AllowedHeader Indicates which headers specified by Access-Control-Request-Headers in the OPTIONs preflight request are allowed. Each header specified by Access-Control-Request-Headers must be consistent with the header of the request sent to KS3. You can specify at most one asterisk (*) in the AllowedHeader parameter.
Type: String
Parent node: CORSRule
Yes
MaxAgeSeconds The period of time within which the browser caches the response of KS3 for an OPTIONS preflight request to specified resources. A CORS rule can contain at most one MaxAgeSeconds parameter.
Type: Integer (seconds)
Parent node: CORSRule
Yes
ExposeHeader The response header that you are allowed to access from your applications, such as from a JavaScript XMLHttpRequest object. Type: String
Parent node: CORSRule
Yes

Response

Response headers

This operation uses only common response headers. For more information, see Public Response Header.

Response body

No response body is returned.

Operation-specific errors

This operation does not return operation-specific errors.

Examples

Sample request

PUT /?cors HTTP/1.1
Content-MD5: /QO8JEkpekFaAuWWEKS7Fg==
Date: Thu, 15 Jun 2017 02:32:02 GMT
Authorization: authorization string
Content-Length: 652
Host: ks3-example.ks3-cn-beijing.ksyun.com


<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<CORSRule>
<AllowedMethod>GET</AllowedMethod>
<AllowedOrigin>http://baidu.com</AllowedOrigin>
<AllowedHeader>*</AllowedHeader>
</CORSRule>
<CORSRule>
<AllowedMethod>POST</AllowedMethod>
<AllowedOrigin>http://*ks3.ksyun.com</AllowedOrigin>
<AllowedOrigin>https://*ks3.console.ksyun.com</AllowedOrigin>
<AllowedOrigin>https://*ks3.ksyun.com</AllowedOrigin>
<AllowedOrigin>https://www.example.com</AllowedOrigin>
<AllowedOrigin>http://*ks3.console.ksyun.com</AllowedOrigin>
<AllowedHeader>*</AllowedHeader>
</CORSRule>
</CORSConfiguration>

Sample response

HTTP/1.1 200 OK
Server: Tengine
Date: Thu, 15 Jun 2017 02:32:56 GMT
Content-Length: 0
X-Application-Context: application
x-kss-request-id: 94def5b819f74135a1df54e6cf422f64

Did you find the above information helpful?

Unhelpful
Mostly Unhelpful
A little helpful
Helpful
Very helpful

What might be the problems?

Insufficient
Outdated
Unclear or awkward
Redundant or clumsy
Lack of context for the complex system or functionality

More suggestions

0/200

Please give us your feedback.

Submitted

Thank you for your feedback.

问题反馈