8. 跨域资源共享¶

跨域资源共享(CORS)允许WEB端的应用程序访问不属于本域的资源。NOS提供了CORS支持以方便利用NOS开发更灵活的WEB应用程序。NOS提供接口方便开发者控制跨域访问的各种权限。

8.1. Put Bucket cors¶

8.1.1. 描述¶

Put Bucket cors操作将在指定的bucket上设定一个跨域资源共享(CORS)的规则，如果原规则存在则覆盖原规则。

8.1.2. 请求语法¶

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

<CORSConfiguration>
  <CORSRule>
     <AllowedOrigin>the origin you want allow CORS request from</AllowedOrigin>
     <AllowedMethod>HTTP method</AllowedMethod>
     <AllowedHeader> headers that allowed browser to send</AllowedHeader>
     <ExposeHeader> headers in response that can access from client app</ExposeHeader>
     <MaxAgeSeconds>time to cache pre-fight response</MaxAgeSeconds>
  </CORSRule>
  <CORSRule>
     …
  </CORSRule>
     …
</CORSConfiguration >

8.1.3. 请求参数¶

参数	描述	是否必须
CORSConfiguration	Bucket的CORS规则容器，可以指定1-10条CORS规则类型：容器默认：无	Yes
CORSRule	CORS规则类型：容器默认：无	Yes
AllowedOrigin	指定允许的跨域请求的来源，多个则以逗号分隔。每个来源字符串中允许使用最多一个‘’通配符。如果来源指定为“”则表示允许所有的来源的跨域请求。类型：非空字符串	Yes
AllowedMethod	指定允许的跨域请求方法。类型：枚举（GET,PUT,DELETE,POST,HEAD），多个则以逗号分隔默认：无	Yes
AllowedHeader	逗号分隔的header列表，控制在OPTIONS预取指令中Access-Control-Request-Headers头中指定的header是否允许。在Access-Control-Request-Headers中指定的每个header都必须在AllowedHeader中有一条对应的项。AllowedHeader的中的header值允许使用最多一个‘*’通配符。类型：类型：非空字符串默认：无	No
ExposeHeader	指定允许用户从应用程序中访问的响应头（例如一个Javascript的XMLHttpRequest对象。）不允许使用‘*’通配符。类型：类型：非空字符串默认：无	No
MaxAgeSeconds	指定浏览器对特定资源的预取（OPTIONS）请求返回结果的缓存时间，单位为秒。类型：整型默认：无	No

8.1.4. 示例¶

Request

PUT /?cors HTTP/1.1
Host: dream.nos-eastchina1.126.net
Content-Length: 186
Date: Fri, 04 May 2016 03:21:12 GMT
Authorization: NOS I_AM_ACCESS_ID:I_AM_SIGNATURE

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration>
  <CORSRule>
     <AllowedOrigin>*</AllowedOrigin>
     <AllowedMethod>PUT</AllowedMethod>
     <AllowedHeader>Authorization</AllowedHeader>
  </CORSRule>
  <CORSRule>
     <AllowedOrigin>http://www.a.com,http://www.b.com</AllowedOrigin>
     <AllowedMethod>GET</AllowedMethod>
     <AllowedHeader>Authorization</AllowedHeader>
     <ExposeHeader>x-nos-test,x-nos-test1</ExposeHeader>
     <MaxAgeSeconds>100</MaxAgeSeconds>
  </CORSRule>
</CORSConfiguration>

Response

HTTP/1.1 200 OK
x-nos-request-id: 17b21e42ac11000001390ab891440240
Date: Wed, 01 Mar 2012 21:34:55 GMT
Connection: close
Server: NOS

8.1.5. 细节描述¶

为了在应用程序中使用CORS功能，比如从一个www.a.com的网址通过浏览器的XMLHttpRequest功能来访问NOS，需要通过本接口上传CORS规则来开启。
每个bucket的CORS设定是由多条CORS规则指定的，每个bucket最多允许10条规则，上传的XML文档最多允许16KB大小。
当NOS收到一个跨域请求（或者OPTIONS请求），会读取bucket对应的CORS规则，然后进行相应的权限检查。NOS会依次检查每一条规则，使用第一条匹配的规则来允许请求并返回对应的header。如果所有规则都匹配失败则不附加任何CORS相关的header。
CORS规则匹配成功必须满足三个条件，首先，请求的Origin必须匹配一项AllowedOrigin值，其次，请求的方法（如GET，PUT等）或者OPTIONS请求的Access-Control-Request-Method头对应的方法必须匹配一项AllowedMethod值，最后，OPTIONS请求的Access-Control-Request-Headers头包含的每个header都必须匹配一项AllowedHeader值。

8.2. Get Bucket cors¶

8.2.1. 描述¶

Get Bucket cors操作用于获取指定的Bucket目前的CORS规则，返回PUT Bucket cors请求的body。

8.2.2. 语法¶

GET /?cors HTTP/1.1
Host: ${BucketName}.{endpoint}
Content-Length: ${length}
Date: ${date}
Authorization: ${signature}

8.2.3. 响应元素¶

与Put Bucket cors的请求元素一致。

8.2.4. 示例¶

Request

GET /cors HTTP/1.1
HOST: dream.nos-eastchina1.126.net
Date: Wed, 01 Mar 2012 21:34:55 GMT
Authorization: NOS I_AM_ACCESS_ID:I_AM_SIGNATURE

Response

HTTP/1.1 200

<CORSConfiguration>
   <CORSRule>
      <AllowedOrigin>{origin}</AllowedOrigin>
      <AllowedMethod>{method}</AllowedMethod>
      <AllowedHeader>{header}</AllowedHeader>
      <ExposeHeader>{exposeheader}</ExposeHeader>
      <MaxAgeSeconds>{age}</MaxAgeSeconds>
   </CORSRule>
   <CORSRule>
      ...
   </CORSRule>
      ...
</CORSConfiguration>

8.2.5. 细节描述¶

如果CORS规则不存在，返回404 Not Found错误，错误码NoSuchCORSConfiguration。

8.3. Delete Bucket cors¶

8.3.1. 描述¶

Delete Bucket cors用于关闭指定Bucket对应的CORS功能并清空所有规则。

8.3.2. 语法¶

DELETE /?cors HTTP/1.1
Host: ${BucketName}.{endpoint}
Date: ${date}
Authorization: ${signature}

8.3.3. 示例¶

Request

DELETE /?cors HTTP/1.1
HOST: dream.nos-eastchina1.126.net
Date: Wed, 01 Mar 2012 21:34:55 GMT
Authorization: NOS I_AM_ACCESS_ID:I_AM_SIGNATURE

Response

HTTP/1.1 200 OK
x-nos-request-id: 17b21e42ac11000001390ab891440240
Date: Wed, 01 Mar 2012 21:34:55 GMT
x-nos-acl: private
Connection: close
Server: NOS

8.4. OPTIONS Object¶

8.4.1. 描述¶

对于非简单跨域请求，浏览器在发送跨域请求之前会发送一个preflight请求（OPTIONS）并带上特定的来源域、HTTP方法和header信息等给NOS以决定是否发送真正的请求。 NOS可以通过Put Bucket cors接口来开启Bucket的CORS支持，开启CORS功能之后，NOS在收到浏览器preflight请求时会根据设定的规则评估是否允许本次请求。如果不允许或者CORS功能没有开启，返回403 Forbidden。

8.4.2. 语法¶

OPTIONS /ObjectName HTTP/1.1
Date: ${date}
Host: ${BucketName}.{endpoint}
Origin: origin
Access-Control-Request-Method: HTTP method
Access-Control-Request-Headers: Request Headers

8.4.3. 请求头¶

元素	描述	是否必须
Origin	请求来源域，用来标示跨域请求。类型：字符串默认：无	Yes
Access-Control-Request-Method	表示在实际请求中将会用到的方法。类型：字符串默认：无	Yes
Access-Control-Request-Headers	表示在实际请求中会用到的除了简单头部之外的headers，多个header则逗号分隔，大小写不敏感。类型：字符串	No

8.4.4. 响应头¶

返回200 OK时，携带如下响应消息头：

元素	描述	是否必须
Access-Control-Allow-Origin	请求中的Origin值，如果不允许的话将不包含该头部。类型：字符串	Yes
Access-Control-Allow-Methods	允许请求的HTTP方法，返回请求中Access-Control-Request-Method的值。如果不允许该请求，则不包含该头部。类型：字符串	Yes
Access-Control-Allow-Headers	允许请求携带的header的列表，逗号分隔，如果请求中有不被允许的header，则不包含该头部，请求也将被拒绝。类型：字符串	返回请求中Access-Control-Request-Headers的值（若有）
Access-Control-Expose-Headers	允许在客户端JavaScript程序中访问的headers的列表，逗号分隔。返回匹配到的CORS规则的ExposeHeader。类型：字符串	有则返回
Access-Control-Max-Age	允许浏览器缓存preflight结果的时间，单位为秒。返回匹配到的CORS规则的MaxAgeSeconds。类型：整型	有则返回

8.4.5. 示例¶

Request

OPTIONS /testobject HTTP/1.1
Host: dream.nos-eastchina1.126.net
Date: Fri, 24 Feb 2012 05:45:34 GMT
Origin:http://www.example.com
Access-Control-Request-Method:PUT
Access-Control-Request-Headers:x-nos-token

Response

HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://www.example.com
Access-Control-Allow-Methods: PUT
Access-Control-Expose-Headers: x-nos-token

8.4.6. 细节描述¶

桶不存在时，返回404，错误码NOSuchBucket。