PutBucketCORS--对象存储-火山引擎

文档中心

导航

对象存储

PutBucketCORS

最近更新时间：2024.08.01 20:30:29首次发布时间：2023.03.14 21:02:14

功能描述

此接口用于为存储桶（Bucket）设置跨域资源共享 CORS（Cross-Origin Resource Sharing）规则。您可以使用Content-MD5头带入期望的 MD5 值，与上传的对象的 MD5 值进行比较，如果不相等，则返回错误。

注意

如果您想要为桶设置跨域资源共享规则，您的账号必须具备 tos:PutBucketCORS 权限，具体操作请参见权限配置指南。
TOS 支持设置多条 CORS 规则，但是所有规则大小总和不能超过 20KiB。

请求消息样式

PUT /?cors HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 +0000
Authorization: authorization string

{
    "CORSRules":[
        {
            "AllowedOrigins":["the origin you want allow CORS request from"],
            "AllowedMethods":["HTTP method"],
            "AllowedHeaders":["headers that allowed browser to send"],
            "ExposeHeaders":["headers in response that can access from client app"],
            "MaxAgeSeconds":1024,
            "ResponseVary" : true
        }
    ]
}

请求参数和消息头

该请求使用的公共请求消息头，请参见公共参数。

名称	位置	参数类型	是否必选	示例值	说明
cors	Query	String	是	-	代表 PutBucketCORS 请求的特殊标识。
Content-MD5	Header	String	否	XrY7u+Ae7tCTyyK7j1rNww==	消息体的 Base64MD5 摘要。

请求元素

名称	参数类型	是否必选	示例值	说明
CORSRules	Array	是	-	CORS 规则信息。
AllowedOrigins	Array	是	["*"]	指定允许跨域请求的来源。约束如下： IP地址或域名形式，允许带端口号。需要携带 https:// 或 http://。可填写多个，每行一个，以回车间隔。每行最多只能有一个通配符 `*`。
AllowedMethods	Array	是	["PUT", "GET"]	指定允许的跨域请求方法，可指定一个或多个，包含 `PUT`、`GET`、`POST`、`DELETE`、`HEAD`。
AllowedHeaders	Array	否	["Authorization"]	指定允许跨域请求的响应头。约束如下：可填写多个，每行一个，以回车间隔。没有特殊需求的场景下，建议设置为 `*`，表示允许所有。
ExposeHeaders	Array	否	["x-tos-request-id"]	指定 CORS 响应中携带的补充头域，以给客户端提供额外的信息。约束如下：可填写多个，每行一个，以回车间隔。不允许使用通配符 `*`。注意通常建议添加 X-Tos-Request-Id 和 ETag 两个补充头域。
MaxAgeSeconds	Integer	否	1024	指定客户端对 OPTIONS 请求返回结果的缓存时间，单位为秒，默认为 3600。
ResponseVary	Bool	否	false	是否返回 `Vary: Origin` 头。 `false`：默认值，不返回 `Vary: Origin` 头。 `true`：响应的 Header 会返回 `Vary: Origin` 头。注意启用返回Vary: Origin 后，可能会增加浏览次数或者 CDN 回源次数。

响应消息头

该请求返回的公共响应消息头，请参见公共参数。

响应元素

该请求响应中无消息元素。

请求示例 1

为桶配置一个跨域访问 CORS 规则。

PUT /?cors HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 +0000
Authorization: authorization string

{
    "CORSRules":[
        {
            "AllowedOrigins":["*"],
            "AllowedMethods":["PUT", "GET"],
            "AllowedHeaders":["Authorization"],
            "ExposeHeaders":["x-tos-request-id"],
            "MaxAgeSeconds":1024
        }
    ]
}

响应示例 1

HTTP/1.1 200 OK
x-tos-id-2: f91b0c03a01300c1-a444ed0        
x-tos-request-id: f91b0c03a01300c1-a444ed0            
Date: Fri, 30 Jul 2021 06:45:39 GMT
server: TosServer
Content-Length: 0

请求示例 2

为桶配置允许来自 http://www.example.com PUT 和 POST 请求跨域访问并启用返回Vary: Origin 头，其中 MaxAgeSeconds 允许避免浏览器为相同的请求发送 OPTION 请求。

PUT /?cors HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 +0000
Authorization: authorization string

{
    "CORSRules":[
        {
            "AllowedOrigins":["http://www.example.com"],
            "AllowedMethods":["PUT", "GET"],
            "AllowedHeaders":["*"],
            "ExposeHeaders":["x-tos-request-id"],
            "MaxAgeSeconds":1024,
            "ResponseVary" : true
        }
    ]
}

响应示例 2

HTTP/1.1 200 OK
x-tos-id-2: f91b0c03a01300c1-a444ed0        
x-tos-request-id: f91b0c03a01300c1-a444ed0            
Date: Fri, 30 Jul 2021 06:45:39 GMT
server: TosServer
Content-Length: 0