software.amazon.awscdk.services.s3

Interface IBucket

All Superinterfaces:

software.constructs.IConstruct, software.constructs.IDependable, IResource, software.amazon.jsii.JsiiSerializable

All Known Subinterfaces:

IBucket.Jsii$Default

All Known Implementing Classes:

Bucket, IBucket.Jsii$Proxy

@Generated(value="jsii-pacmak/1.29.0 (build 41df200)",
           date="2021-06-02T09:55:36.296Z")
 @Stability(value=Experimental)
public interface IBucket
extends software.amazon.jsii.JsiiSerializable, IResource

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	IBucket.Jsii$Default Internal default implementation for IBucket.
static class	IBucket.Jsii$Proxy A proxy class which represents a concrete javascript instance of this type.

Method Summary

Modifier and Type	Method and Description
AddToResourcePolicyResult	addToResourcePolicy(PolicyStatement permission) (experimental) Adds a statement to the resource policy for a principal (i.e.
String	arnForObjects(String keyPattern) (experimental) Returns an ARN that represents all objects within the bucket that match the key pattern specified.
String	getBucketArn() (experimental) The ARN of the bucket.
String	getBucketDomainName() (experimental) The IPv4 DNS name of the specified bucket.
String	getBucketDualStackDomainName() (experimental) The IPv6 DNS name of the specified bucket.
String	getBucketName() (experimental) The name of the bucket.
String	getBucketRegionalDomainName() (experimental) The regional domain name of the specified bucket.
String	getBucketWebsiteDomainName() (experimental) The Domain name of the static website.
String	getBucketWebsiteUrl() (experimental) The URL of the static website.
default IKey	getEncryptionKey() (experimental) Optional KMS encryption key associated with this bucket.
default Boolean	getIsWebsite() (experimental) If this bucket has been configured for static website hosting.
default BucketPolicy	getPolicy() (experimental) The resource policy associated with this bucket.
Grant	grantDelete(IGrantable identity) (experimental) Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.
Grant	grantDelete(IGrantable identity, Object objectsKeyPattern) (experimental) Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.
Grant	grantPublicAccess(String keyPrefix, String... allowedActions) (experimental) Allows unrestricted access to objects from this bucket.
Grant	grantPut(IGrantable identity) (experimental) Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal.
Grant	grantPut(IGrantable identity, Object objectsKeyPattern) (experimental) Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal.
Grant	grantPutAcl(IGrantable identity) (experimental) Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket.
Grant	grantPutAcl(IGrantable identity, String objectsKeyPattern) (experimental) Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket.
Grant	grantRead(IGrantable identity) (experimental) Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
Grant	grantRead(IGrantable identity, Object objectsKeyPattern) (experimental) Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
Grant	grantReadWrite(IGrantable identity) (experimental) Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
Grant	grantReadWrite(IGrantable identity, Object objectsKeyPattern) (experimental) Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
Grant	grantWrite(IGrantable identity) (experimental) Grant write permissions to this bucket to an IAM principal.
Grant	grantWrite(IGrantable identity, Object objectsKeyPattern) (experimental) Grant write permissions to this bucket to an IAM principal.
Rule	onCloudTrailEvent(String id) (experimental) Defines a CloudWatch event that triggers when something happens to this bucket.
Rule	onCloudTrailEvent(String id, OnCloudTrailBucketEventOptions options) (experimental) Defines a CloudWatch event that triggers when something happens to this bucket.
Rule	onCloudTrailPutObject(String id) (experimental) 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(String id, OnCloudTrailBucketEventOptions options) (experimental) 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(String id) (experimental) Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to.
Rule	onCloudTrailWriteObject(String id, OnCloudTrailBucketEventOptions options) (experimental) Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to.
String	s3UrlForObject() (experimental) The S3 URL of an S3 object.
String	s3UrlForObject(String key) (experimental) The S3 URL of an S3 object.
default void	setPolicy(BucketPolicy value) (experimental) The resource policy associated with this bucket.
String	urlForObject() (experimental) The https URL of an S3 object.
String	urlForObject(String key) (experimental) The https URL of an S3 object.
String	virtualHostedUrlForObject() (experimental) The virtual hosted-style URL of an S3 object.
String	virtualHostedUrlForObject(String key) (experimental) The virtual hosted-style URL of an S3 object.
String	virtualHostedUrlForObject(String key, VirtualHostedStyleUrlOptions options) (experimental) The virtual hosted-style URL of an S3 object.

Methods inherited from interface software.amazon.awscdk.IResource

getEnv, getStack

Methods inherited from interface software.constructs.IConstruct

getNode

Methods inherited from interface software.amazon.jsii.JsiiSerializable

$jsii$toJson

Method Detail

getBucketArn

@Stability(value=Experimental)
 @NotNull
String getBucketArn()

(experimental) The ARN of the bucket.

getBucketDomainName

@Stability(value=Experimental)
 @NotNull
String getBucketDomainName()

(experimental) The IPv4 DNS name of the specified bucket.

getBucketDualStackDomainName

@Stability(value=Experimental)
 @NotNull
String getBucketDualStackDomainName()

(experimental) The IPv6 DNS name of the specified bucket.

getBucketName

@Stability(value=Experimental)
 @NotNull
String getBucketName()

(experimental) The name of the bucket.

getBucketRegionalDomainName

@Stability(value=Experimental)
 @NotNull
String getBucketRegionalDomainName()

(experimental) The regional domain name of the specified bucket.

getBucketWebsiteDomainName

@Stability(value=Experimental)
 @NotNull
String getBucketWebsiteDomainName()

(experimental) The Domain name of the static website.

getBucketWebsiteUrl

@Stability(value=Experimental)
 @NotNull
String getBucketWebsiteUrl()

(experimental) The URL of the static website.

getEncryptionKey

@Stability(value=Experimental)
 @Nullable
default IKey getEncryptionKey()

(experimental) Optional KMS encryption key associated with this bucket.

getIsWebsite

@Stability(value=Experimental)
 @Nullable
default Boolean getIsWebsite()

(experimental) If this bucket has been configured for static website hosting.

getPolicy

@Stability(value=Experimental)
 @Nullable
default BucketPolicy getPolicy()

(experimental) The resource policy associated with this bucket.

If autoCreatePolicy is true, a BucketPolicy will be created upon the first call to addToResourcePolicy(s).

setPolicy

@Optional
default void setPolicy(@Nullable
                                 BucketPolicy value)

(experimental) The resource policy associated with this bucket.

If autoCreatePolicy is true, a BucketPolicy will be created upon the first call to addToResourcePolicy(s).

addToResourcePolicy

@Stability(value=Experimental)
 @NotNull
AddToResourcePolicyResult addToResourcePolicy(@NotNull
                                                                                       PolicyStatement permission)

(experimental) Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or it's contents. Use `bucketArn` and `arnForObjects(keys)` to obtain ARNs for this bucket or objects.

Parameters:

permission - This parameter is required.

arnForObjects

@Stability(value=Experimental)
 @NotNull
String arnForObjects(@NotNull
                                                              String keyPattern)

(experimental) Returns an ARN that represents all objects within the bucket that match the key pattern specified.

To represent all keys, specify "*".

Parameters:

keyPattern - This parameter is required.

grantDelete

@Stability(value=Experimental)
 @NotNull
Grant grantDelete(@NotNull
                                                           IGrantable identity,
                                                           @Nullable
                                                           Object objectsKeyPattern)

(experimental) Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.

Parameters:

identity - The principal. This parameter is required.

objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

grantDelete

@Stability(value=Experimental)
 @NotNull
Grant grantDelete(@NotNull
                                                           IGrantable identity)

(experimental) Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.

Parameters:

identity - The principal. This parameter is required.

grantPublicAccess

@Stability(value=Experimental)
 @NotNull
Grant grantPublicAccess(@Nullable
                                                                 String keyPrefix,
                                                                 @NotNull
                                                                 String... allowedActions)

(experimental) Allows unrestricted access to objects from this bucket.

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” });
 

Parameters:

keyPrefix - the prefix of S3 object keys (e.g. `home/*`). Default is "*".

allowedActions - the set of S3 actions to allow. This parameter is required.

Returns:

The `iam.PolicyStatement` object, which can be used to apply e.g. conditions.

grantPut

@Stability(value=Experimental)
 @NotNull
Grant grantPut(@NotNull
                                                        IGrantable identity,
                                                        @Nullable
                                                        Object objectsKeyPattern)

(experimental) Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal.

If encryption is used, permission to use the key to encrypt the contents of written files will also be granted to the same principal.

Parameters:

identity - The principal. This parameter is required.

objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

grantPut

@Stability(value=Experimental)
 @NotNull
Grant grantPut(@NotNull
                                                        IGrantable identity)

(experimental) Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal.

If encryption is used, permission to use the key to encrypt the contents of written files will also be granted to the same principal.

Parameters:

identity - The principal. This parameter is required.

grantPutAcl

@Stability(value=Experimental)
 @NotNull
Grant grantPutAcl(@NotNull
                                                           IGrantable identity,
                                                           @Nullable
                                                           String objectsKeyPattern)

(experimental) Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket.

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.

Parameters:

identity - The principal. This parameter is required.

objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

grantPutAcl

@Stability(value=Experimental)
 @NotNull
Grant grantPutAcl(@NotNull
                                                           IGrantable identity)

(experimental) Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket.

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.

Parameters:

identity - The principal. This parameter is required.

grantRead

@Stability(value=Experimental)
 @NotNull
Grant grantRead(@NotNull
                                                         IGrantable identity,
                                                         @Nullable
                                                         Object objectsKeyPattern)

(experimental) Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User).

If encryption is used, permission to use the key to decrypt the contents of the bucket will also be granted to the same principal.

Parameters:

identity - The principal. This parameter is required.

objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

grantRead

@Stability(value=Experimental)
 @NotNull
Grant grantRead(@NotNull
                                                         IGrantable identity)

(experimental) Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User).

If encryption is used, permission to use the key to decrypt the contents of the bucket will also be granted to the same principal.

Parameters:

identity - The principal. This parameter is required.

grantReadWrite

@Stability(value=Experimental)
 @NotNull
Grant grantReadWrite(@NotNull
                                                              IGrantable identity,
                                                              @Nullable
                                                              Object objectsKeyPattern)

(experimental) Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User).

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.

Parameters:

identity - The principal. This parameter is required.

objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

grantReadWrite

@Stability(value=Experimental)
 @NotNull
Grant grantReadWrite(@NotNull
                                                              IGrantable identity)

(experimental) Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User).

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.

Parameters:

identity - The principal. This parameter is required.

grantWrite

@Stability(value=Experimental)
 @NotNull
Grant grantWrite(@NotNull
                                                          IGrantable identity,
                                                          @Nullable
                                                          Object objectsKeyPattern)

(experimental) Grant write permissions to this bucket to an IAM principal.

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.

Parameters:

identity - The principal. This parameter is required.

objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

grantWrite

@Stability(value=Experimental)
 @NotNull
Grant grantWrite(@NotNull
                                                          IGrantable identity)

(experimental) Grant write permissions to this bucket to an IAM principal.

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.

Parameters:

identity - The principal. This parameter is required.

onCloudTrailEvent

@Stability(value=Experimental)
 @NotNull
Rule onCloudTrailEvent(@NotNull
                                                                String id,
                                                                @Nullable
                                                                OnCloudTrailBucketEventOptions options)

(experimental) Defines a CloudWatch event that triggers when something happens to this bucket.

Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.

Parameters:

id - The id of the rule. This parameter is required.

options - Options for adding the rule.

onCloudTrailEvent

@Stability(value=Experimental)
 @NotNull
Rule onCloudTrailEvent(@NotNull
                                                                String id)

(experimental) Defines a CloudWatch event that triggers when something happens to this bucket.

Requires that there exists at least one CloudTrail Trail in your account that captures the event. This method will not create the Trail.

Parameters:

id - The id of the rule. This parameter is required.

onCloudTrailPutObject

@Stability(value=Experimental)
 @NotNull
Rule onCloudTrailPutObject(@NotNull
                                                                    String id,
                                                                    @Nullable
                                                                    OnCloudTrailBucketEventOptions options)

(experimental) 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.

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.

Parameters:

id - The id of the rule. This parameter is required.

options - Options for adding the rule.

onCloudTrailPutObject

@Stability(value=Experimental)
 @NotNull
Rule onCloudTrailPutObject(@NotNull
                                                                    String id)

(experimental) 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.

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.

Parameters:

id - The id of the rule. This parameter is required.

onCloudTrailWriteObject

@Stability(value=Experimental)
 @NotNull
Rule onCloudTrailWriteObject(@NotNull
                                                                      String id,
                                                                      @Nullable
                                                                      OnCloudTrailBucketEventOptions options)

(experimental) Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to.

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.

Parameters:

id - The id of the rule. This parameter is required.

options - Options for adding the rule.

onCloudTrailWriteObject

@Stability(value=Experimental)
 @NotNull
Rule onCloudTrailWriteObject(@NotNull
                                                                      String id)

(experimental) Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to.

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.

Parameters:

id - The id of the rule. This parameter is required.

s3UrlForObject

@Stability(value=Experimental)
 @NotNull
String s3UrlForObject(@Nullable
                                                               String key)

(experimental) The S3 URL of an S3 object.

For example:

Example:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 s3:

Parameters:

key - The S3 key of the object.

Returns:

an ObjectS3Url token

s3UrlForObject

@Stability(value=Experimental)
 @NotNull
String s3UrlForObject()

(experimental) The S3 URL of an S3 object.

For example:

Example:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 s3:

Returns:

an ObjectS3Url token

urlForObject

@Stability(value=Experimental)
 @NotNull
String urlForObject(@Nullable
                                                             String key)

(experimental) The https URL of an S3 object.

For example:

Example:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 https:

Parameters:

key - The S3 key of the object.

Returns:

an ObjectS3Url token

urlForObject

@Stability(value=Experimental)
 @NotNull
String urlForObject()

(experimental) The https URL of an S3 object.

For example:

Example:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 https:

Returns:

an ObjectS3Url token

virtualHostedUrlForObject

@Stability(value=Experimental)
 @NotNull
String virtualHostedUrlForObject(@Nullable
                                                                          String key,
                                                                          @Nullable
                                                                          VirtualHostedStyleUrlOptions options)

(experimental) The virtual hosted-style URL of an S3 object.

Specify regional: false at the options for non-regional URL. For example:

Example:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 https:

Parameters:

key - The S3 key of the object.

options - Options for generating URL.

Returns:

an ObjectS3Url token

virtualHostedUrlForObject

@Stability(value=Experimental)
 @NotNull
String virtualHostedUrlForObject(@Nullable
                                                                          String key)

(experimental) The virtual hosted-style URL of an S3 object.

Specify regional: false at the options for non-regional URL. For example:

Example:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 https:

Parameters:

key - The S3 key of the object.

Returns:

an ObjectS3Url token

virtualHostedUrlForObject

@Stability(value=Experimental)
 @NotNull
String virtualHostedUrlForObject()

(experimental) The virtual hosted-style URL of an S3 object.

Specify regional: false at the options for non-regional URL. For example:

Example:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 https:

Returns:

an ObjectS3Url token