@Generated(value="jsii-pacmak/1.58.0 (build f8ba112)", date="2022-05-20T22:19:58.052Z") public abstract class BucketBase extends Resource implements IBucket
Buckets can be either defined within this stack:
new Bucket(this, 'MyBucket', { props });
Or imported from an existing bucket:
Bucket.import(this, 'MyImportedBucket', { bucketArn: ... });
You can also export a bucket and import it into another stack:
const ref = myBucket.export(); Bucket.import(this, 'MyImportedBucket', ref);
IBucket.Jsii$Default
Modifier | Constructor and Description |
---|---|
protected |
BucketBase(software.amazon.jsii.JsiiObject.InitializationMode initializationMode) |
protected |
BucketBase(software.amazon.jsii.JsiiObjectRef objRef) |
protected |
BucketBase(software.constructs.Construct scope,
java.lang.String id) |
protected |
BucketBase(software.constructs.Construct scope,
java.lang.String id,
ResourceProps props) |
Modifier and Type | Method and Description |
---|---|
void |
addEventNotification(EventType event,
IBucketNotificationDestination dest,
NotificationKeyFilter... filters)
Adds a bucket notification event destination.
|
void |
addObjectCreatedNotification(IBucketNotificationDestination dest,
NotificationKeyFilter... filters)
Subscribes a destination to receive notifications when an object is created in the bucket.
|
void |
addObjectRemovedNotification(IBucketNotificationDestination dest,
NotificationKeyFilter... filters)
Subscribes a destination to receive notifications when an object is removed from the bucket.
|
AddToResourcePolicyResult |
addToResourcePolicy(PolicyStatement permission)
Adds a statement to the resource policy for a principal (i.e.
|
java.lang.String |
arnForObjects(java.lang.String keyPattern)
Returns an ARN that represents all objects within the bucket that match the key pattern specified.
|
protected void |
enableEventBridgeNotification() |
protected abstract java.lang.Boolean |
getAutoCreatePolicy()
Indicates if a bucket resource policy should automatically created upon the first call to `addToResourcePolicy`.
|
abstract java.lang.String |
getBucketArn()
The ARN of the bucket.
|
abstract java.lang.String |
getBucketDomainName()
The IPv4 DNS name of the specified bucket.
|
abstract java.lang.String |
getBucketDualStackDomainName()
The IPv6 DNS name of the specified bucket.
|
abstract java.lang.String |
getBucketName()
The name of the bucket.
|
abstract java.lang.String |
getBucketRegionalDomainName()
The regional domain name of the specified bucket.
|
abstract java.lang.String |
getBucketWebsiteDomainName()
The Domain name of the static website.
|
abstract java.lang.String |
getBucketWebsiteUrl()
The URL of the static website.
|
protected abstract java.lang.Boolean |
getDisallowPublicAccess()
Whether to disallow public access.
|
abstract IKey |
getEncryptionKey()
Optional KMS encryption key associated with this bucket.
|
abstract java.lang.Boolean |
getIsWebsite()
If this bucket has been configured for static website hosting.
|
protected IRole |
getNotificationsHandlerRole() |
abstract BucketPolicy |
getPolicy()
The resource policy associated with this bucket.
|
Grant |
grantDelete(IGrantable identity)
Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.
|
Grant |
grantDelete(IGrantable identity,
java.lang.Object objectsKeyPattern)
Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.
|
Grant |
grantPublicAccess(java.lang.String keyPrefix,
java.lang.String... allowedActions)
Allows unrestricted access to objects from this bucket.
|
Grant |
grantPut(IGrantable identity)
Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal.
|
Grant |
grantPut(IGrantable identity,
java.lang.Object objectsKeyPattern)
Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal.
|
Grant |
grantPutAcl(IGrantable identity)
Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket.
|
Grant |
grantPutAcl(IGrantable identity,
java.lang.String objectsKeyPattern)
Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket.
|
Grant |
grantRead(IGrantable identity)
Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
|
Grant |
grantRead(IGrantable identity,
java.lang.Object objectsKeyPattern)
Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
|
Grant |
grantReadWrite(IGrantable identity)
Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
|
Grant |
grantReadWrite(IGrantable identity,
java.lang.Object objectsKeyPattern)
Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
|
Grant |
grantWrite(IGrantable identity)
Grant write permissions to this bucket to an IAM principal.
|
Grant |
grantWrite(IGrantable identity,
java.lang.Object objectsKeyPattern)
Grant write permissions to this bucket to an IAM principal.
|
Rule |
onCloudTrailEvent(java.lang.String id)
Define a CloudWatch event that triggers when something happens to this repository.
|
Rule |
onCloudTrailEvent(java.lang.String id,
OnCloudTrailBucketEventOptions options)
Define a CloudWatch event that triggers when something happens to this repository.
|
Rule |
onCloudTrailPutObject(java.lang.String id)
Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call.
|
Rule |
onCloudTrailPutObject(java.lang.String id,
OnCloudTrailBucketEventOptions options)
Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call.
|
Rule |
onCloudTrailWriteObject(java.lang.String id)
Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to.
|
Rule |
onCloudTrailWriteObject(java.lang.String id,
OnCloudTrailBucketEventOptions options)
Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to.
|
java.lang.String |
s3UrlForObject()
The S3 URL of an S3 object.
|
java.lang.String |
s3UrlForObject(java.lang.String key)
The S3 URL of an S3 object.
|
protected abstract void |
setAutoCreatePolicy(java.lang.Boolean value)
Indicates if a bucket resource policy should automatically created upon the first call to `addToResourcePolicy`.
|
protected abstract void |
setDisallowPublicAccess(java.lang.Boolean value)
Whether to disallow public access.
|
protected void |
setNotificationsHandlerRole(IRole value) |
abstract void |
setPolicy(BucketPolicy value)
The resource policy associated with this bucket.
|
java.lang.String |
transferAccelerationUrlForObject()
The https Transfer Acceleration URL of an S3 object.
|
java.lang.String |
transferAccelerationUrlForObject(java.lang.String key)
The https Transfer Acceleration URL of an S3 object.
|
java.lang.String |
transferAccelerationUrlForObject(java.lang.String key,
TransferAccelerationUrlOptions options)
The https Transfer Acceleration URL of an S3 object.
|
java.lang.String |
urlForObject()
The https URL of an S3 object.
|
java.lang.String |
urlForObject(java.lang.String key)
The https URL of an S3 object.
|
protected java.util.List<java.lang.String> |
validate()
Validate the current construct.
|
java.lang.String |
virtualHostedUrlForObject()
The virtual hosted-style URL of an S3 object.
|
java.lang.String |
virtualHostedUrlForObject(java.lang.String key)
The virtual hosted-style URL of an S3 object.
|
java.lang.String |
virtualHostedUrlForObject(java.lang.String key,
VirtualHostedStyleUrlOptions options)
The virtual hosted-style URL of an S3 object.
|
applyRemovalPolicy, generatePhysicalName, getEnv, getPhysicalName, getResourceArnAttribute, getResourceNameAttribute, getStack, isResource
getNode, isConstruct, onPrepare, onSynthesize, onValidate, prepare, synthesize
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
applyRemovalPolicy, getEnv, getStack
getNode
protected BucketBase(software.amazon.jsii.JsiiObjectRef objRef)
protected BucketBase(software.amazon.jsii.JsiiObject.InitializationMode initializationMode)
protected BucketBase(software.constructs.Construct scope, java.lang.String id, ResourceProps props)
scope
- This parameter is required.id
- This parameter is required.props
- protected BucketBase(software.constructs.Construct scope, java.lang.String id)
scope
- This parameter is required.id
- This parameter is required.public void addEventNotification(EventType event, IBucketNotificationDestination dest, NotificationKeyFilter... filters)
Example:
Function myLambda; Bucket bucket = new Bucket(this, "MyBucket"); bucket.addEventNotification(EventType.OBJECT_CREATED, new LambdaDestination(myLambda), NotificationKeyFilter.builder().prefix("home/myusername/*").build());
addEventNotification
in interface IBucket
event
- The event to trigger the notification. This parameter is required.dest
- The notification destination (Lambda, SNS Topic or SQS Queue). This parameter is required.filters
- S3 object key filter rules to determine which objects trigger this event. This parameter is required.https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html
public void addObjectCreatedNotification(IBucketNotificationDestination dest, NotificationKeyFilter... filters)
This is identical to calling
onEvent(EventType.OBJECT_CREATED)
.
addObjectCreatedNotification
in interface IBucket
dest
- The notification destination (see onEvent). This parameter is required.filters
- Filters (see onEvent). This parameter is required.public void addObjectRemovedNotification(IBucketNotificationDestination dest, NotificationKeyFilter... filters)
This is identical to calling
onEvent(EventType.OBJECT_REMOVED)
.
addObjectRemovedNotification
in interface IBucket
dest
- The notification destination (see onEvent). This parameter is required.filters
- Filters (see onEvent). This parameter is required.public AddToResourcePolicyResult addToResourcePolicy(PolicyStatement permission)
Note that the policy statement may or may not be added to the policy.
For example, when an IBucket
is created from an existing bucket,
it's not possible to tell whether the bucket already has a policy
attached, let alone to re-use that policy to add more statements to it.
So it's safest to do nothing in these cases.
addToResourcePolicy
in interface IBucket
permission
- the policy statement to be added to the bucket's policy. This parameter is required.public java.lang.String arnForObjects(java.lang.String keyPattern)
To represent all keys, specify "*"
.
If you need to specify a keyPattern with multiple components, concatenate them into a single string, e.g.:
arnForObjects(home/${team}/${user}/*
)
arnForObjects
in interface IBucket
keyPattern
- This parameter is required.protected void enableEventBridgeNotification()
public Grant grantDelete(IGrantable identity, java.lang.Object objectsKeyPattern)
grantDelete
in interface IBucket
identity
- The principal. This parameter is required.objectsKeyPattern
- Restrict the permission to a certain key pattern (default '*').public Grant grantDelete(IGrantable identity)
grantDelete
in interface IBucket
identity
- The principal. This parameter is required.public Grant grantPublicAccess(java.lang.String keyPrefix, java.lang.String... allowedActions)
IMPORTANT: This permission allows anyone to perform actions on S3 objects in this bucket, which is useful for when you configure your bucket as a website and want everyone to be able to read objects in the bucket without needing to authenticate.
Without arguments, this method will grant read ("s3:GetObject") access to all objects ("*") in the bucket.
The method returns the iam.Grant
object, which can then be modified
as needed. For example, you can add a condition that will restrict access only
to an IPv4 range like this:
const grant = bucket.grantPublicAccess(); grant.resourceStatement!.addCondition(‘IpAddress’, { “aws:SourceIp”: “54.240.143.0/24” });
Note that if this IBucket
refers to an existing bucket, possibly not
managed by CloudFormation, this method will have no effect, since it's
impossible to modify the policy of an existing bucket.
grantPublicAccess
in interface IBucket
keyPrefix
- the prefix of S3 object keys (e.g. `home/*`). Default is "*".allowedActions
- the set of S3 actions to allow. This parameter is required.public Grant grantPut(IGrantable identity, java.lang.Object objectsKeyPattern)
If encryption is used, permission to use the key to encrypt the contents of written files will also be granted to the same principal.
public Grant grantPut(IGrantable identity)
If encryption is used, permission to use the key to encrypt the contents of written files will also be granted to the same principal.
public Grant grantPutAcl(IGrantable identity, java.lang.String objectsKeyPattern)
If your application has the '@aws-cdk/aws-s3:grantWriteWithoutAcl' feature flag set, calling {@link grantWrite} or {@link grantReadWrite} no longer grants permissions to modify the ACLs of the objects; in this case, if you need to modify object ACLs, call this method explicitly.
grantPutAcl
in interface IBucket
identity
- This parameter is required.objectsKeyPattern
- public Grant grantPutAcl(IGrantable identity)
If your application has the '@aws-cdk/aws-s3:grantWriteWithoutAcl' feature flag set, calling {@link grantWrite} or {@link grantReadWrite} no longer grants permissions to modify the ACLs of the objects; in this case, if you need to modify object ACLs, call this method explicitly.
grantPutAcl
in interface IBucket
identity
- This parameter is required.public Grant grantRead(IGrantable identity, java.lang.Object objectsKeyPattern)
If encryption is used, permission to use the key to decrypt the contents of the bucket will also be granted to the same principal.
public Grant grantRead(IGrantable identity)
If encryption is used, permission to use the key to decrypt the contents of the bucket will also be granted to the same principal.
public Grant grantReadWrite(IGrantable identity, java.lang.Object objectsKeyPattern)
If an encryption key is used, permission to use the key for encrypt/decrypt will also be granted.
Before CDK version 1.85.0, this method granted the s3:PutObject*
permission that included s3:PutObjectAcl
,
which could be used to grant read/write object access to IAM principals in other accounts.
If you want to get rid of that behavior, update your CDK version to 1.85.0 or later,
and make sure the @aws-cdk/aws-s3:grantWriteWithoutAcl
feature flag is set to true
in the context
key of your cdk.json file.
If you've already updated, but still need the principal to have permissions to modify the ACLs,
use the {@link grantPutAcl} method.
grantReadWrite
in interface IBucket
identity
- This parameter is required.objectsKeyPattern
- public Grant grantReadWrite(IGrantable identity)
If an encryption key is used, permission to use the key for encrypt/decrypt will also be granted.
Before CDK version 1.85.0, this method granted the s3:PutObject*
permission that included s3:PutObjectAcl
,
which could be used to grant read/write object access to IAM principals in other accounts.
If you want to get rid of that behavior, update your CDK version to 1.85.0 or later,
and make sure the @aws-cdk/aws-s3:grantWriteWithoutAcl
feature flag is set to true
in the context
key of your cdk.json file.
If you've already updated, but still need the principal to have permissions to modify the ACLs,
use the {@link grantPutAcl} method.
grantReadWrite
in interface IBucket
identity
- This parameter is required.public Grant grantWrite(IGrantable identity, java.lang.Object objectsKeyPattern)
If encryption is used, permission to use the key to encrypt the contents of written files will also be granted to the same principal.
Before CDK version 1.85.0, this method granted the s3:PutObject*
permission that included s3:PutObjectAcl
,
which could be used to grant read/write object access to IAM principals in other accounts.
If you want to get rid of that behavior, update your CDK version to 1.85.0 or later,
and make sure the @aws-cdk/aws-s3:grantWriteWithoutAcl
feature flag is set to true
in the context
key of your cdk.json file.
If you've already updated, but still need the principal to have permissions to modify the ACLs,
use the {@link grantPutAcl} method.
grantWrite
in interface IBucket
identity
- This parameter is required.objectsKeyPattern
- public Grant grantWrite(IGrantable identity)
If encryption is used, permission to use the key to encrypt the contents of written files will also be granted to the same principal.
Before CDK version 1.85.0, this method granted the s3:PutObject*
permission that included s3:PutObjectAcl
,
which could be used to grant read/write object access to IAM principals in other accounts.
If you want to get rid of that behavior, update your CDK version to 1.85.0 or later,
and make sure the @aws-cdk/aws-s3:grantWriteWithoutAcl
feature flag is set to true
in the context
key of your cdk.json file.
If you've already updated, but still need the principal to have permissions to modify the ACLs,
use the {@link grantPutAcl} method.
grantWrite
in interface IBucket
identity
- This parameter is required.public Rule onCloudTrailEvent(java.lang.String id, OnCloudTrailBucketEventOptions options)
Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.
onCloudTrailEvent
in interface IBucket
id
- The id of the rule. This parameter is required.options
- Options for adding the rule.public Rule onCloudTrailEvent(java.lang.String id)
Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.
onCloudTrailEvent
in interface IBucket
id
- The id of the rule. This parameter is required.public Rule onCloudTrailPutObject(java.lang.String id, OnCloudTrailBucketEventOptions options)
Note that some tools like aws s3 cp
will automatically use either
PutObject or the multipart upload API depending on the file size,
so using onCloudTrailWriteObject
may be preferable.
Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.
onCloudTrailPutObject
in interface IBucket
id
- The id of the rule. This parameter is required.options
- Options for adding the rule.public Rule onCloudTrailPutObject(java.lang.String id)
Note that some tools like aws s3 cp
will automatically use either
PutObject or the multipart upload API depending on the file size,
so using onCloudTrailWriteObject
may be preferable.
Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.
onCloudTrailPutObject
in interface IBucket
id
- The id of the rule. This parameter is required.public Rule onCloudTrailWriteObject(java.lang.String id, OnCloudTrailBucketEventOptions options)
This includes the events PutObject, CopyObject, and CompleteMultipartUpload.
Note that some tools like aws s3 cp
will automatically use either
PutObject or the multipart upload API depending on the file size,
so using this method may be preferable to onCloudTrailPutObject
.
Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.
onCloudTrailWriteObject
in interface IBucket
id
- The id of the rule. This parameter is required.options
- Options for adding the rule.public Rule onCloudTrailWriteObject(java.lang.String id)
This includes the events PutObject, CopyObject, and CompleteMultipartUpload.
Note that some tools like aws s3 cp
will automatically use either
PutObject or the multipart upload API depending on the file size,
so using this method may be preferable to onCloudTrailPutObject
.
Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.
onCloudTrailWriteObject
in interface IBucket
id
- The id of the rule. This parameter is required.public java.lang.String s3UrlForObject(java.lang.String key)
s3://onlybucket
s3://bucket/key
s3UrlForObject
in interface IBucket
key
- The S3 key of the object.public java.lang.String s3UrlForObject()
s3://onlybucket
s3://bucket/key
s3UrlForObject
in interface IBucket
public java.lang.String transferAccelerationUrlForObject(java.lang.String key, TransferAccelerationUrlOptions options)
Specify dualStack: true
at the options
for dual-stack endpoint (connect to the bucket over IPv6). For example:
https://bucket.s3-accelerate.amazonaws.com
https://bucket.s3-accelerate.amazonaws.com/key
transferAccelerationUrlForObject
in interface IBucket
key
- The S3 key of the object.options
- Options for generating URL.public java.lang.String transferAccelerationUrlForObject(java.lang.String key)
Specify dualStack: true
at the options
for dual-stack endpoint (connect to the bucket over IPv6). For example:
https://bucket.s3-accelerate.amazonaws.com
https://bucket.s3-accelerate.amazonaws.com/key
transferAccelerationUrlForObject
in interface IBucket
key
- The S3 key of the object.public java.lang.String transferAccelerationUrlForObject()
Specify dualStack: true
at the options
for dual-stack endpoint (connect to the bucket over IPv6). For example:
https://bucket.s3-accelerate.amazonaws.com
https://bucket.s3-accelerate.amazonaws.com/key
transferAccelerationUrlForObject
in interface IBucket
public java.lang.String urlForObject(java.lang.String key)
https://s3.us-west-1.amazonaws.com/onlybucket
https://s3.us-west-1.amazonaws.com/bucket/key
https://s3.cn-north-1.amazonaws.com.cn/china-bucket/mykey
urlForObject
in interface IBucket
key
- The S3 key of the object.public java.lang.String urlForObject()
https://s3.us-west-1.amazonaws.com/onlybucket
https://s3.us-west-1.amazonaws.com/bucket/key
https://s3.cn-north-1.amazonaws.com.cn/china-bucket/mykey
urlForObject
in interface IBucket
protected java.util.List<java.lang.String> validate()
This method can be implemented by derived constructs in order to perform validation logic. It is called on all constructs before synthesis.
public java.lang.String virtualHostedUrlForObject(java.lang.String key, VirtualHostedStyleUrlOptions options)
https://only-bucket.s3.us-west-1.amazonaws.com
https://bucket.s3.us-west-1.amazonaws.com/key
https://bucket.s3.amazonaws.com/key
https://china-bucket.s3.cn-north-1.amazonaws.com.cn/mykey
virtualHostedUrlForObject
in interface IBucket
key
- The S3 key of the object.options
- Options for generating URL.public java.lang.String virtualHostedUrlForObject(java.lang.String key)
https://only-bucket.s3.us-west-1.amazonaws.com
https://bucket.s3.us-west-1.amazonaws.com/key
https://bucket.s3.amazonaws.com/key
https://china-bucket.s3.cn-north-1.amazonaws.com.cn/mykey
virtualHostedUrlForObject
in interface IBucket
key
- The S3 key of the object.public java.lang.String virtualHostedUrlForObject()
https://only-bucket.s3.us-west-1.amazonaws.com
https://bucket.s3.us-west-1.amazonaws.com/key
https://bucket.s3.amazonaws.com/key
https://china-bucket.s3.cn-north-1.amazonaws.com.cn/mykey
virtualHostedUrlForObject
in interface IBucket
public abstract java.lang.String getBucketArn()
getBucketArn
in interface IBucket
public abstract java.lang.String getBucketDomainName()
getBucketDomainName
in interface IBucket
public abstract java.lang.String getBucketDualStackDomainName()
getBucketDualStackDomainName
in interface IBucket
public abstract java.lang.String getBucketName()
getBucketName
in interface IBucket
public abstract java.lang.String getBucketRegionalDomainName()
getBucketRegionalDomainName
in interface IBucket
public abstract java.lang.String getBucketWebsiteDomainName()
getBucketWebsiteDomainName
in interface IBucket
public abstract java.lang.String getBucketWebsiteUrl()
getBucketWebsiteUrl
in interface IBucket
public abstract IKey getEncryptionKey()
getEncryptionKey
in interface IBucket
public abstract java.lang.Boolean getIsWebsite()
getIsWebsite
in interface IBucket
protected abstract java.lang.Boolean getAutoCreatePolicy()
protected abstract void setAutoCreatePolicy(java.lang.Boolean value)
protected abstract java.lang.Boolean getDisallowPublicAccess()
protected abstract void setDisallowPublicAccess(java.lang.Boolean value)
protected IRole getNotificationsHandlerRole()
protected void setNotificationsHandlerRole(IRole value)
public abstract BucketPolicy getPolicy()
If autoCreatePolicy
is true, a BucketPolicy
will be created upon the
first call to addToResourcePolicy(s).
public abstract void setPolicy(BucketPolicy value)
If autoCreatePolicy
is true, a BucketPolicy
will be created upon the
first call to addToResourcePolicy(s).