文档中心
文档中心 >
下载PDF文档

PUT Bucket CORS

描述

设置用户 bucket (空间)的 cors （跨源资源共享）。如果配置已存在，那么KS3将会替换它。

使用此接口，你需要拥有执行 PutBucketCORS 操作的权限。空间拥有者默认具有此权限，并且可以授予他人相应权限。

用户通过设置此配置，可以实现指定空间响应来自不同源的请求。例如，你也许想要从一个源 http://www.example.com 以 XMLHttpRequest 的方式请求你在KS3的某个空间 my.example.bucket.com，可以通过此操作实现。

要将您的存储段配置为允许跨源请求，您可以创建一个 CORS 配置，即一个 XML 文档，其中包含一些规则，它们能够识别您允许访问存储段的源、每个源支持的操作（HTTP 方法），以及其他特定操作的信息。您可以向配置添加最多 100 条规则。将 XML 文档作为 cors 子资源添加到存储段，文件大小限制在64KB。

例如，以下针对存储段的 cors 配置包含两个指定为 CORSRule 元素的规则：

  • 第一个规则允许来自 https://www.example.com 源的跨源 PUT、POST 和 DELETE 请求。该规则还通过 Access-Control-Request-Headers 标头允许预检 OPTIONS 请求中的所有标头。作为对任何预检 OPTIONS 请求的响应，KS3 将返回请求的任意标头。

  • 规则二允许任一源通过 GET 方式请求跨源资源共享。“*”通配符字符是指所有的源。

      <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>

    用户可以通过其他可选参数来对某个空间进行 cors 配置。例如，设置允许源 http://www.example.com 使用 PUT 和 POST 发送跨源资源共享请求。

      <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>

上面的配置中，CORSRule包含以下可选参数：

  • MaxAgeSeconds--指定在 KS3 针对特定资源的预检 OPTIONS 请求作出响应后，浏览器缓存该响应的时间（以秒为单位）（在本示例中，为 3 000 秒）。通过缓存响应，在需要重复原始请求时，浏览器无需向KS3 发送预检请求。
  • ExposeHeader – 识别可允许客户从应用程序（例如，从 JavaScript XMLHttpRequest 数据元）进行访问的响应标头（在本示例中，为 x-kss-server-side-encryption）。

当KS3收到针对某一空间的跨源请求，它会根据设定的跨源资源共享规则来进行匹配，为了能够正常匹配，用户提交的规则配置必须满足以下条件。

  • 请求源头部必须匹配 AllowedOrigin 配置。
  • 在一个预检 OPTIONS 请求中请求方法（如 PUT,GET,HEAD等）或者 Access-Control-Request-Method header 必须是 AllowedMethod 配置中的一个。
  • 在一个预检 OPTIONS 请求中每一个在 Access-Control-Request-Headers 指明的头部必须匹配 AllowedHeader 配置。

请求

语法

PUT /?cors HTTP/1.1
Host: BucketName.kss.ksyun.com
Content-Length: length
Date: date
Authorization: authorization string
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>

请求参数

该请求不使用请求参数。

请求头部

该接口仅使用常用响应头部。获取更多信息，请点击常用响应头部。

请求内容

名称 描述 必须
CORSConfiguration 包含 CORSRules 元素的容器，元素上限为100。
类型: Container
子节点: CORSRules
父节点: 无		 是
CORSRule 源与方法的集合，最多可以配置100条规则。
类型: Container
子节点: AllowedOrigin, AllowedMethod, MaxAgeSeconds, ExposeHeader, ID.
父节点: CORSConfiguration		 是
ID 规则的唯一表示，最多255字符，它可以帮助你快速查找配置中的某一规则。
类型: String
父节点: CORSRule		 是
AllowedMethod 用户允许源所能执行的 HTTP 方法，每一条 CORSRule 必须定义至少一个源地址和一种方法。
类型: Enum (GET, PUT, HEAD, POST, DELETE)
父节点: CORSRule		 是
AllowedOrigin 用户允许跨源资源共享访问的源地址，其最多含有一个"*"通配符。每一条 CORSRule 必须定义至少一个源地址和一种方法。例如：http://*.example.com。另外，你可以使用"*"来代表全部源。
类型: String
父节点: CORSRule		 是
AllowedHeader 指明在预检OPTION中通过 Access-Control-Request-Headers 哪些头部是可以使用的。每一个在 Access-Control-Request-Headers 中指定的头部必须要与发送到KS3请求的头部保持一致，最多使用一个"*"
类型: String
父节点: CORSRule		 是
MaxAgeSeconds 指定在 KS3 针对特定资源的预检 OPTIONS 请求作出响应后，浏览器缓存该响应的时间。一个 CORSRule 最多有一个 MaxAgeSeconds 元素.
类型: Integer (seconds)
父节点: CORSRule		 是
ExposeHeader 识别可允许客户从应用程序（例如，从 JavaScript XMLHttpRequest 数据元）进行访问的响应标头。
类型: String
父节点: CORSRule		 是

响应

响应头部

该接口仅使用常用响应头部。获取更多信息，请点击常用响应头部。

响应内容

该接口不使用响应内容。

特殊错误

该接口不返回错误代码。

示例

请求示例

PUT /?cors HTTP/1.1
Host: bucketcors.kss.ksyun.com
Content-MD5: 0mkEYgbBoqMI4LdwvYqNUw==
Authorization: authorization string
Content-Length: 216

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

响应示例

HTTP/1.1 200 OK
x-kss-request-id: eff6be918b1d43378fac13a1db42ba07
Date: Wed, 24 Dec 2014 03:02:52 GMT
Server: Tengine