@aws-cdk/aws-s3

中文文档

1.204.0发布于 2023/06/20Apache-2.0TypeScriptCommonJS近 30 天下载 39.7万

AWS::S3 的 CDK 构造库

此软件包已被标记为弃用

AWS CDK v1 has reached End-of-Support on 2023-06-01. This package is no longer being updated, and users should migrate to AWS CDK v2. For more information on how to migrate, see https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html

文档目录24 节

加密
权限
AWS 基础安全最佳做法
执行 SSL
堆栈之间共享桶
导入已存在的桶
Bucket 通知
事件包通知
屏蔽公众访问
日志配置
S3 库存
网站重定向
静态重定向
规则
将桶装入部署
对象的 URL
对象所有权
对象写入器
首选的 Bucket 拥有者
Bucket 所有人被强制(建议)
框删除
传输加速
智能分层
生命周期规则

亚马逊 S3 构造库

AWS CDK v1在2023-06-01上达到了支持结束. 此软件包不再更新,用户应该迁移到 AWS CDK v2.

关于如何移徙的更多信息,请参见: 移动到 AWS CDK v2 指南。。。 .

定义未加密的 S3 桶 .

const bucket = new s3.Bucket(this, 'MyFirstBucket');

Bucket 构造显示以下部署时间属性:

bucketArn - 桶的ARN(即:. arn:aws:s3:::bucket_name(中文(简体) )
bucketName - 桶名(即:. bucket_name(中文(简体) )
bucketWebsiteUrl - 桶的网站URL(即:. http://bucket_name.s3-website-us-west-1.amazonaws.com(中文(简体) )
bucketDomainName - 桶的URL(即:. bucket_name.s3.amazonaws.com(中文(简体) )
bucketDualStackDomainName - 桶的双层URL(即:. bucket_name.s3.dualstack.eu-west-1.amazonaws.com(中文(简体) )
bucketRegionalDomainName - 桶的区域URL(即:. bucket_name.s3.eu-west-1.amazonaws.com(中文(简体) )
arnForObjects(pattern) - 桶内物体(即:. arn:aws:s3:::bucket_name/exampleobject.png 或者说 arn:aws:s3:::bucket_name/Development/*(中文(简体) )
urlForObject(key) - 桶内物体的HTTP URL(即:. https://s3.cn-north-1.amazonaws.com.cn/china-bucket/mykey(中文(简体) )
virtualHostedUrlForObject(key) - 一个对象的虚拟托管样式 HTTP URL 在桶内(即:. https://china-bucket-s3.cn-north-1.amazonaws.com.cn/mykey(中文(简体) )
s3UrlForObject(key) - 桶内物体的S3 URL(即:. s3://bucket/mykey(中文(简体) )

加密

定义 KMS 加密的桶 :

const bucket = new s3.Bucket(this, 'MyEncryptedBucket', {
  encryption: s3.BucketEncryption.KMS,
});

// you can access the encryption key:
assert(bucket.encryptionKey instanceof kms.Key);

您也可以提供自己的钥匙 :

const myKmsKey = new kms.Key(this, 'MyKey');

const bucket = new s3.Bucket(this, 'MyEncryptedBucket', {
  encryption: s3.BucketEncryption.KMS,
  encryptionKey: myKmsKey,
});

assert(bucket.encryptionKey === myKmsKey);

通过 KMS- SSE 加密 S3 密钥数字 :

const bucket = new s3.Bucket(this, 'MyEncryptedBucket', {
  encryption: s3.BucketEncryption.KMS,
  bucketKeyEnabled: true,
});

使用 BucketEncryption.ManagedKms 以使用 S3 主 KMS 密钥 :

const bucket = new s3.Bucket(this, 'Buck', {
  encryption: s3.BucketEncryption.KMS_MANAGED,
});

assert(bucket.encryptionKey == null);

权限

第一次呼叫时会自动为桶创建桶策略 addToResourcePolicy(statement)数字 :

const bucket = new s3.Bucket(this, 'MyBucket');
const result = bucket.addToResourcePolicy(new iam.PolicyStatement({
  actions: ['s3:GetObject'],
  resources: [bucket.arnForObjects('file.txt')],
  principals: [new iam.AccountRootPrincipal()],
}));

如果您尝试在已有的桶中添加一个策略语句, 此方法将什么都别做:

const bucket = s3.Bucket.fromBucketName(this, 'existingBucket', 'bucket-name');

// No policy statement will be added to the resource
const result = bucket.addToResourcePolicy(new iam.PolicyStatement({
  actions: ['s3:GetObject'],
  resources: [bucket.arnForObjects('file.txt')],
  principals: [new iam.AccountRootPrincipal()],
}));

那是因为不可能分辨这桶子已经附有一项政策,更不用说重新使用这项政策来增加发言。我们建议你随时检查电话结果:

const bucket = new s3.Bucket(this, 'MyBucket');
const result = bucket.addToResourcePolicy(new iam.PolicyStatement({
  actions: ['s3:GetObject'],
  resources: [bucket.arnForObjects('file.txt')],
  principals: [new iam.AccountRootPrincipal()],
}));

if (!result.statementAdded) {
  // Uh-oh! Someone probably made a mistake here.
}

创建后可以直接访问桶策略以添加语句或调整删除政策.

const bucket = new s3.Bucket(this, 'MyBucket');
bucket.policy?.applyRemovalPolicy(cdk.RemovalPolicy.RETAIN);

大多数时候,你不用直接操纵桶保单. 相反,桶子有“赠与”的方法, 要求给予预先包装的允许其他资源。例如:

declare const myLambda: lambda.Function;

const bucket = new s3.Bucket(this, 'MyBucket');
bucket.grantReadWrite(myLambda);

给Lambda执行角色的读写权限从桶.

AWS 基础安全最佳做法

执行 SSL

要求所有请求使用安全套接字层( SSL) :

const bucket = new s3.Bucket(this, 'Bucket', {
  enforceSSL: true,
});

要在同一 CDK 应用程序中使用不同的堆栈中的桶, 将对象传递到另一个堆栈 :

堆栈之间共享桶

导入已存在的桶

要将已有的桶导入您的 CDK 应用程序, 请使用 Bucket.fromBucketAttributes 工厂方法。此方法接受 BucketAttributes 描述一个已存在的属性已存在的桶 :

declare const myLambda: lambda.Function;
const bucket = s3.Bucket.fromBucketAttributes(this, 'ImportedBucket', {
  bucketArn: 'arn:aws:s3:::my-bucket',
});

// now you can just call methods on the bucket
bucket.addEventNotification(s3.EventType.OBJECT_CREATED, new s3n.LambdaDestination(myLambda), {prefix: 'home/myusername/*'});

或者,短期工厂作为 Bucket.fromBucketName 财务报告和审定财务报表 Bucket.fromBucketArn,它将从桶中获取所有桶属性名称或ARN分别为:

const byName = s3.Bucket.fromBucketName(this, 'BucketByName', 'my-bucket');
const byArn  = s3.Bucket.fromBucketArn(this, 'BucketByArn', 'arn:aws:s3:::my-bucket');

桶所在区域默认为当前堆栈所在区域,但也可以在桶之一的情况下明确设置区域属性需要包含正确的值.

const myCrossRegionBucket = s3.Bucket.fromBucketAttributes(this, 'CrossRegionImport', {
  bucketArn: 'arn:aws:s3:::my-bucket',
  region: 'us-east-1',
});
// myCrossRegionBucket.bucketRegionalDomainName === 'my-bucket.s3.us-east-1.amazonaws.com'

Bucket 通知

Amazon S3通知功能允许您在某些事件发生在你的桶里描述如下 S3 弹匣通知 s3 开发者指南.

要订阅桶通知,请使用 bucket.addEventNotification 方法。这个 bucket.addObjectCreatedNotification 财务报告和审定财务报表 bucket.addObjectRemovedNotification 也可以用于这些常用案例.

以下例子将订阅一个 SNS 专题,以便通知所有 s3:ObjectCreated:* 事件:

const bucket = new s3.Bucket(this, 'MyBucket');
const topic = new sns.Topic(this, 'MyTopic');
bucket.addEventNotification(s3.EventType.OBJECT_CREATED, new s3n.SnsDestination(topic));

这一呼吁还将确保专题政策能够接受以下通知: 这个特殊的桶.

支持的S3通知目标被暴露在 @aws-cdk/aws-s3-notifications 软件包.

也可以在签名时指定 S3 对象密钥过滤器。这个后面的示例将通知 myQueue 当对象的前缀 foo/ 财务报告和审定财务报表拥有 .jpg 后缀从桶中取出.

declare const myQueue: sqs.Queue;
const bucket = new s3.Bucket(this, 'MyBucket');
bucket.addEventNotification(s3.EventType.OBJECT_REMOVED,
  new s3n.SqsDestination(myQueue),
  { prefix: 'foo/', suffix: '.jpg' });

在现有桶上添加通知 :

declare const topic: sns.Topic;
const bucket = s3.Bucket.fromBucketAttributes(this, 'ImportedBucket', {
  bucketArn: 'arn:aws:s3:::my-bucket',
});
bucket.addEventNotification(s3.EventType.OBJECT_CREATED, new s3n.SnsDestination(topic));

当向桶中添加事件通知时,会创建自定义资源到管理通知。默认情况下,为 Lambda 创建了新角色函数执行此特性。如果你想用你自己的角色来代替, 你应该在 Bucket 构造器 :

declare const myRole: iam.IRole;
const bucket = new s3.Bucket(this, 'MyBucket', {
  notificationsHandlerRole: myRole,
});

无论您提供什么角色, CDK都会尝试通过添加权限从 AWSLambdaBasicExecutionRole (澳大利亚妇女协会管理的政策)以及作为权限 s3:PutBucketNotification 财务报告和审定财务报表 s3:GetBucketNotification。。。 . 如果您正在传递一个导入的角色, 而您不希望发生这种情况, 请配置不可改变:

const importedRole = iam.Role.fromRoleArn(this, 'role', 'arn:aws:iam::123456789012:role/RoleName', {
  mutable: false,
});

如果您提供了导入的不可变的作用, 请确保它至少具有全部上述权限。否则部署会失败!

事件包通知

Amazon S3可以发送事件到 Amazon EventBridge 每当你桶里发生某些事件. 与其他目的地不同,您不需要选择要交付哪些事件类型.

以下实例将允许 EventBridge 通知:

const bucket = new s3.Bucket(this, 'MyEventBridgeBucket', {
  eventBridgeEnabled: true,
});

屏蔽公众访问

使用 blockPublicAccess 指定块公共访问设置在水桶上。。 .

启用所有块公共访问设置 :

const bucket = new s3.Bucket(this, 'MyBlockedBucket', {
  blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
});

屏蔽和忽略公共ACLs:

const bucket = new s3.Bucket(this, 'MyBlockedBucket', {
  blockPublicAccess: s3.BlockPublicAccess.BLOCK_ACLS,
});

或者,手动指定设置 :

const bucket = new s3.Bucket(this, 'MyBlockedBucket', {
  blockPublicAccess: new s3.BlockPublicAccess({ blockPublicPolicy: true }),
});

何时 blockPublicPolicy 设置为 true, (中文(简体) ), grantPublicRead() 丢出一个错误.

日志配置

使用 serverAccessLogsBucket 来描述服务器访问日志的存储位置.

const accessLogsBucket = new s3.Bucket(this, 'AccessLogsBucket');

const bucket = new s3.Bucket(this, 'MyBucket', {
  serverAccessLogsBucket: accessLogsBucket,
});

还可以为亚马逊S3指定一个前缀,指定所有日志对象密钥.

const accessLogsBucket = new s3.Bucket(this, 'AccessLogsBucket');

const bucket = new s3.Bucket(this, 'MyBucket', {
  serverAccessLogsBucket: accessLogsBucket,
  serverAccessLogsPrefix: 'logs',
});

S3 库存

一个库存包含源桶中对象列表和每个对象的元数据。库存列表被存储在目的地桶中,作为用GZIP压缩的CSV文件,作为用ZLIB压缩的Apache优化行列(ORC)文件,或者作为用Snappy压缩的Apache Parquet(Parquet)文件.

您可以为一桶配置多个目录列表。您可以配置目录中包含哪些对象元数据, 是列出所有对象版本, 还是只列出当前版本, 将目录列表文件输出存储到何处, 以及是否每天或每周生成目录 .

const inventoryBucket = new s3.Bucket(this, 'InventoryBucket');

const dataBucket = new s3.Bucket(this, 'DataBucket', {
  inventories: [
    {
      frequency: s3.InventoryFrequency.DAILY,
      includeObjectVersions: s3.InventoryObjectVersion.CURRENT,
      destination: {
        bucket: inventoryBucket,
      },
    },
    {
      frequency: s3.InventoryFrequency.WEEKLY,
      includeObjectVersions: s3.InventoryObjectVersion.ALL,
      destination: {
        bucket: inventoryBucket,
        prefix: 'with-all-versions',
      },
    },
  ],
});

如果目的地桶作为同为CDK应用程序的一部分被创建,则所需的权限会自动被添加到桶策略中. 但是,如果使用进口桶(即: Bucket.fromXXX())),您必须确保其中包含以下政策文件: 1

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "InventoryAndAnalyticsExamplePolicy",
      "Effect": "Allow",
      "Principal": { "Service": "s3.amazonaws.com" },
      "Action": "s3:PutObject",
      "Resource": ["arn:aws:s3:::destinationBucket/*"]
    }
  ]
}

网站重定向

您可以使用以下两个属性指定桶重新定向政策请注意,这两种方法不能同时适用于同一桶.

静态重定向

您可以静态重定向一个给定的 Bucket URL 或其他主机名 websiteRedirect数字 :

const bucket = new s3.Bucket(this, 'MyRedirectedBucket', {
  websiteRedirect: { hostName: 'www.example.com' },
});

规则

或者,您也可以定义多个 websiteRoutingRules,用于定义复杂、有条件的重定向:

const bucket = new s3.Bucket(this, 'MyRedirectedBucket', {
  websiteRoutingRules: [{
    hostName: 'www.example.com',
    httpRedirectCode: '302',
    protocol: s3.RedirectProtocol.HTTPS,
    replaceKey: s3.ReplaceKey.prefixWith('test/'),
    condition: {
      httpErrorCodeReturnedEquals: '200',
      keyPrefixEquals: 'prefix',
    },
  }],
});

将桶装入部署

作为部署的一部分,将文件放入桶中(例如,托管一个网站),参见 @aws-cdk/aws-s3-deployment 软件包,提供资源可以做到这一点.

对象的 URL

S3为通过HTTP(S)访问对象提供了两种类型的URL. 路径样式和虚拟主机样式 URL (中文(简体) ). Path-Style是一种经典的方式,并将是已贬值。。。 . 我们建议在新制作的桶上使用虚拟主机-Style URL.

你可以生成两个.

const bucket = new s3.Bucket(this, 'MyBucket');
bucket.urlForObject('objectname'); // Path-Style URL
bucket.virtualHostedUrlForObject('objectname'); // Virtual Hosted-Style URL
bucket.virtualHostedUrlForObject('objectname', { regional: false }); // Virtual Hosted-Style URL but non-regional

对象所有权

您可以使用以下属性指定桶对象所有权。。。 .

对象写入器

上传账户将拥有对象 .

new s3.Bucket(this, 'MyBucket', {
  objectOwnership: s3.ObjectOwnership.OBJECT_WRITER,
});

首选的 Bucket 拥有者

如果对象被上传到桶主-完全控制罐的ACL上,桶主会拥有该对象. 没有这个设置和罐装ACL,该对象会被上传并仍然被上传账户所拥有.

new s3.Bucket(this, 'MyBucket', {
  objectOwnership: s3.ObjectOwnership.BUCKET_OWNER_PREFERRED,
});

Bucket 所有人被强制(建议)

ACL被禁用,而桶主自动拥有并完全控制了桶中每一个物体. ACLs不再影响S3桶中的数据权限. 该桶使用政策定义访问控制.

new s3.Bucket(this, 'MyBucket', {
  objectOwnership: s3.ObjectOwnership.BUCKET_OWNER_ENFORCED,
});

框删除

当从堆栈中取出一桶(或该堆栈被删除)时, S3 桶将根据其取出政策被取出(默认情况下将取出) 把桶放在AWS账户里如果删除政策设定为: RemovalPolicy.DESTROY,桶会删除,只要因为它不包含任何对象.

要覆盖这个并强迫所有对象在被桶删除时删除, 启用autoDeleteObjects 选项.

const bucket = new s3.Bucket(this, 'MyTempFileBucket', {
  removalPolicy: cdk.RemovalPolicy.DESTROY,
  autoDeleteObjects: true,
});

3⁄4 ̄ ̧漯B 如果你已经部署一个桶 autoDeleteObjects: true, (中文(简体) ), 切换到 false 在 CDK 版本中 在此之前 1.126.0 将会导致正在删除桶中的所有对象。确定更新您的桶资源用 CDK 版本部署 1.126.0 或稍后时间 在此之前 切换此值为 false。。。 .

传输加速

传输加速可以进行配置,以便能够快速、容易和安全地在长距离传输文件:

const bucket = new s3.Bucket(this, 'MyBucket', {
  transferAcceleration: true,
});

要访问用于传输加速的桶, 您必须使用特殊的端点。使用方法生成 URL transferAccelerationUrlForObject数字 :

const bucket = new s3.Bucket(this, 'MyBucket', {
  transferAcceleration: true,
});
bucket.transferAccelerationUrlForObject('objectname');

智能分层

智能分层能够配置到将文件自动移动到冰川:

new s3.Bucket(this, 'MyBucket', {
  intelligentTieringConfigurations: [{
    name: 'foo',
    prefix: 'folder/name',
    archiveAccessTierTime: cdk.Duration.days(90),
    deepArchiveAccessTierTime: cdk.Duration.days(180),
    tags: [{key: 'tagname', value: 'tagvalue'}]
  }],
});

生命周期规则

管理生命周期可配置过渡或到期动作.

const bucket = new s3.Bucket(this, 'MyBucket', {
  lifecycleRules: [{
    abortIncompleteMultipartUploadAfter: cdk.Duration.minutes(30),
    enabled: false,
    expiration: cdk.Duration.days(30),
    expirationDate: new Date(),
    expiredObjectDeleteMarker: false,
    id: 'id',
    noncurrentVersionExpiration: cdk.Duration.days(30),

    // the properties below are optional
    noncurrentVersionsToRetain: 123,
    noncurrentVersionTransitions: [{
      storageClass: s3.StorageClass.GLACIER,
      transitionAfter: cdk.Duration.days(30),

      // the properties below are optional
      noncurrentVersionsToRetain: 123,
    }],
    objectSizeGreaterThan: 500, 
    prefix: 'prefix',
    objectSizeLessThan: 10000, 
    transitions: [{
      storageClass: s3.StorageClass.GLACIER,

      // the properties below are optional
      transitionAfter: cdk.Duration.days(30),
      transitionDate: new Date(),
    }],
  }]
});

版本与发布记录

@aws-cdk/aws-s3 共发布 288 个版本，首次发布于 2018/07/31；过去 12 个月发布了 0 个版本。

版本	发布日期	距今
`1.204.0`latest	2023/06/20	3 年前
`1.203.0`	2023/06/01	3 年前
`1.202.0`	2023/05/22	3 年前
`1.201.0`	2023/05/11	3 年前
`1.200.0`	2023/04/27	3 年前
`1.199.0`	2023/04/21	3 年前

关于 @aws-cdk/aws-s3 的常见问题

@aws-cdk/aws-s3 是什么？

AWS::S3 的 CDK 构造库注意：该包已被作者标记为弃用——AWS CDK v1 has reached End-of-Support on 2023-06-01. This package is no longer being updated, and users should migrate to AWS CDK v2. For more information on how to migrate, see https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html

如何安装 @aws-cdk/aws-s3？

在项目目录运行 npm install @aws-cdk/aws-s3，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aws-cdk/aws-events（1.204.0）、@aws-cdk/aws-iam（1.204.0）、@aws-cdk/aws-kms（1.204.0）、@aws-cdk/core（1.204.0）、@aws-cdk/cx-api（1.204.0）、constructs（^3.3.69）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

@aws-cdk/aws-s3 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@aws-cdk/aws-s3 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require()；在 ES Module 项目中也可以用 import 引入（Node.js 会把 module.exports 作为默认导出）。

@aws-cdk/aws-s3 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >= 14.15.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@aws-cdk/aws-s3 可以商用吗？

@aws-cdk/aws-s3 使用 Apache-2.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

@aws-cdk/aws-s3 的下载量有多少？

根据 npm 官方下载统计，@aws-cdk/aws-s3 在 2026/10/08 – 2026/11/06 这 30 天内被下载 397,372 次，日均约 13,246 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@aws-cdk/aws-s3 还在维护吗？

最新版本 1.204.0 发布于 2023/06/20（3 年前）；至今共发布 288 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/07/31。作者已将其标记为弃用，新项目建议寻找替代方案。

npm install @aws-cdk/aws-s3

pnpmpnpm add @aws-cdk/aws-s3
yarnyarn add @aws-cdk/aws-s3
bunbun add @aws-cdk/aws-s3

peer 依赖@aws-cdk/aws-events 1.204.0@aws-cdk/aws-iam 1.204.0@aws-cdk/aws-kms 1.204.0@aws-cdk/core 1.204.0@aws-cdk/cx-api 1.204.0constructs ^3.3.69

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

在你的项目目录中运行此命令。

近 30 天下载

397,372

约 39.7万次日均 13,246 次

统计周期 2026/10/08 – 2026/11/06
数据来自 npm 官方下载统计，今天更新

最新版本1.204.0发布于 3 年前

开源许可Apache-2.0宽松许可

包体积3.2 MB39 个文件 · 解压后

运行依赖6 个另有 6 个 peer 依赖

模块格式CommonJS

TypeScript自带类型

Node.js>= 14.15.0

发布版本288 个近 12 个月 0 个

首次发布2018/07/318 年前

元数据更新2023/11/21

每一个软件包背后，
都有分享与创造的人。