Package 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, BucketBase, IBucket.Jsii$Proxy
@Generated(value="jsii-pacmak/1.98.0 (build 00b106d)", date="2024-05-08T21:35:13.240Z") @Stability(Stable) public interface IBucket extends software.amazon.jsii.JsiiSerializable, IResource

  • Method Details

    • getBucketArn

      @Stability(Stable) @NotNull String getBucketArn()
      The ARN of the bucket.

    • getBucketDomainName

      @Stability(Stable) @NotNull String getBucketDomainName()
      The IPv4 DNS name of the specified bucket.

    • getBucketDualStackDomainName

      @Stability(Stable) @NotNull String getBucketDualStackDomainName()
      The IPv6 DNS name of the specified bucket.

    • getBucketName

      @Stability(Stable) @NotNull String getBucketName()
      The name of the bucket.

    • getBucketRegionalDomainName

      @Stability(Stable) @NotNull String getBucketRegionalDomainName()
      The regional domain name of the specified bucket.

    • getBucketWebsiteDomainName

      @Stability(Stable) @NotNull String getBucketWebsiteDomainName()
      The Domain name of the static website.

    • getBucketWebsiteUrl

      @Stability(Stable) @NotNull String getBucketWebsiteUrl()
      The URL of the static website.

    • getEncryptionKey

      @Stability(Stable) @Nullable default IKey getEncryptionKey()
      Optional KMS encryption key associated with this bucket.

    • getIsWebsite

      @Stability(Stable) @Nullable default Boolean getIsWebsite()
      If this bucket has been configured for static website hosting.

    • getPolicy

      @Stability(Stable) @Nullable default BucketPolicy getPolicy()
      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)
      The resource policy associated with this bucket.

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

    • addEventNotification

      @Stability(Stable) void addEventNotification(@NotNull EventType event, @NotNull IBucketNotificationDestination dest, @NotNull @NotNull NotificationKeyFilter... filters)
      Adds a bucket notification event destination.

      Example: 

       Function myLambda;
 Bucket bucket = new Bucket(this, "MyBucket");
 bucket.addEventNotification(EventType.OBJECT_CREATED, new LambdaDestination(myLambda), NotificationKeyFilter.builder().prefix("home/myusername/*").build());

      Parameters:
      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.
      See Also:

    • addObjectCreatedNotification

      @Stability(Stable) void addObjectCreatedNotification(@NotNull IBucketNotificationDestination dest, @NotNull @NotNull NotificationKeyFilter... filters)
      Subscribes a destination to receive notifications when an object is created in the bucket.

      This is identical to calling onEvent(s3.EventType.OBJECT_CREATED).

      Parameters:
      dest - The notification destination (see onEvent). This parameter is required.
      filters - Filters (see onEvent). This parameter is required.

    • addObjectRemovedNotification

      @Stability(Stable) void addObjectRemovedNotification(@NotNull IBucketNotificationDestination dest, @NotNull @NotNull NotificationKeyFilter... filters)
      Subscribes a destination to receive notifications when an object is removed from the bucket.

      This is identical to calling onEvent(EventType.OBJECT_REMOVED).

      Parameters:
      dest - The notification destination (see onEvent). This parameter is required.
      filters - Filters (see onEvent). This parameter is required.

    • addToResourcePolicy

      @Stability(Stable) @NotNull AddToResourcePolicyResult addToResourcePolicy(@NotNull PolicyStatement permission)
      Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use bucketArn and arnForObjects(keys) to obtain ARNs for this bucket or objects.

      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.

      Parameters:
      permission - the policy statement to be added to the bucket's policy. This parameter is required.
      Returns:
      metadata about the execution of this method. If the policy was not added, the value of statementAdded will be false. You should always check this value to make sure that the operation was actually carried out. Otherwise, synthesis and deploy will terminate silently, which may be confusing.

    • arnForObjects

      @Stability(Stable) @NotNull String arnForObjects(@NotNull String keyPattern)
      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.

    • enableEventBridgeNotification

      @Stability(Stable) void enableEventBridgeNotification()
      Enables event bridge notification, causing all events below to be sent to EventBridge:.

      • Object Deleted (DeleteObject)
      • Object Deleted (Lifecycle expiration)
      • Object Restore Initiated
      • Object Restore Completed
      • Object Restore Expired
      • Object Storage Class Changed
      • Object Access Tier Changed
      • Object ACL Updated
      • Object Tags Added
      • Object Tags Deleted

    • grantDelete

      @Stability(Stable) @NotNull Grant grantDelete(@NotNull IGrantable identity, @Nullable Object objectsKeyPattern)
      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(Stable) @NotNull Grant grantDelete(@NotNull IGrantable identity)
      Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket.

      Parameters:
      identity - The principal. This parameter is required.

    • grantPublicAccess

      @Stability(Stable) @NotNull Grant grantPublicAccess(@Nullable String keyPrefix, @NotNull @NotNull String... allowedActions)
      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(Stable) @NotNull Grant grantPut(@NotNull IGrantable identity, @Nullable Object objectsKeyPattern)
      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(Stable) @NotNull Grant grantPut(@NotNull IGrantable identity)
      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(Stable) @NotNull Grant grantPutAcl(@NotNull IGrantable identity, @Nullable String objectsKeyPattern)
      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 grantWrite or 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(Stable) @NotNull Grant grantPutAcl(@NotNull IGrantable identity)
      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 grantWrite or 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(Stable) @NotNull Grant grantRead(@NotNull IGrantable identity, @Nullable Object objectsKeyPattern)
      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(Stable) @NotNull Grant grantRead(@NotNull IGrantable identity)
      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(Stable) @NotNull Grant grantReadWrite(@NotNull IGrantable identity, @Nullable Object objectsKeyPattern)
      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 grantPutAcl method.

      Parameters:
      identity - The principal. This parameter is required.
      objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

    • grantReadWrite

      @Stability(Stable) @NotNull Grant grantReadWrite(@NotNull IGrantable identity)
      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 grantPutAcl method.

      Parameters:
      identity - The principal. This parameter is required.

    • grantWrite

      @Stability(Stable) @NotNull Grant grantWrite(@NotNull IGrantable identity, @Nullable Object objectsKeyPattern, @Nullable List<String> allowedActionPatterns)
      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 grantPutAcl method.

      Parameters:
      identity - The principal. This parameter is required.
      objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').
      allowedActionPatterns - Restrict the permissions to certain list of action patterns.

    • grantWrite

      @Stability(Stable) @NotNull Grant grantWrite(@NotNull IGrantable identity, @Nullable Object objectsKeyPattern)
      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 grantPutAcl method.

      Parameters:
      identity - The principal. This parameter is required.
      objectsKeyPattern - Restrict the permission to a certain key pattern (default '*').

    • grantWrite

      @Stability(Stable) @NotNull Grant grantWrite(@NotNull IGrantable identity)
      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 grantPutAcl method.

      Parameters:
      identity - The principal. This parameter is required.

    • onCloudTrailEvent

      @Stability(Stable) @NotNull Rule onCloudTrailEvent(@NotNull String id, @Nullable OnCloudTrailBucketEventOptions options)
      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(Stable) @NotNull Rule onCloudTrailEvent(@NotNull String id)
      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(Stable) @NotNull Rule onCloudTrailPutObject(@NotNull String id, @Nullable 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.

      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(Stable) @NotNull Rule onCloudTrailPutObject(@NotNull 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.

      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(Stable) @NotNull Rule onCloudTrailWriteObject(@NotNull String id, @Nullable OnCloudTrailBucketEventOptions options)
      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(Stable) @NotNull Rule onCloudTrailWriteObject(@NotNull String id)
      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(Stable) @NotNull String s3UrlForObject(@Nullable String key)
      The S3 URL of an S3 object.

      For example:

      • s3://onlybucket
      • s3://bucket/key

      Parameters:
      key - The S3 key of the object.
      Returns:
      an ObjectS3Url token

    • s3UrlForObject

      @Stability(Stable) @NotNull String s3UrlForObject()
      The S3 URL of an S3 object.

      For example:

      • s3://onlybucket
      • s3://bucket/key

      Returns:
      an ObjectS3Url token

    • transferAccelerationUrlForObject

      @Stability(Stable) @NotNull String transferAccelerationUrlForObject(@Nullable String key, @Nullable TransferAccelerationUrlOptions options)
      The https Transfer Acceleration URL of an S3 object.

      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

      Parameters:
      key - The S3 key of the object.
      options - Options for generating URL.
      Returns:
      an TransferAccelerationUrl token

    • transferAccelerationUrlForObject

      @Stability(Stable) @NotNull String transferAccelerationUrlForObject(@Nullable String key)
      The https Transfer Acceleration URL of an S3 object.

      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

      Parameters:
      key - The S3 key of the object.
      Returns:
      an TransferAccelerationUrl token

    • transferAccelerationUrlForObject

      @Stability(Stable) @NotNull String transferAccelerationUrlForObject()
      The https Transfer Acceleration URL of an S3 object.

      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

      Returns:
      an TransferAccelerationUrl token

    • urlForObject

      @Stability(Stable) @NotNull String urlForObject(@Nullable String key)
      The https URL of an S3 object. For example:.

      • 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

      Parameters:
      key - The S3 key of the object.
      Returns:
      an ObjectS3Url token

    • urlForObject

      @Stability(Stable) @NotNull String urlForObject()
      The https URL of an S3 object. For example:.

      • 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

      Returns:
      an ObjectS3Url token

    • virtualHostedUrlForObject

      @Stability(Stable) @NotNull String virtualHostedUrlForObject(@Nullable String key, @Nullable VirtualHostedStyleUrlOptions options)
      The virtual hosted-style URL of an S3 object. Specify regional: false at the options for non-regional URL. For example:.

      • 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

      Parameters:
      key - The S3 key of the object.
      options - Options for generating URL.
      Returns:
      an ObjectS3Url token

    • virtualHostedUrlForObject

      @Stability(Stable) @NotNull String virtualHostedUrlForObject(@Nullable String key)
      The virtual hosted-style URL of an S3 object. Specify regional: false at the options for non-regional URL. For example:.

      • 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

      Parameters:
      key - The S3 key of the object.
      Returns:
      an ObjectS3Url token

    • virtualHostedUrlForObject

      @Stability(Stable) @NotNull String virtualHostedUrlForObject()
      The virtual hosted-style URL of an S3 object. Specify regional: false at the options for non-regional URL. For example:.

      • 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

      Returns:
      an ObjectS3Url token