Interface IBucket

Inherited Members

IResource.Stack

IConstruct.Node

Namespace: Amazon.CDK.AWS.S3

Assembly: Amazon.CDK.AWS.S3.dll

Syntax (csharp)

public interface IBucket : IResource, IConstruct, IConstruct, IDependable

Syntax (vb)

Public Interface IBucket
    Inherits IResource, IConstruct, IConstruct, IDependable

Synopsis

Properties

BucketArn	The ARN of the bucket.
BucketDomainName	The IPv4 DNS name of the specified bucket.
BucketDualStackDomainName	The IPv6 DNS name of the specified bucket.
BucketName	The name of the bucket.
BucketRegionalDomainName	The regional domain name of the specified bucket.
BucketWebsiteDomainName	The Domain name of the static website.
BucketWebsiteUrl	The URL of the static website.
EncryptionKey	Optional KMS encryption key associated with this bucket.
IsWebsite	If this bucket has been configured for static website hosting.
Policy	The resource policy associated with this bucket.

Methods

AddToResourcePolicy(PolicyStatement)	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.
ArnForObjects(String)	Returns an ARN that represents all objects within the bucket that match the key pattern specified.
GrantDelete(IGrantable, Object)	Grants s3:DeleteObject* permission to an IAM pricipal for objects in this bucket.
GrantPublicAccess(String, String[])	Allows unrestricted access to objects from this bucket.
GrantPut(IGrantable, Object)	Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal.
GrantRead(IGrantable, Object)	Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
GrantReadWrite(IGrantable, Object)	Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User).
GrantWrite(IGrantable, Object)	Grant write permissions to this bucket to an IAM principal.
OnCloudTrailEvent(String, IOnCloudTrailBucketEventOptions)	Defines a CloudWatch event that triggers when something happens to this bucket.
OnCloudTrailPutObject(String, IOnCloudTrailBucketEventOptions)	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.
OnCloudTrailWriteObject(String, IOnCloudTrailBucketEventOptions)	Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to.
S3UrlForObject(String)	The S3 URL of an S3 object.
UrlForObject(String)	The https URL of an S3 object.

Properties

BucketArn

The ARN of the bucket.

string BucketArn { get; }

Property Value

System.String

Remarks

Attribute: true

BucketDomainName

The IPv4 DNS name of the specified bucket.

string BucketDomainName { get; }

Property Value

System.String

Remarks

Attribute: true

BucketDualStackDomainName

The IPv6 DNS name of the specified bucket.

string BucketDualStackDomainName { get; }

Property Value

System.String

Remarks

Attribute: true

BucketName

The name of the bucket.

string BucketName { get; }

Property Value

System.String

Remarks

Attribute: true

BucketRegionalDomainName

The regional domain name of the specified bucket.

string BucketRegionalDomainName { get; }

Property Value

System.String

Remarks

Attribute: true

BucketWebsiteDomainName

The Domain name of the static website.

string BucketWebsiteDomainName { get; }

Property Value

System.String

Remarks

Attribute: true

BucketWebsiteUrl

The URL of the static website.

string BucketWebsiteUrl { get; }

Property Value

System.String

Remarks

Attribute: true

EncryptionKey

Optional KMS encryption key associated with this bucket.

virtual IKey EncryptionKey { get; }

Property Value

IKey

IsWebsite

If this bucket has been configured for static website hosting.

virtual Nullable<bool> IsWebsite { get; }

Property Value

System.Nullable<System.Boolean>

Policy

The resource policy associated with this bucket.

virtual BucketPolicy Policy { get; set; }

Property Value

BucketPolicy

Remarks

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

Methods

AddToResourcePolicy(PolicyStatement)

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.

IAddToResourcePolicyResult AddToResourcePolicy(PolicyStatement permission)

Parameters

permission PolicyStatement

Returns

IAddToResourcePolicyResult

ArnForObjects(String)

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

string ArnForObjects(string keyPattern)

Parameters

keyPattern System.String

Returns

System.String

Remarks

To represent all keys, specify "*".

GrantDelete(IGrantable, Object)

Grants s3:DeleteObject* permission to an IAM pricipal for objects in this bucket.

Grant GrantDelete(IGrantable identity, object objectsKeyPattern = null)

Parameters

identity IGrantable

The principal.

objectsKeyPattern System.Object

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

Returns

Grant

GrantPublicAccess(String, String[])

Allows unrestricted access to objects from this bucket.

Grant GrantPublicAccess(string keyPrefix = null, params string[] allowedActions)

Parameters

keyPrefix System.String

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

allowedActions System.String[]

the set of S3 actions to allow.

Returns

Grant

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

Remarks

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

GrantPut(IGrantable, Object)

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

Grant GrantPut(IGrantable identity, object objectsKeyPattern = null)

Parameters

identity IGrantable

The principal.

objectsKeyPattern System.Object

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

Returns

Grant

Remarks

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

GrantRead(IGrantable, Object)

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

Grant GrantRead(IGrantable identity, object objectsKeyPattern = null)

Parameters

identity IGrantable

The principal.

objectsKeyPattern System.Object

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

Returns

Grant

Remarks

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

GrantReadWrite(IGrantable, Object)

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

Grant GrantReadWrite(IGrantable identity, object objectsKeyPattern = null)

Parameters

identity IGrantable

The principal.

objectsKeyPattern System.Object

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

Returns

Grant

Remarks

If an encryption key is used, permission to use the key for encrypt/decrypt will also be granted.

GrantWrite(IGrantable, Object)

Grant write permissions to this bucket to an IAM principal.

Grant GrantWrite(IGrantable identity, object objectsKeyPattern = null)

Parameters

identity IGrantable

The principal.

objectsKeyPattern System.Object

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

Returns

Grant

Remarks

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

OnCloudTrailEvent(String, IOnCloudTrailBucketEventOptions)

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

Rule OnCloudTrailEvent(string id, IOnCloudTrailBucketEventOptions options = null)

Parameters

id System.String

The id of the rule.

options IOnCloudTrailBucketEventOptions

Options for adding the rule.

Returns

Rule

Remarks

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

OnCloudTrailPutObject(String, IOnCloudTrailBucketEventOptions)

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, IOnCloudTrailBucketEventOptions options = null)

Parameters

id System.String

The id of the rule.

options IOnCloudTrailBucketEventOptions

Options for adding the rule.

Returns

Rule

Remarks

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.

OnCloudTrailWriteObject(String, IOnCloudTrailBucketEventOptions)

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, IOnCloudTrailBucketEventOptions options = null)

Parameters

id System.String

The id of the rule.

options IOnCloudTrailBucketEventOptions

Options for adding the rule.

Returns

Rule

Remarks

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.

S3UrlForObject(String)

The S3 URL of an S3 object.

string S3UrlForObject(string key = null)

Parameters

key System.String

The S3 key of the object.

Returns

System.String

an ObjectS3Url token

Remarks

For example:

Examples

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

UrlForObject(String)

The https URL of an S3 object.

string UrlForObject(string key = null)

Parameters

key System.String

The S3 key of the object.

Returns

System.String

an ObjectS3Url token

Remarks

For example:

Examples

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