tencent cloud

文档反馈

PUT Bucket Origin

最后更新时间:2024-11-21 14:50:30

功能描述

PUT Bucket Origin 接口用于设置存储桶的回源。

请求

请求示例

PUT /?origin HTTP 1.1
Host:<BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
说明
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com,其中 <BucketName-APPID> 为带 APPID 后缀的存储桶名字,例如 examplebucket-1250000000,请参见 存储桶概览 > 基本信息存储桶概述 > 存储桶命名规范 文档;<Region> 为 COS 的可用地域,请参见 地域和访问域名 文档。
Authorization: Auth String(详情请参见 请求签名 文档)。
该请求需结合请求体一起使用。

请求参数

此接口无请求参数。

请求头

此接口仅使用公共请求头部,详情请参见 公共请求头部 文档。

请求体

请求的请求体为回源规则。
<OriginConfiguration>
<OriginRule>
<RulePriority>Integer</RulePriority>
<OriginType>Redirect|Proxy|Mirror</OriginType>
<OriginCondition>
<!--回源设置的 HTTP 状态码设置根据回源类型决定,如果是 Proxy、Mirror 是404,如果是 Redirect 是4XX或5XX的任意状态码-->
<HTTPStatusCode>404</HTTPStatusCode>
<Prefix></Prefix>
</OriginCondition>
<OriginParameter>
<Protocol>HTTP|HTTPS|FOLLOW</Protocol>
<!--回源是否保留源站的错误码-->
<TransparentErrorCode>true|false</TransparentErrorCode>
<!--回源是否保留原始查询参数,支持保留、不保留两种-->
<FollowQueryString>true|false</FollowQueryString>
<!--回源的请求头部参数-->
<HttpHeader>
<!--回源是否传输全部的请求头部,支持传递、不传递两种-->
<FollowAllHeaders>true|false</FollowAllHeaders>
<!--回源新增指定头部,最多10个,自定义头部中一对键值算一个-->
<!--如果有值则新增头部,如果为空则不新增-->
<NewHttpHeaders>
<Header>
<Key>x-cos|oss|amz-ContentType|CacheControl|ContentDisposition|ContentEncoding|HttpExpiresDate|UserMetaData</Key>
<Value>string</Value>
</Header>
</NewHttpHeaders>
<!--回源透传原始请求的指定头部-->
<FollowHttpHeaders>
<Header>
<Key>x-cos|oss|amz-ContentType|CacheControl|ContentDisposition|ContentEncoding|HttpExpiresDate|UserMetaData</Key>
</Header>
</FollowHttpHeaders>
<!--回源不透传原始请求的指定头部-->
<ForbidFollowHeaders>
<Header>
<Key>String</Key>
</Header>
</ForbidFollowHeaders>
</HttpHeader>
<!--follow3xx参数-->
<FollowRedirection>true|false</FollowRedirection>
<!--重定向返回码参数只有在回源类型为 Redirect、Proxy 时可选,否则报参数错误-->
<HttpRedirectCode>301|302|307</HttpRedirectCode>
</OriginParameter>
<!--切备错误码,默认5XX切换备站,添加此选项后支持4XX切换备站 -->
<HTTPStandbyCode>
<StatusCode>404</StatusCode>
<StatusCode>403</StatusCode>
</HTTPStandbyCode>
<OriginInfo>
<!--Mirror 模式支持设置多个源站,按比例回源,分担单个源站的回源流量,最多支持填入10条回源地址,比例按权重分配;Proxy 和 Redirect 仅支持一个源站-->
<HostInfo>
<HostName>bucketname-appid.cos.region.myqcloud.com</HostName>
<!--源站权重,按比例回源-->
<Weight>4</Weight>
<!--备份回源地址,最多支持填入10条备份回源地址,节点命名依次按照1-10编号-->
<StandbyHostName_1>bucketname2-appid.cos.region.myqcloud.com</StandbyHostName_1>
<StandbyHostName_2>bucketname3-appid.cos.region.myqcloud.com</StandbyHostName_2>
</HostInfo>
<HostInfo>
<HostName>bucketname4-appid.cos.region.myqcloud.com</HostName>
<!--源站权重,按比例回源-->
<Weight>2</Weight>
<!--备份回源地址,最多支持填入10条备份回源地址,节点命名依次按照1-10编号-->
<StandbyHostName_1>bucketname5-appid.cos.region.myqcloud.com</StandbyHostName_1>
<StandbyHostName_2>bucketname6-appid.cos.region.myqcloud.com</StandbyHostName_2>
</HostInfo>
<FileInfo>
<!--回源为指定的文件-->
<FixedFileConfiguration>
<FixedFilePath>String</FixedFilePath>
</FixedFileConfiguration>
<!--回源文件的新增文件前缀-->
<Prefix></Prefix>
<!--回源文件的新增文件后缀-->
<Suffix></Suffix>
</FileInfo>
</OriginInfo>
</OriginRule>
</OriginConfiguration>
具体的数据内容如下:
节点名称(关键字)
父节点
描述
类型
是否必选
OriginConfiguration
Origin 回源配置
Container
Container 节点 OriginConfiguration 的内容:
节点名称(关键字)
父节点
描述
类型
是否必选
OriginRule
OriginConfiguration
支持多条 OriginRule,通过优先级区分规则执行先后
Container
Container 节点 OriginRule 的内容:
节点名称(关键字)
父节点
描述
类型
是否必选
RulePriority
OriginConfiguration.OriginRule
通过优先级区分规则执行先后
Integer
OriginType
OriginConfiguration.OriginRule
回源类型,支持异步回源(Proxy)、同步回源(Mirror)和重定向回源(Redirect)三种模式。 枚举值:Proxy|Mirror|Redirect
Container
OriginCondition
OriginConfiguration.OriginRule
回源配置,配置用户使用的 HTTP 传输协议等信息
Container
OriginParameter
OriginConfiguration.OriginRule
回源地址相关信息
Container
OriginInfo
OriginConfiguration.OriginRule
源站信息。例如源站域名或者源站 IP 等信息
Container
Container 节点 OriginCondition 的内容:
节点名称(关键字)
父节点
描述
类型
是否必选
HTTPStatusCode
OriginConfiguration.OriginRule.OriginCondition
触发回源的HTTP 状态码,Proxy 和 Mirror 模式支持填写404,Redirect 模式支持填写4XX和5XX
String
Prefix
OriginConfiguration.OriginRule.OriginCondition
触发回源的文件前缀,默认为空,任意文件均可触发
String
Container 节点 OriginParameter 的内容:
节点名称(关键字)
父节点
描述
类型
是否必选
Protocol
OriginConfiguration.OriginRule.OriginParameter
回源使用的协议,枚举值为 HTTP(使用 HTTP 协议),HTTPS(使用 HTTPS 协议)、FOLLOW(跟随用户使用的协议),默认值为 FOLLOW。
String
FollowQueryString
OriginConfiguration.OriginRule.OriginParameter
回源是否需要透传 HTTP 请求串,枚举值:true|false,默认为true
Boolean
HttpHeader
OriginConfiguration.OriginRule.OriginParameter
是否需要设置 Http 头部传输配置。
Container
FollowRedirection
OriginConfiguration.OriginRule.OriginParameter
源站3XX响应策略,枚举值true|false,选择 true 时跟随源站3xx重定向请求获取到资源,并将资源保存到 COS 上;选择false时透传3XX响应,不获取资源,默认为true
Boolean
HttpRedirectCode
OriginConfiguration.OriginRule.OriginParameter
仅支持RedirectProxy模式,设置重定向返回码参数,枚举值301|302|307,默认为302
String
Container 节点 HttpHeader 的内容:
节点名称(关键字)
父节点
描述
类型
是否必选
FollowAllHeaders
OriginConfiguration.OriginRule.OriginParameter.HttpHeader
是否传输全部的请求头部,枚举值:true|false,默认为false
Boolean
NewHttpHeaders
OriginConfiguration.OriginRule.OriginParameter.HttpHeader
设置回源新增指定头部,最多10个。
Container
FollowHttpHeaders
OriginConfiguration.OriginRule.OriginParameter.HttpHeader
设置回源透传原始请求的指定头部。
Container
ForbidFollowHeaders
OriginConfiguration.OriginRule.OriginParameter.HttpHeader
设置回源不透传的原始请求的指定头部。
Container
Container 节点 NewHttpHeaders、FollowHttpHeaders、ForbidFollowHeaders 的内容:
节点名称(关键字)
父节点
描述
类型
是否必选
Header
OriginConfiguration.OriginRule.OriginParameter.HttpHeader.NewHttpHeader
回源到源站时添加或者指定传递的自定义头部,默认为空。
Container
Container 节点 Header 的内容:
节点名称(关键字)
父节点
描述
类型
是否必选
Key
OriginConfiguration.OriginRule.OriginParameter.HttpHeader.NewHttpHeader.UserMetaData
用户设置的头部名称,默认为空。形式如x-cos|oss|amz-ContentType|CacheControl|ContentDisposition|ContentEncoding|HttpExpiresDate|UserMetaData
String
Value
OriginConfiguration.OriginRule.OriginParameter.HttpHeader.NewHttpHeader.UserMetaData
用户设置的头部值,默认为空。
String
Container 节点 OriginInfo 的内容:
节点名称(关键字)
父节点
描述
类型
是否必选
HostInfo
OriginConfiguration.OriginRule.OriginInfo
源站信息。Mirror 模式支持设置多个源站,按比例回源,分担单个源站的回源流量,最多支持填入10条回源地址,比例按权重分配;Proxy 和 Redirect 模式仅支持一个源站。
Container
FileInfo
OriginConfiguration.OriginRule.OriginInfo
回源文件信息。
Container
Container 节点 HostInfo 的内容:
节点名称(关键字)
父节点
描述
类型
是否必选
HostName
OriginConfiguration.OriginRule.OriginInfo.HostInfo
源站域名或者源站 IP。
String
Weight
OriginConfiguration.OriginRule.OriginInfo.HostInfo
源站权重,Mirror 模式下配置了多个源站时,会根据权重按比例回源。
Integer
StandbyHostName_N
OriginConfiguration.OriginRule.OriginInfo.HostInfo
备份回源地址,最多支持填入10条备份回源地址,节点命名依次按照1-10编号,例如StandbyHostName_1StandbyHostName_2......StandbyHostName_10
String
Container 节点 FileInfo 的内容:
节点名称(关键字)
父节点
描述
类型
是否必选
Prefix
OriginConfiguration.OriginRule.OriginInfo.FileInfo
回源文件的新增文件前缀,默认为空。
String
Suffix
OriginConfiguration.OriginRule.OriginInfo.FileInfo
回源文件的新增文件后缀,默认为空。
String
FixedFileConfiguration
OriginConfiguration.OriginRule.OriginInfo.FileInfo
回源到固定的文件。
String
Container 节点 FixedFileConfiguration 的内容:
节点名称(关键字)
父节点
描述
类型
是否必选
FixedFilePath
OriginConfiguration.OriginRule.OriginInfo.FileInfo.FixedFileConfiguration
回源的固定文件路径。
String

响应

响应头

此接口仅返回公共响应头部,详情请参见 公共响应头部 文档。

响应体

此接口响应体为空。

错误码

此接口遵循统一的错误响应和错误码,详情请参见 错误码 文档。

实际案例

案例一:普通 Mirror 模式

请求

PUT /?origin= HTTP/1.1
Host: examplebucket-1250000000.cos.ap-shanghai.myqcloud.com
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1484639384;32557535384&q-key-time=1484639384;32557535384&q-header-list=host&q-url-param-list=&q-signature=****************************************
Content-Length: 347
Date: Sun, 28 Apr 2019 12:02:24 GMT

<?xml version="1.0" encoding="UTF-8"?>
<OriginConfiguration>
<OriginRule>
<RulePriority>1</RulePriority>
<OriginType>Mirror</OriginType>
<OriginCondition>
<HTTPStatusCode>404</HTTPStatusCode>
<Prefix></Prefix>
</OriginCondition>
<OriginParameter>
<Protocol>HTTP</Protocol>
<FollowQueryString>true</FollowQueryString>
<HttpHeader>
<FollowAllHeaders>false</FollowAllHeaders>
<NewHttpHeaders>
<Header>
<Key>x-cos</Key>
<Value>exampleHeader</Value>
</Header>
</NewHttpHeaders>
<FollowHttpHeaders>
<Header>
<Key>exampleHeaderKey</Key>
</Header>
</FollowHttpHeaders>
</HttpHeader>
<FollowRedirection>true</FollowRedirection>
<HttpRedirectCode>302</HttpRedirectCode>
</OriginParameter>
<OriginInfo>
<HostInfo>
<HostName>examplebucket-1250000000.cos.ap-shanghai.myqcloud.com</HostName>
</HostInfo>
</OriginInfo>
</OriginRule>
</OriginConfiguration>

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Sun, 28 Apr 2019 12:02:45 GMT
Server: tencent-cos
x-cos-request-id: NWNjNTk2NTFfMmM4OGY3MGFfNadfadsfY2****

案例二:带权重的 Mirror 模式

在如下示例中,回源会透传除 x-cos-example-header 之外原始请求的所有头部;规则指定了两个回源源站,源站1bucketname1-appid.cos.region.myqcloud.com和源站2bucketname2-appid.cos.region.myqcloud.com,权重分别为8和2,80%的回源请求会访问源站1,20%的回源请求会访问源站2。

请求

PUT /?origin= HTTP/1.1
Host: examplebucket-1250000000.cos.ap-shanghai.myqcloud.com
Authorization:Authstring
Content-Length:Content-Length
DATE:Sun, 28 Apr 2019 12:02:24 GMT

<?xml version="1.0" encoding="UTF-8"?>
<OriginConfiguration>
<OriginRule>
<RulePriority>1</RulePriority>
<OriginType>Mirror</OriginType>
<OriginCondition>
<HTTPStatusCode>404</HTTPStatusCode>
<Prefix></Prefix>
</OriginCondition>
<OriginParameter>
<Protocol>HTTPS</Protocol>
<FollowQueryString>true</FollowQueryString>
<HttpHeader>
<FollowAllHeaders>true</FollowAllHeaders>
<ForbidFollowHeaders>
<Header>
<Key>x-cos-example-header</Key>
</Header>
</ForbidFollowHeaders>
</HttpHeader>
</OriginParameter>
<OriginInfo>
<HostInfo>
<HostName>bucketname1-appid.cos.region.myqcloud.com</HostName>
<Weight>8</Weight>
</HostInfo>
<HostInfo>
<HostName>bucketname2-appid.cos.region.myqcloud.com</HostName>
<Weight>2</Weight>
</HostInfo>
</OriginInfo>
</OriginRule>
</OriginConfiguration>

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Sun, 28 Apr 2019 12:02:25 GMT
Server: tencent-cos
x-cos-request-id: NWNjNTk2NTFfMmM4OGY3MGFfNTI1****

案例三:Proxy 模式

请求

PUT /?origin= HTTP/1.1
Host: examplebucket-1250000000.cos.ap-shanghai.myqcloud.com
Authorization:Authstring
Content-Length: 347
DATE:Sun, 28 Apr 2019 12:02:24 GMT

<?xml version="1.0" encoding="UTF-8"?>
<OriginConfiguration>
<OriginRule>
<RulePriority>1</RulePriority>
<OriginType>Proxy</OriginType>
<OriginCondition>
<HTTPStatusCode>404</HTTPStatusCode>
<Prefix></Prefix>
</OriginCondition>

<OriginParameter>
<Protocol>FOLLOW</Protocol>
<FollowQueryString>true</FollowQueryString>
<HttpHeader>
<FollowAllHeaders>true</FollowAllHeaders>
<NewHttpHeaders>
<Header>
<Key>x-cos-ContentType</Key>
<Value>csv</Value>
</Header>
</NewHttpHeader>
<FollowHttpHeaders>
<Header>
<Key>Content-Type</Key>
</Header>
</FollowHttpHeaders>
</HttpHeader>
<FollowRedirection>true</FollowRedirection>
</OriginParameter>

<OriginInfo>
<HostInfo>
<HostName>examplebucket-1250000000.cos.ap-shanghai.myqcloud.com</HostName>
</HostInfo>
</OriginInfo>
</OriginRule>
</OriginConfiguration>

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Sun, 28 Apr 2019 12:02:45 GMT
Server: tencent-cos
x-cos-request-id: NWNjNTk2NTFfMmM4OGY3MGFfNadfadsfY****

案例四:Redirect 模式

请求

PUT /?origin= HTTP/1.1
Host: examplebucket-1250000000.cos.ap-shanghai.myqcloud.com
Authorization:Authstring
Content-Length: 347
DATE:Sun, 28 Apr 2019 12:02:24 GMT

<?xml version="1.0" encoding="UTF-8"?>
<OriginConfiguration>
<OriginRule>
<RulePriority>1</RulePriority>
<OriginType>Redirect</OriginType>
<OriginCondition>
<HTTPStatusCode>403</HTTPStatusCode>
<Prefix></Prefix>
</OriginCondition>
<OriginParameter>
<HttpRedirectCode>301</HttpRedirectCode>
</OriginParameter>
<OriginInfo>
<HostInfo>
<HostName>examplebucket-1250000000.cos.ap-shanghai.myqcloud.com</HostName>
</HostInfo>
</OriginInfo>
</OriginRule>
</OriginConfiguration>

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Sun, 28 Apr 2019 12:02:25 GMT
Server: tencent-cos
x-cos-request-id: NWNjNTk2NTFfMmM4OGY3MGFfNTI1****


产品类别

文档章节

PUT Bucket Origin

联系我们

联系我们,为您的业务提供专属服务。

技术支持

如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

7x24 电话支持