ALIYUN::OSS::Bucket

属性名称

类型

必须

允许更新

描述

约束

BucketName

String

是

否

存储空间名称。

长度为3~63个字符。必须以小写英文字母或数字开头和结尾，可包含小写英文字母、数字和短划线（-）。

AccessControl

String

否

是

访问权限。

取值：

• private（默认值）：私有。

• public-read：公共读。

• public-read-write：公共读写。

CORSConfiguration

Map

否

是

跨域访问配置。

更多信息，请参见CORSConfiguration属性。

DeletionForce

Boolean

否

是

是否强制删除OSS中的文件。

取值：

• true：强制删除。

• false（默认值）：不强制删除。

EnableOssHdfsService

Boolean

否

是

是否开启OSS-HDFS服务。

取值：

• true：开启OSS-HDFS服务。

  说明

  一旦启用，它不能再被禁用。

• false：不开启OSS-HDFS服务。 

LifecycleConfiguration

Map

否

是

文件生命周期配置。

更多信息，请参见LifecycleConfiguration属性。

LoggingConfiguration

Map

否

否

日志存储配置。

更多信息，请参见LoggingConfiguration属性。

Policy

Map

否

是

存储空间策略。

更多信息，请参见Bucket Policy常见示例。

RedundancyType

String

否

否

Bucket的数据容灾类型。

取值：

• LRS（默认） ：本地冗余LRS，将您的数据冗余存储在同一个可用区的不同存储设备上，可支持两个存储设备并发损坏时，仍维持数据不丢失，可正常访问。

• ZRS：同城冗余ZRS，采用多可用区（AZ）机制，将您的数据冗余存储在同一地域（Region）的3个可用区。可支持单个可用区（机房）整体故障时（例如断电、火灾等），仍然能够保障数据的正常访问。

RefererConfiguration

Map

否

是

防盗链配置。

更多信息，请参见RefererConfiguration属性。

ResourceGroupId

String

否

否

资源组ID。

无

ServerSideEncryptionConfiguration

Map

否

是

服务端加密规则配置。

更多信息，请参见ServerSideEncryptionConfiguration属性。

StorageClass

String

否

否

存储空间类型。

取值：

• Standard（默认值）：标准存储。

• IA：低频访问。

• Archive：归档存储。

Tags

Map

否

是

存储空间标签。Key-Value形式的键值对。

最多设置20个标签。

Key长度为1~64个字符，不能以http://、https://或Aliyun开头。

Value长度为0~128个字符，必须为UTF-8编码。

VersioningConfiguration

Map

否

是

保存版本控制状态的容器。

更多信息，请参见VersioningConfiguration属性。

WebsiteConfigurationV2

Map

否

否

网站配置。

更多信息，请参见WebsiteConfigurationV2属性。

属性名称

类型

必须

允许更新

描述

约束

CORSRule

List

否

是

跨域访问规则。

更多信息，请参见CORSRule属性。

ResponseVary

Boolean

否

是

是否返回Vary: Origin头部。

其取值范围如下：

• true：无论是否发送了跨域请求，或者跨域请求是否成功，都返回Vary: Origin头部。

• false（默认）：在任何情况下都不返回Vary: Origin头部。

属性名称

类型

必须

允许更新

描述

约束

AllowedHeader

List

否

是

允许的跨域请求Header。

取值：

• *

• Cache-Control

• Content-Language

• Content-Type

• Expires

• Last-Modified

• Pragma

AllowedMethod

List

否

是

允许的跨域请求的方法。

取值：

• *

• GET

• PUT

• POST

• DELETE

• HEAD

AllowedOrigin

List

否

是

允许的跨域请求的来源。

无

ExposeHeader

List

否

是

允许用户从应用程序中访问的响应头。

不允许使用星号（*）。

MaxAgeSeconds

Number

否

是

浏览器对特定资源的OPTIONS请求返回结果的缓存时间。

无

属性名称

类型

必须

允许更新

描述

约束

Rule

List

是

否

生命周期规则。

更多信息，请参见Rule属性。

属性名称

类型

必须

允许更新

描述

约束

Prefix

String

是

否

规则所适用的前缀。

只有匹配前缀的对象才可能被该规则所影响。

AbortMultipartUpload

Map

否

否

未完成分片上传的过期属性。

更多信息，请参见AbortMultipartUpload属性。

Expiration

Map

否

否

对象规则的过期属性。

更多信息，请参见Expiration属性。

ID

String

否

否

规则的唯一ID。

最长为255字符。当没有指定ID或者ID为空时，OSS会自动生成一个唯一值。

Status

String

否

是

启用或停用规则。

取值：

• Enabled：启用规则。

• Disabled：停用规则。

Filter

Map

否

否

这条排除规则最多只有一个条件规则。

更多信息，请参见Filter属性。

属性名称

类型

必须

允许更新

描述

约束

Not

Map

否

否

排除规则

更多信息，请参见Not属性。

属性名称

类型

必须

允许更新

描述

约束

Tag

List

否

否

排除规则的标签。

这条排除规则最多适用于一个对象标签。

Prefix

String

否

否

规则前缀。

此排除规则所适用的对象前缀条件如下：

• 如果在规则（Rule）节点下配置了前缀（Prefix），那么在非（Not）节点下的前缀必须以规则节点下配置的前缀为开头。例如，如果在规则节点下配置的前缀是dir，则非节点下配置的前缀必须以dir开头，如dir1、dir2等。

• 如果在非（Not）节点下没有配置标签（Tag），那么非节点下配置的前缀不能与规则节点下配置的前缀相同。

简而言之，这条规则说明了在设置排除规则时，如果上级规则定义了一个前缀，那么下属的非规则内的前缀必须是上级前缀的子集或具体化，且不能完全相同（除非使用了标签配置）。这样设计是为了实现更细致和灵活的文件或对象筛选逻辑，特别是在云存储、数据备份或内容过滤等场景中。

属性名称

类型

必须

允许更新

描述

约束

CreatedBeforeDate

String

否

否

指定一个日期，OSS会对最后更新日期早于该日期的数据执行规则。

日期必须服从ISO8601的格式，且要求是UTC的零点。例如：2002-10-11T00:00:00.000Z。

Days

Number

否

否

对象最后修改后，规则将在多少天后生效。

以文件最后修改时间为起点开始计算，超过设定天数时即执行规则，则将对象删除。如果设置时间为30天，则最后修改日期为2016年01月01日的对象会在2016年01月31日被后端程序删除。

ExpiredObjectDeleteMarker

Boolean

否

否

指定是否应自动删除过期的删除标签。

有效值如下：

• true：这意味着过期删除标记将自动被移除。当设置为true时，指定Days或CreatedBeforeDate是不被支持的。

• false：这表示过期删除标记不会被自动移除。当设为false时，必须指定Days或CreatedBeforeDate中的一个。

属性名称

类型

必须

允许更新

描述

约束

CreatedBeforeDate

String

否

否

规则在何时之前生效。

日期为ISO8601的格式，并且值为UTC的零点。例如：2002-10-11T00:00:00.000Z。

Days

Number

否

否

对象最后修改后，规则会在多少天后生效。

以文件最后修改时间为起点开始计算，超过设定天数时即执行规则，则将对象删除。如果设置时间为30天，则最后修改日期为2016年01月01日的对象会在2016年01月31日被后端程序删除。

属性名称

类型

必须

允许更新

描述

约束

TargetBucket

String

否

否

存放访问日志的存储空间。

无

TargetPrefix

String

否

否

最终被保存的访问日志文件前缀。

无

属性名称

类型

必须

允许更新

描述

约束

ErrorDocument

Map

否

否

托管的静态错误页。

无

IndexDocument

Map

否

否

托管的静态首页。

无

RoutingRules

List

否

否

路由规则列表。

最大长度20。

属性名称

类型

必须

允许更新

描述

约束

Suffix

String

是

否

默认首页。

设置默认首页后，如果您访问以正斜杠（/）结尾的对象，OSS将返回到此默认首页。

Type

String

否

否

当设置默认首页后，尝试访问以非正斜杠（/）结尾且不存在的对象时的行为如下。

此规则仅在SupportSubDir设置为true时生效，并且在RoutingRule之后、ErrorFile之前生效。假设默认首页文件为index.html，当访问的文件路径为bucket.oss-cn-hangzhou.aliyuncs.com/abc，且对象ABC不存在时，针对Type不同值的行为如下：

• 0（默认）：检查abc/index.html是否存在（对象加上正斜杠（/）再加上首页名称），如果存在，则返回302重定向状态码，并在Location头部中设置URL代码为/abc/（正斜杠（/）加上对象名再加正斜杠（/））。如果不存在，则返回404错误，并继续检查ErrorFile。

• 1：直接返回404错误，错误类型为NoSuchKey，然后继续检查ErrorFile。

• 2：检查abc/index.html是否存在，如果存在则直接返回该对象的内容。如果不存在，则返回404错误，并继续检查ErrorFile。

SupportSubDir

String

否

否

当访问一个子目录时，是否跳转到该子目录的默认主页。

可选范围如下：

• true：跳转到子目录下的默认主页。

• false（默认）：不跳转到子目录下的默认主页，而是前往根目录下的默认主页。假设默认主页为index.html，如果访问bucket.oss-cn-hangzhou.aliyuncs.com/subdir/时，将SupportSubDir设置为false，则会重定向到bucket.oss-cn-hangzhou.aliyuncs.com/index.html；如果将SupportSubDir设置为true，则会重定向到bucket.oss-cn-hangzhou.aliyuncs.com/subdir/index.html。

属性名称

类型

必须

允许更新

描述

约束

Redirect

Map

是

否

指定当此规则被匹配时要执行的操作。

更多信息，请参见Redirect属性。

Condition

Map

是

否

匹配条件。

此规则仅在满足指定的所有项目时执行。只有当此容器下的每个节点的所有条件都得到满足时，才视为匹配成功。更多信息，请参见Condition属性。

RuleNumber

Integer

是

否

匹配并执行RoutingRule的序列号，OSS将根据此序列号顺序匹配规则。

如果匹配成功，则执行此规则并且不再执行后续规则。

属性名称

类型

必须

允许更新

描述

约束

KeyPrefixEquals

String

否

否

要匹配的对象名称的前缀。

无。

HttpErrorCodeReturnedEquals

String

否

否

当访问指定的对象时，为了符合此规则，必须返回此状态。

当跳转规则镜像回源类型时，此字段必须为404。

IncludeHeaders

List

否

否

此规则仅当请求中包含指定的头部且其值为指定的值时才会匹配。

最多可设置10个这样的条件。更多信息，请参见IncludeHeaders属性。

KeySuffixEquals

String

否

否

要匹配的对象名称的前缀。

无。

属性名称

类型

必须

允许更新

描述

约束

Equals

String

否

否

头部的值。

无

Key

String

是

否

头标的名称。

无

属性名称

类型

必须

允许更新

描述

约束

AllowEmptyReferer

Boolean

否

否

是否允许referer字段为空的请求访问。

取值：

• true（默认值）：允许。

• false：不允许。

RefererList

List

否

否

允许referer字段的白名单。

无

属性名称

类型

必须

允许更新

描述

约束

MirrorFollowRedirect

Boolean

否

否

当镜像回源后得到的结果是3xx状态码时，是否继续跳转到指定的Location以获取数据。

此设置仅在RedirectType设置为Mirror时生效。例如，当我们镜像请求回到源站时，源站返回了一个带有Location信息的302状态码。

• 如果设置为true，OSS将继续请求该Location指向的地址。这个过程最多可以跳转10次，超过10次后，镜像回源将失败并返回错误。

• 如果设置为false，OSS将直接返回302状态码，并将Location信息透传给客户端，由客户端决定是否继续跳转。

  默认值为：true。

MirrorURL

String

否

否

镜像回源站地址。

此设置仅在RedirectType配置为Mirror时生效。起源网址必须以http://或https://开头，并以正斜杠（/）结尾，OSS会在此基础上拼接上对象名称来构成返回的URL。例如，若要访问的对象名为myobject，当您将其设置为http://example.com/时，回源URL将会是http://example.com/myobject；如果设置为http://example.com/dir1/，则回源URL将会是http://example.com/dir1/myobject。

PassQueryString

Boolean

否

否

当执行跳转或回源镜像时，是否携带请求参数。

即用户以请求参数a=b&c=d的形式访问OSS，并设置PassQueryString为true时，若规则类型为302跳转，则此请求参数会附加在跳转的Location头部中，例如Location:example.com?a=b&c=d；若规则类型为镜像回源，则此请求参数也会被携带在发起的回源请求中。有效值：true、false（默认）。

MirrorPassQueryString

Boolean

否

否

与PassQueryString相同，但优先于PassQueryString。此设置仅在RedirectType设置为Mirror时有效。

默认值：false。

ReplaceKeyWith

String

否

否

使用Redirect规则时，对象名称将被ReplaceKeyWith指定的值替换，这使得您可以设置变量。

目前支持的变量是{key}，它代表请求中的对象名称。假设要访问名为test的对象，如果将ReplaceKeyWith设置为prefix/key，它代表请求中的对象名称。假设要访问名为test的对象，如果将ReplaceKeyWith设置为prefix/{key}。那么，后缀将指向http://example.com/prefix/test.suffix的Location头部。

这意味着，当客户端请求原始对象（例如，test）时，服务器会通过Redirect规则将其重定向到一个新位置，该位置的路径由ReplaceKeyWith定义的模式动态生成。在这个例子中，新路径会在“prefix/”后面加上原始对象名（即test），最终重定向的URL变为"http://example.com/prefix/test.suffix"。这里的".suffix"是您提到的后缀部分，按照您的描述它似乎是固定不变的，而"${key}"则成功地被对象名“test”替换。

Protocol

String

否

否

当执行跳转时的协议规范。

该规则仅在RedirectType设置为External或AliCDN的情况下适用。假如您希望访问的文件是“test”，并且想要将其重定向至“example.com”，同时指定协议为https，那么在HTTP响应中的Location头部应设置为"https://example.com/test"。可选的协议值有：http, https。

HttpRedirectCode

String

否

否

当进行跳转时返回的状态码。

仅当RedirectType设置为External或AliCDN时适用。默认值为302。可选值：301、302、307。

ReplaceKeyPrefixWith

String

否

否

该值将替代重定向中对象名称的前缀。如果前缀为空，则此字符串将在对象名称之前插入。

RedirectType

String

是

否

指定跳转的类型。

可选范围如下：

• 镜像（Mirror）：回源镜像，即反射回源站。

• 外部（External）：外部分支，即OSS会返回一个3xx状态码的请求，指示将分支指向另一个地址。

• 阿里云CDN（AliCDN）：阿里云CDN跳转，主要用于阿里云的内容分发网络。与“外部”不同的是，OSS会添加一个额外的头部信息。阿里云CDN识别到这个头部后，会主动跳转到指定的地址，并将获取的数据返回给用户，而不是向用户返回3xx的跳转请求。

MirrorHeaders

Map

否

否

指定回传到源端时被镜像的头部。

此设置仅在RedirectType被设置为Mirror时生效。更多信息，请参见MirrorHeaders属性。

MirrorCheckMd5

Boolean

否

否

是否回源检查MD5。

此配置仅在RedirectType设置为Mirror时生效。当MirrorCheckMd5设置为true时，如果源站返回的响应中包含Content-Md5头信息，OSS会检查拉取的数据MD5是否与该头信息匹配，如果不匹配，则不会将数据保存到OSS上。默认值：false。

EnableReplacePrefix

Boolean

否

否

如果将此字段设置为true，对象的前缀将被ReplaceKeyPrefixWith指定的值替换。如果未指定此字段或为空，则意味着对象的前缀将被截断。

注意：当ReplaceKeyWith字段不为空时，此字段不能设置为true。默认值：false。

HostName

String

否

否

跳转的域名。

该域名应遵循域名规范。如果要访问的文件名为test，并且协议设置为https，主机名设置为example.com，则Location头部应为https://example.com/test。

属性名称

类型

必须

允许更新

描述

约束

Remove

List

否

否

禁用指定头部向源的透传。

这仅在将RedirectType设置为Mirror时有效。每个头部的长度最多为1,024字节，并且字符集包括0-9、a-z、A-Z和破折号（-）。此字段最多可以指定10个。

PassAll

Boolean

否

否

是否将除以下头部之外的其他头部传递给源。

这仅在将RedirectType设置为Mirror时有效。需要排除的头部包括：- content-length, authorization2, authorization, range, date以及其他的通用头部- 以oss-/x-oss-/x-drs-开头的特定头部

默认值为：false

这意味着，默认情况下，这些特定的头部不会被传递到镜像源。如果需要修改此行为，可以将此设置调整为true，以允许这些头部信息通过。

Sets

List

否

否

设置一个头部到源服务器，当请求被回传给源服务器时，该头部会被设置，无论指定的头部是否包含在请求中。

此功能仅在将RedirectType设置为Mirror时生效。此容器最多可以为10组头信息进行这样的设置。更多信息，请参见Sets属性。

Pass

List

否

否

将指定的头部信息传递给源。

此操作仅在将RedirectType设置为镜像（Mirror）时有效。每个头部的最大长度为1,024字节，并且只能包含字符集0-9、a-z、A-Z和破折号（-）。此字段最多可以指定10个头部信息。

属性名称

类型

必须

允许更新

描述

约束

Value

String

是

否

将标头的值设置为最大1024字节，不包括\r\n。

此设置仅在RedirectType被设置为镜像（Mirror）时有效。

Key

String

是

否

将头部键设置为最大1024字节，使用的字符集与Pass相同。

此设置仅在RedirectType被设置为Mirror时有效。

属性名称

类型

必须

允许更新

描述

约束

Key

String

是

否

默认错误页面。

当指定了一个错误页面时，如果访问的对象不存在，将返回这个错误页面。

HttpStatus

String

否

否

错误页面的HTTP状态代码。

有效值：200、404（默认）。

属性名称

类型

必须

允许更新

描述

约束

SSEAlgorithm

String

是

否

服务端默认加密方式。

取值：

• KMS

• AES256

KMSMasterKeyID

String

否

否

密钥ID。

只有当SSEAlgorithm值为KMS，且使用指定的密钥加密时，才需指定密钥ID。

属性名称

类型

必须

允许更新

描述

约束

Status

String

是

否

版本控制状态。

取值：

• Enabled：开启版本控制状态

• Suspended：暂停版本控制状态