Class: AWS.S3
- Inherits:
-
AWS.Service
- Object
- AWS.Service
- AWS.S3
- Identifier:
- s3
- API Version:
- 2006-03-01
- Defined in:
- (unknown)
Overview
Constructs a service interface object. Each API operation is exposed as a function on service.
Service Description
Sending a Request Using S3
var s3 = new AWS.S3();
s3.abortMultipartUpload(params, function (err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Locking the API Version
In order to ensure that the S3 object uses this specific API, you can
construct the object by passing the apiVersion
option to the constructor:
var s3 = new AWS.S3({apiVersion: '2006-03-01'});
You can also set the API version globally in AWS.config.apiVersions
using
the s3 service identifier:
AWS.config.apiVersions = {
s3: '2006-03-01',
// other service API versions
};
var s3 = new AWS.S3();
Version:
-
2006-03-01
Defined Under Namespace
Classes: ManagedUpload
Waiter Resource States
This service supports a list of resource states that can be polled using the waitFor() method. The resource states are:
bucketExists, bucketNotExists, objectExists, objectNotExists
Constructor Summary
-
new AWS.S3(options = {}) ⇒ Object
constructor
Constructs a service object.
Property Summary
-
endpoint ⇒ AWS.Endpoint
readwrite
An Endpoint object representing the endpoint URL for service requests.
Properties inherited from AWS.Service
Method Summary
-
abortMultipartUpload(params = {}, callback) ⇒ AWS.Request
Aborts a multipart upload.
-
completeMultipartUpload(params = {}, callback) ⇒ AWS.Request
Completes a multipart upload by assembling previously uploaded parts.
-
copyObject(params = {}, callback) ⇒ AWS.Request
Creates a copy of an object that is already stored in Amazon S3.
-
createBucket(params, callback) ⇒ AWS.Request
Creates a new bucket.Note: This operation cannot be used in a browser.
-
createMultipartUpload(params = {}, callback) ⇒ AWS.Request
Initiates a multipart upload and returns an upload ID.
-
createPresignedPost(params, callback) ⇒ map?
Get a pre-signed POST policy to support uploading to S3 directly from an HTML form.
-
deleteBucket(params = {}, callback) ⇒ AWS.Request
Deletes the bucket.
-
deleteBucketAnalyticsConfiguration(params = {}, callback) ⇒ AWS.Request
Deletes an analytics configuration for the bucket (specified by the analytics configuration ID).
-
deleteBucketCors(params = {}, callback) ⇒ AWS.Request
Deletes the CORS configuration information set for the bucket.
-
deleteBucketEncryption(params = {}, callback) ⇒ AWS.Request
Deletes the server-side encryption configuration from the bucket.
-
deleteBucketInventoryConfiguration(params = {}, callback) ⇒ AWS.Request
Deletes an inventory configuration (identified by the inventory ID) from the bucket.
-
deleteBucketLifecycle(params = {}, callback) ⇒ AWS.Request
Deletes the lifecycle configuration from the bucket.
-
deleteBucketMetricsConfiguration(params = {}, callback) ⇒ AWS.Request
Deletes a metrics configuration (specified by the metrics configuration ID) from the bucket.
-
deleteBucketPolicy(params = {}, callback) ⇒ AWS.Request
Deletes the policy from the bucket.
-
deleteBucketReplication(params = {}, callback) ⇒ AWS.Request
Deletes the replication configuration from the bucket.
-
deleteBucketTagging(params = {}, callback) ⇒ AWS.Request
Deletes the tags from the bucket.
-
deleteBucketWebsite(params = {}, callback) ⇒ AWS.Request
This operation removes the website configuration from the bucket.
-
deleteObject(params = {}, callback) ⇒ AWS.Request
Removes the null version (if there is one) of an object and inserts a delete marker, which becomes the latest version of the object.
-
deleteObjects(params = {}, callback) ⇒ AWS.Request
This operation enables you to delete multiple objects from a bucket using a single HTTP request.
-
deleteObjectTagging(params = {}, callback) ⇒ AWS.Request
Removes the tag-set from an existing object.
-
deletePublicAccessBlock(params = {}, callback) ⇒ AWS.Request
Removes the PublicAccessBlock configuration from an Amazon S3 bucket.
-
getBucketAccelerateConfiguration(params = {}, callback) ⇒ AWS.Request
Returns the accelerate configuration of a bucket.
-
getBucketAcl(params = {}, callback) ⇒ AWS.Request
Gets the access control policy for the bucket.
-
getBucketAnalyticsConfiguration(params = {}, callback) ⇒ AWS.Request
Gets an analytics configuration for the bucket (specified by the analytics configuration ID).
-
getBucketCors(params = {}, callback) ⇒ AWS.Request
Returns the CORS configuration for the bucket.
-
getBucketEncryption(params = {}, callback) ⇒ AWS.Request
Returns the server-side encryption configuration of a bucket.
-
getBucketInventoryConfiguration(params = {}, callback) ⇒ AWS.Request
Returns an inventory configuration (identified by the inventory ID) from the bucket.
-
getBucketLifecycle(params = {}, callback) ⇒ AWS.Request
No longer used, see the GetBucketLifecycleConfiguration operation.
-
getBucketLifecycleConfiguration(params = {}, callback) ⇒ AWS.Request
Returns the lifecycle configuration information set on the bucket.
-
getBucketLocation(params = {}, callback) ⇒ AWS.Request
Returns the region the bucket resides in.
-
getBucketLogging(params = {}, callback) ⇒ AWS.Request
Returns the logging status of a bucket and the permissions users have to view and modify that status.
-
getBucketMetricsConfiguration(params = {}, callback) ⇒ AWS.Request
Gets a metrics configuration (specified by the metrics configuration ID) from the bucket.
-
getBucketNotification(params = {}, callback) ⇒ AWS.Request
No longer used, see the GetBucketNotificationConfiguration operation.
-
getBucketNotificationConfiguration(params = {}, callback) ⇒ AWS.Request
Returns the notification configuration of a bucket.
-
getBucketPolicy(params = {}, callback) ⇒ AWS.Request
Returns the policy of a specified bucket.
-
getBucketPolicyStatus(params = {}, callback) ⇒ AWS.Request
Retrieves the policy status for an Amazon S3 bucket, indicating whether the bucket is public.
-
getBucketReplication(params = {}, callback) ⇒ AWS.Request
Returns the replication configuration of a bucket.
-
getBucketRequestPayment(params = {}, callback) ⇒ AWS.Request
Returns the request payment configuration of a bucket.
-
getBucketTagging(params = {}, callback) ⇒ AWS.Request
Returns the tag set associated with the bucket.
-
getBucketVersioning(params = {}, callback) ⇒ AWS.Request
Returns the versioning state of a bucket.
-
getBucketWebsite(params = {}, callback) ⇒ AWS.Request
Returns the website configuration for a bucket.
-
getObject(params = {}, callback) ⇒ AWS.Request
Retrieves objects from Amazon S3.
-
getObjectAcl(params = {}, callback) ⇒ AWS.Request
Returns the access control list (ACL) of an object.
-
getObjectLegalHold(params = {}, callback) ⇒ AWS.Request
Gets an object's current Legal Hold status.
-
getObjectLockConfiguration(params = {}, callback) ⇒ AWS.Request
Gets the Object Lock configuration for a bucket.
-
getObjectRetention(params = {}, callback) ⇒ AWS.Request
Retrieves an object's retention settings.
-
getObjectTagging(params = {}, callback) ⇒ AWS.Request
Returns the tag-set of an object.
-
getObjectTorrent(params = {}, callback) ⇒ AWS.Request
Return torrent files from a bucket.
-
getPublicAccessBlock(params = {}, callback) ⇒ AWS.Request
Retrieves the PublicAccessBlock configuration for an Amazon S3 bucket.
-
getSignedUrl(operation, params, callback) ⇒ String?
Get a pre-signed URL for a given operation name.
-
headBucket(params = {}, callback) ⇒ AWS.Request
This operation is useful to determine if a bucket exists and you have permission to access it.
-
headObject(params = {}, callback) ⇒ AWS.Request
The HEAD operation retrieves metadata from an object without returning the object itself.
-
listBucketAnalyticsConfigurations(params = {}, callback) ⇒ AWS.Request
Lists the analytics configurations for the bucket.
-
listBucketInventoryConfigurations(params = {}, callback) ⇒ AWS.Request
Returns a list of inventory configurations for the bucket.
-
listBucketMetricsConfigurations(params = {}, callback) ⇒ AWS.Request
Lists the metrics configurations for the bucket.
-
listBuckets(params = {}, callback) ⇒ AWS.Request
Returns a list of all buckets owned by the authenticated sender of the request.Note: This operation cannot be used in a browser.
-
listMultipartUploads(params = {}, callback) ⇒ AWS.Request
This operation lists in-progress multipart uploads.
-
listObjects(params = {}, callback) ⇒ AWS.Request
Returns some or all (up to 1000) of the objects in a bucket.
-
listObjectsV2(params = {}, callback) ⇒ AWS.Request
Returns some or all (up to 1000) of the objects in a bucket.
-
listObjectVersions(params = {}, callback) ⇒ AWS.Request
Returns metadata about all of the versions of objects in a bucket.
-
listParts(params = {}, callback) ⇒ AWS.Request
Lists the parts that have been uploaded for a specific multipart upload.
-
putBucketAccelerateConfiguration(params = {}, callback) ⇒ AWS.Request
Sets the accelerate configuration of an existing bucket.
-
putBucketAcl(params = {}, callback) ⇒ AWS.Request
Sets the permissions on a bucket using access control lists (ACL).
-
putBucketAnalyticsConfiguration(params = {}, callback) ⇒ AWS.Request
Sets an analytics configuration for the bucket (specified by the analytics configuration ID).
-
putBucketCors(params = {}, callback) ⇒ AWS.Request
Sets the CORS configuration for a bucket.
-
putBucketEncryption(params = {}, callback) ⇒ AWS.Request
Creates a new server-side encryption configuration (or replaces an existing one, if present).
-
putBucketInventoryConfiguration(params = {}, callback) ⇒ AWS.Request
Adds an inventory configuration (identified by the inventory ID) from the bucket.
-
putBucketLifecycle(params = {}, callback) ⇒ AWS.Request
No longer used, see the PutBucketLifecycleConfiguration operation.
-
putBucketLifecycleConfiguration(params = {}, callback) ⇒ AWS.Request
Sets lifecycle configuration for your bucket.
-
putBucketLogging(params = {}, callback) ⇒ AWS.Request
Set the logging parameters for a bucket and to specify permissions for who can view and modify the logging parameters.
-
putBucketMetricsConfiguration(params = {}, callback) ⇒ AWS.Request
Sets a metrics configuration (specified by the metrics configuration ID) for the bucket.
-
putBucketNotification(params = {}, callback) ⇒ AWS.Request
No longer used, see the PutBucketNotificationConfiguration operation.
-
putBucketNotificationConfiguration(params = {}, callback) ⇒ AWS.Request
Enables notifications of specified events for a bucket.
-
putBucketPolicy(params = {}, callback) ⇒ AWS.Request
Replaces a policy on a bucket.
-
putBucketReplication(params = {}, callback) ⇒ AWS.Request
Creates a replication configuration or replaces an existing one.
-
putBucketRequestPayment(params = {}, callback) ⇒ AWS.Request
Sets the request payment configuration for a bucket.
-
putBucketTagging(params = {}, callback) ⇒ AWS.Request
Sets the tags for a bucket.
-
putBucketVersioning(params = {}, callback) ⇒ AWS.Request
Sets the versioning state of an existing bucket.
-
putBucketWebsite(params = {}, callback) ⇒ AWS.Request
Set the website configuration for a bucket.
-
putObject(params = {}, callback) ⇒ AWS.Request
Adds an object to a bucket.
-
putObjectAcl(params = {}, callback) ⇒ AWS.Request
uses the acl subresource to set the access control list (ACL) permissions for an object that already exists in a bucket.
-
putObjectLegalHold(params = {}, callback) ⇒ AWS.Request
Applies a Legal Hold configuration to the specified object.
-
putObjectLockConfiguration(params = {}, callback) ⇒ AWS.Request
Places an Object Lock configuration on the specified bucket.
-
putObjectRetention(params = {}, callback) ⇒ AWS.Request
Places an Object Retention configuration on an object.
-
putObjectTagging(params = {}, callback) ⇒ AWS.Request
Sets the supplied tag-set to an object that already exists in a bucket.
-
putPublicAccessBlock(params = {}, callback) ⇒ AWS.Request
Creates or modifies the PublicAccessBlock configuration for an Amazon S3 bucket.
-
restoreObject(params = {}, callback) ⇒ AWS.Request
Restores an archived copy of an object back into Amazon S3.
-
selectObjectContent(params = {}, callback) ⇒ AWS.Request
This operation filters the contents of an Amazon S3 object based on a simple Structured Query Language (SQL) statement.
-
upload(params = {}, [options], [callback]) ⇒ AWS.S3.ManagedUpload
Uploads an arbitrarily sized buffer, blob, or stream, using intelligent concurrent handling of parts if the payload is large enough.
-
uploadPart(params = {}, callback) ⇒ AWS.Request
Uploads a part in a multipart upload.
-
uploadPartCopy(params = {}, callback) ⇒ AWS.Request
Uploads a part by copying data from an existing object as data source.
-
waitFor(state, params = {}, callback) ⇒ AWS.Request
Waits for a given S3 resource.
Methods inherited from AWS.Service
makeRequest, makeUnauthenticatedRequest, defineService
Constructor Details
new AWS.S3(options = {}) ⇒ Object
Constructs a service object. This object has one method for each API operation.
Examples:
Constructing a S3 object
var s3 = new AWS.S3({apiVersion: '2006-03-01'});
Options Hash (options):
-
params
(map)
—
An optional map of parameters to bind to every request sent by this service object. For more information on bound parameters, see "Working with Services" in the Getting Started Guide.
-
endpoint
(String)
—
The endpoint URI to send requests to. The default endpoint is built from the configured
region
. The endpoint should be a string like'https://{service}.{region}.amazonaws.com'
. -
useDualstack
(Boolean)
—
Enables IPv6/IPv4 dualstack endpoint. When a DNS lookup is performed on an endpoint of this type, it returns an “A” record with an IPv4 address and an “AAAA” record with an IPv6 address. In most cases the network stack in the client environment will automatically prefer the AAAA record and make a connection using the IPv6 address. Note, however, that currently on Windows, the IPv4 address will be preferred.
-
accessKeyId
(String)
—
your AWS access key ID.
-
secretAccessKey
(String)
—
your AWS secret access key.
-
sessionToken
(AWS.Credentials)
—
the optional AWS session token to sign requests with.
-
credentials
(AWS.Credentials)
—
the AWS credentials to sign requests with. You can either specify this object, or specify the accessKeyId and secretAccessKey options directly.
-
credentialProvider
(AWS.CredentialProviderChain)
—
the provider chain used to resolve credentials if no static
credentials
property is set. -
region
(String)
—
the region to send service requests to. See AWS.S3.region for more information.
-
maxRetries
(Integer)
—
the maximum amount of retries to attempt with a request. See AWS.S3.maxRetries for more information.
-
maxRedirects
(Integer)
—
the maximum amount of redirects to follow with a request. See AWS.S3.maxRedirects for more information.
-
sslEnabled
(Boolean)
—
whether to enable SSL for requests.
-
paramValidation
(Boolean|map)
—
whether input parameters should be validated against the operation description before sending the request. Defaults to true. Pass a map to enable any of the following specific validation features:
- min [Boolean] — Validates that a value meets the min
constraint. This is enabled by default when paramValidation is set
to
true
. - max [Boolean] — Validates that a value meets the max constraint.
- pattern [Boolean] — Validates that a string value matches a regular expression.
- enum [Boolean] — Validates that a string value matches one of the allowable enum values.
- min [Boolean] — Validates that a value meets the min
constraint. This is enabled by default when paramValidation is set
to
-
computeChecksums
(Boolean)
—
whether to compute checksums for payload bodies when the service accepts it (currently supported in S3 only)
-
convertResponseTypes
(Boolean)
—
whether types are converted when parsing response data. Currently only supported for JSON based services. Turning this off may improve performance on large response payloads. Defaults to
true
. -
correctClockSkew
(Boolean)
—
whether to apply a clock skew correction and retry requests that fail because of an skewed client clock. Defaults to
false
. -
s3ForcePathStyle
(Boolean)
—
whether to force path style URLs for S3 objects.
-
s3BucketEndpoint
(Boolean)
—
whether the provided endpoint addresses an individual bucket (false if it addresses the root API endpoint). Note that setting this configuration option requires an
endpoint
to be provided explicitly to the service constructor. -
s3DisableBodySigning
(Boolean)
—
whether S3 body signing should be disabled when using signature version
v4
. Body signing can only be disabled when using https. Defaults totrue
. -
retryDelayOptions
(map)
—
A set of options to configure the retry delay on retryable errors. Currently supported options are:
- base [Integer] — The base number of milliseconds to use in the exponential backoff for operation retries. Defaults to 100 ms for all services except DynamoDB, where it defaults to 50ms.
- customBackoff [function] — A custom function that accepts a retry count
and returns the amount of time to delay in milliseconds. The
base
option will be ignored if this option is supplied.
-
httpOptions
(map)
—
A set of options to pass to the low-level HTTP request. Currently supported options are:
- proxy [String] — the URL to proxy requests through
- agent [http.Agent, https.Agent] — the Agent object to perform
HTTP requests with. Used for connection pooling. Defaults to the global
agent (
http.globalAgent
) for non-SSL connections. Note that for SSL connections, a special Agent object is used in order to enable peer certificate verification. This feature is only available in the Node.js environment. - connectTimeout [Integer] — Sets the socket to timeout after
failing to establish a connection with the server after
connectTimeout
milliseconds. This timeout has no effect once a socket connection has been established. - timeout [Integer] — Sets the socket to timeout after timeout milliseconds of inactivity on the socket. Defaults to two minutes (120000).
- xhrAsync [Boolean] — Whether the SDK will send asynchronous HTTP requests. Used in the browser environment only. Set to false to send requests synchronously. Defaults to true (async on).
- xhrWithCredentials [Boolean] — Sets the "withCredentials" property of an XMLHttpRequest object. Used in the browser environment only. Defaults to false.
-
apiVersion
(String, Date)
—
a String in YYYY-MM-DD format (or a date) that represents the latest possible API version that can be used in all services (unless overridden by
apiVersions
). Specify 'latest' to use the latest possible version. -
apiVersions
(map<String, String|Date>)
—
a map of service identifiers (the lowercase service class name) with the API version to use when instantiating a service. Specify 'latest' for each individual that can use the latest available version.
-
logger
(#write, #log)
—
an object that responds to .write() (like a stream) or .log() (like the console object) in order to log information about requests
-
systemClockOffset
(Number)
—
an offset value in milliseconds to apply to all signing times. Use this to compensate for clock skew when your system may be out of sync with the service time. Note that this configuration option can only be applied to the global
AWS.config
object and cannot be overridden in service-specific configuration. Defaults to 0 milliseconds. -
signatureVersion
(String)
—
the signature version to sign requests with (overriding the API configuration). Possible values are: 'v2', 'v3', 'v4'.
-
signatureCache
(Boolean)
—
whether the signature to sign requests with (overriding the API configuration) is cached. Only applies to the signature version 'v4'. Defaults to
true
. -
dynamoDbCrc32
(Boolean)
—
whether to validate the CRC32 checksum of HTTP response bodies returned by DynamoDB. Default:
true
. -
useAccelerateEndpoint
(Boolean)
—
Whether to use the S3 Transfer Acceleration endpoint with the S3 service. Default:
false
. -
clientSideMonitoring
(Boolean)
—
whether to collect and publish this client's performance metrics of all its API requests.
-
endpointDiscoveryEnabled
(Boolean)
—
whether to enable endpoint discovery for operations that allow optionally using an endpoint returned by the service. Defaults to 'false'
-
endpointCacheSize
(Number)
—
the size of the global cache storing endpoints from endpoint discovery operations. Once endpoint cache is created, updating this setting cannot change existing cache size. Defaults to 1000
-
hostPrefixEnabled
(Boolean)
—
whether to marshal request parameters to the prefix of hostname. Defaults to
true
.
Property Details
Method Details
abortMultipartUpload(params = {}, callback) ⇒ AWS.Request
Aborts a multipart upload.
To verify that all parts have been removed, so you don't get charged for the part storage, you should call the List Parts operation and ensure the parts list is empty.
Service Reference:
Examples:
To abort a multipart upload
/* The following example aborts a multipart upload. */
var params = {
Bucket: "examplebucket",
Key: "bigobject",
UploadId: "xadcOB_7YPBOJuoFiQ9cz4P3Pe6FIZwO4f7wN93uHsNBEw97pl5eNwzExg0LAT2dUN91cOmrEQHDsP3WA60CEg--"
};
s3.abortMultipartUpload(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
}
*/
});
Calling the abortMultipartUpload operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
UploadId: 'STRING_VALUE', /* required */
RequestPayer: requester
};
s3.abortMultipartUpload(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Key
— (String
)UploadId
— (String
)RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
completeMultipartUpload(params = {}, callback) ⇒ AWS.Request
Completes a multipart upload by assembling previously uploaded parts.
Service Reference:
Examples:
To complete multipart upload
/* The following example completes a multipart upload. */
var params = {
Bucket: "examplebucket",
Key: "bigobject",
MultipartUpload: {
Parts: [
{
ETag: "\"d8c2eafd90c266e19ab9dcacc479f8af\"",
PartNumber: 1
},
{
ETag: "\"d8c2eafd90c266e19ab9dcacc479f8af\"",
PartNumber: 2
}
]
},
UploadId: "7YPBOJuoFiQ9cz4P3Pe6FIZwO4f7wN93uHsNBEw97pl5eNwzExg0LAT2dUN91cOmrEQHDsP3WA60CEg--"
};
s3.completeMultipartUpload(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Bucket: "acexamplebucket",
ETag: "\"4d9031c7644d8081c2829f4ea23c55f7-2\"",
Key: "bigobject",
Location: "https://examplebucket.s3.amazonaws.com/bigobject"
}
*/
});
Calling the completeMultipartUpload operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
UploadId: 'STRING_VALUE', /* required */
MultipartUpload: {
Parts: [
{
ETag: 'STRING_VALUE',
PartNumber: 'NUMBER_VALUE'
},
/* more items */
]
},
RequestPayer: requester
};
s3.completeMultipartUpload(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Key
— (String
)MultipartUpload
— (map
)Parts
— (Array<map>
)ETag
— (String
)Entity tag returned when the part was uploaded.
PartNumber
— (Integer
)Part number that identifies the part. This is a positive integer between 1 and 10,000.
UploadId
— (String
)RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Location
— (String
)Bucket
— (String
)Key
— (String
)Expiration
— (String
)If the object expiration is configured, this will contain the expiration date (expiry-date) and rule ID (rule-id). The value of rule-id is URL encoded.
ETag
— (String
)Entity tag of the object.
ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
VersionId
— (String
)Version of the object.
SSEKMSKeyId
— (String
)If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
copyObject(params = {}, callback) ⇒ AWS.Request
Creates a copy of an object that is already stored in Amazon S3.
Service Reference:
Examples:
To copy an object
/* The following example copies an object from one bucket to another. */
var params = {
Bucket: "destinationbucket",
CopySource: "/sourcebucket/HappyFacejpg",
Key: "HappyFaceCopyjpg"
};
s3.copyObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
CopyObjectResult: {
ETag: "\"6805f2cfc46c0f04559748bb039d69ae\"",
LastModified: <Date Representation>
}
}
*/
});
Calling the copyObject operation
var params = {
Bucket: 'STRING_VALUE', /* required */
CopySource: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
ACL: private | public-read | public-read-write | authenticated-read | aws-exec-read | bucket-owner-read | bucket-owner-full-control,
CacheControl: 'STRING_VALUE',
ContentDisposition: 'STRING_VALUE',
ContentEncoding: 'STRING_VALUE',
ContentLanguage: 'STRING_VALUE',
ContentType: 'STRING_VALUE',
CopySourceIfMatch: 'STRING_VALUE',
CopySourceIfModifiedSince: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
CopySourceIfNoneMatch: 'STRING_VALUE',
CopySourceIfUnmodifiedSince: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
CopySourceSSECustomerAlgorithm: 'STRING_VALUE',
CopySourceSSECustomerKey: new Buffer('...') || 'STRING_VALUE' /* Strings will be Base-64 encoded on your behalf */,
CopySourceSSECustomerKeyMD5: 'STRING_VALUE',
Expires: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
GrantFullControl: 'STRING_VALUE',
GrantRead: 'STRING_VALUE',
GrantReadACP: 'STRING_VALUE',
GrantWriteACP: 'STRING_VALUE',
Metadata: {
'<MetadataKey>': 'STRING_VALUE',
/* '<MetadataKey>': ... */
},
MetadataDirective: COPY | REPLACE,
ObjectLockLegalHoldStatus: ON | OFF,
ObjectLockMode: GOVERNANCE | COMPLIANCE,
ObjectLockRetainUntilDate: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
RequestPayer: requester,
SSECustomerAlgorithm: 'STRING_VALUE',
SSECustomerKey: new Buffer('...') || 'STRING_VALUE' /* Strings will be Base-64 encoded on your behalf */,
SSECustomerKeyMD5: 'STRING_VALUE',
SSEKMSKeyId: 'STRING_VALUE',
ServerSideEncryption: AES256 | aws:kms,
StorageClass: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE,
Tagging: 'STRING_VALUE',
TaggingDirective: COPY | REPLACE,
WebsiteRedirectLocation: 'STRING_VALUE'
};
s3.copyObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
ACL
— (String
)The canned ACL to apply to the object.
Possible values include:"private"
"public-read"
"public-read-write"
"authenticated-read"
"aws-exec-read"
"bucket-owner-read"
"bucket-owner-full-control"
Bucket
— (String
)CacheControl
— (String
)Specifies caching behavior along the request/reply chain.
ContentDisposition
— (String
)Specifies presentational information for the object.
ContentEncoding
— (String
)Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
ContentLanguage
— (String
)The language the content is in.
ContentType
— (String
)A standard MIME type describing the format of the object data.
CopySource
— (String
)The name of the source bucket and key name of the source object, separated by a slash (/). Must be URL-encoded.
CopySourceIfMatch
— (String
)Copies the object if its entity tag (ETag) matches the specified tag.
CopySourceIfModifiedSince
— (Date
)Copies the object if it has been modified since the specified time.
CopySourceIfNoneMatch
— (String
)Copies the object if its entity tag (ETag) is different than the specified ETag.
CopySourceIfUnmodifiedSince
— (Date
)Copies the object if it hasn't been modified since the specified time.
Expires
— (Date
)The date and time at which the object is no longer cacheable.
GrantFullControl
— (String
)Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
GrantRead
— (String
)Allows grantee to read the object data and its metadata.
GrantReadACP
— (String
)Allows grantee to read the object ACL.
GrantWriteACP
— (String
)Allows grantee to write the ACL for the applicable object.
Key
— (String
)Metadata
— (map<String>
)A map of metadata to store with the object in S3.
MetadataDirective
— (String
)Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request.
Possible values include:"COPY"
"REPLACE"
TaggingDirective
— (String
)Specifies whether the object tag-set are copied from the source object or replaced with tag-set provided in the request.
Possible values include:"COPY"
"REPLACE"
ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
StorageClass
— (String
)The type of storage to use for the object. Defaults to 'STANDARD'.
Possible values include:"STANDARD"
"REDUCED_REDUNDANCY"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"GLACIER"
"DEEP_ARCHIVE"
WebsiteRedirectLocation
— (String
)If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
SSECustomerAlgorithm
— (String
)Specifies the algorithm to use to when encrypting the object (e.g., AES256).
SSECustomerKey
— (Buffer, Typed Array, Blob, String
)Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
SSECustomerKeyMD5
— (String
)Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
SSEKMSKeyId
— (String
)Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
CopySourceSSECustomerAlgorithm
— (String
)Specifies the algorithm to use when decrypting the source object (e.g., AES256).
CopySourceSSECustomerKey
— (Buffer, Typed Array, Blob, String
)Specifies the customer-provided encryption key for Amazon S3 to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created.
CopySourceSSECustomerKeyMD5
— (String
)Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Tagging
— (String
)The tag-set for the object destination object this value must be used in conjunction with the TaggingDirective. The tag-set must be encoded as URL Query parameters
ObjectLockMode
— (String
)The Object Lock mode that you want to apply to the copied object.
Possible values include:"GOVERNANCE"
"COMPLIANCE"
ObjectLockRetainUntilDate
— (Date
)The date and time when you want the copied object's Object Lock to expire.
ObjectLockLegalHoldStatus
— (String
)Specifies whether you want to apply a Legal Hold to the copied object.
Possible values include:"ON"
"OFF"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:CopyObjectResult
— (map
)ETag
— (String
)LastModified
— (Date
)
Expiration
— (String
)If the object expiration is configured, the response includes this header.
CopySourceVersionId
— (String
)VersionId
— (String
)Version ID of the newly created copy.
ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
SSECustomerAlgorithm
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
SSECustomerKeyMD5
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
SSEKMSKeyId
— (String
)If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
createBucket(params, callback) ⇒ AWS.Request
Creates a new bucket.
Note: This operation cannot be used in a browser. S3 does not support CORS on this operation.
Service Reference:
Examples:
To create a bucket in a specific region
/* The following example creates a bucket. The request specifies an AWS region where to create the bucket. */
var params = {
Bucket: "examplebucket",
CreateBucketConfiguration: {
LocationConstraint: "eu-west-1"
}
};
s3.createBucket(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Location: "http://examplebucket.s3.amazonaws.com/"
}
*/
});
To create a bucket
/* The following example creates a bucket. */
var params = {
Bucket: "examplebucket"
};
s3.createBucket(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Location: "/examplebucket"
}
*/
});
Calling the createBucket operation
var params = {
Bucket: 'STRING_VALUE', /* required */
ACL: private | public-read | public-read-write | authenticated-read,
CreateBucketConfiguration: {
LocationConstraint: EU | eu-west-1 | us-west-1 | us-west-2 | ap-south-1 | ap-southeast-1 | ap-southeast-2 | ap-northeast-1 | sa-east-1 | cn-north-1 | eu-central-1
},
GrantFullControl: 'STRING_VALUE',
GrantRead: 'STRING_VALUE',
GrantReadACP: 'STRING_VALUE',
GrantWrite: 'STRING_VALUE',
GrantWriteACP: 'STRING_VALUE',
ObjectLockEnabledForBucket: true || false
};
s3.createBucket(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
—
ACL
— (String
)The canned ACL to apply to the bucket.
Possible values include:"private"
"public-read"
"public-read-write"
"authenticated-read"
Bucket
— (String
)CreateBucketConfiguration
— (map
)LocationConstraint
— (String
)Specifies the region where the bucket will be created. If you don't specify a region, the bucket is created in US East (N. Virginia) Region (us-east-1).
Possible values include:"EU"
"eu-west-1"
"us-west-1"
"us-west-2"
"ap-south-1"
"ap-southeast-1"
"ap-southeast-2"
"ap-northeast-1"
"sa-east-1"
"cn-north-1"
"eu-central-1"
GrantFullControl
— (String
)Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
GrantRead
— (String
)Allows grantee to list the objects in the bucket.
GrantReadACP
— (String
)Allows grantee to read the bucket ACL.
GrantWrite
— (String
)Allows grantee to create, overwrite, and delete any object in the bucket.
GrantWriteACP
— (String
)Allows grantee to write the ACL for the applicable bucket.
ObjectLockEnabledForBucket
— (Boolean
)Specifies whether you want S3 Object Lock to be enabled for the new bucket.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Location
— (String
)
-
(AWS.Response)
—
Returns:
createMultipartUpload(params = {}, callback) ⇒ AWS.Request
Initiates a multipart upload and returns an upload ID.
Note: After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, Amazon S3 frees up the parts storage and stops charging you for the parts storage.
Service Reference:
Examples:
To initiate a multipart upload
/* The following example initiates a multipart upload. */
var params = {
Bucket: "examplebucket",
Key: "largeobject"
};
s3.createMultipartUpload(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Bucket: "examplebucket",
Key: "largeobject",
UploadId: "ibZBv_75gd9r8lH_gqXatLdxMVpAlj6ZQjEs.OwyF3953YdwbcQnMA2BLGn8Lx12fQNICtMw5KyteFeHw.Sjng--"
}
*/
});
Calling the createMultipartUpload operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
ACL: private | public-read | public-read-write | authenticated-read | aws-exec-read | bucket-owner-read | bucket-owner-full-control,
CacheControl: 'STRING_VALUE',
ContentDisposition: 'STRING_VALUE',
ContentEncoding: 'STRING_VALUE',
ContentLanguage: 'STRING_VALUE',
ContentType: 'STRING_VALUE',
Expires: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
GrantFullControl: 'STRING_VALUE',
GrantRead: 'STRING_VALUE',
GrantReadACP: 'STRING_VALUE',
GrantWriteACP: 'STRING_VALUE',
Metadata: {
'<MetadataKey>': 'STRING_VALUE',
/* '<MetadataKey>': ... */
},
ObjectLockLegalHoldStatus: ON | OFF,
ObjectLockMode: GOVERNANCE | COMPLIANCE,
ObjectLockRetainUntilDate: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
RequestPayer: requester,
SSECustomerAlgorithm: 'STRING_VALUE',
SSECustomerKey: new Buffer('...') || 'STRING_VALUE' /* Strings will be Base-64 encoded on your behalf */,
SSECustomerKeyMD5: 'STRING_VALUE',
SSEKMSKeyId: 'STRING_VALUE',
ServerSideEncryption: AES256 | aws:kms,
StorageClass: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE,
Tagging: 'STRING_VALUE',
WebsiteRedirectLocation: 'STRING_VALUE'
};
s3.createMultipartUpload(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
ACL
— (String
)The canned ACL to apply to the object.
Possible values include:"private"
"public-read"
"public-read-write"
"authenticated-read"
"aws-exec-read"
"bucket-owner-read"
"bucket-owner-full-control"
Bucket
— (String
)CacheControl
— (String
)Specifies caching behavior along the request/reply chain.
ContentDisposition
— (String
)Specifies presentational information for the object.
ContentEncoding
— (String
)Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
ContentLanguage
— (String
)The language the content is in.
ContentType
— (String
)A standard MIME type describing the format of the object data.
Expires
— (Date
)The date and time at which the object is no longer cacheable.
GrantFullControl
— (String
)Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
GrantRead
— (String
)Allows grantee to read the object data and its metadata.
GrantReadACP
— (String
)Allows grantee to read the object ACL.
GrantWriteACP
— (String
)Allows grantee to write the ACL for the applicable object.
Key
— (String
)Metadata
— (map<String>
)A map of metadata to store with the object in S3.
ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
StorageClass
— (String
)The type of storage to use for the object. Defaults to 'STANDARD'.
Possible values include:"STANDARD"
"REDUCED_REDUNDANCY"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"GLACIER"
"DEEP_ARCHIVE"
WebsiteRedirectLocation
— (String
)If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
SSECustomerAlgorithm
— (String
)Specifies the algorithm to use to when encrypting the object (e.g., AES256).
SSECustomerKey
— (Buffer, Typed Array, Blob, String
)Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
SSECustomerKeyMD5
— (String
)Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
SSEKMSKeyId
— (String
)Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Tagging
— (String
)The tag-set for the object. The tag-set must be encoded as URL Query parameters
ObjectLockMode
— (String
)Specifies the Object Lock mode that you want to apply to the uploaded object.
Possible values include:"GOVERNANCE"
"COMPLIANCE"
ObjectLockRetainUntilDate
— (Date
)Specifies the date and time when you want the Object Lock to expire.
ObjectLockLegalHoldStatus
— (String
)Specifies whether you want to apply a Legal Hold to the uploaded object.
Possible values include:"ON"
"OFF"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:AbortDate
— (Date
)Date when multipart upload will become eligible for abort operation by lifecycle.
AbortRuleId
— (String
)Id of the lifecycle rule that makes a multipart upload eligible for abort operation.
Bucket
— (String
)Name of the bucket to which the multipart upload was initiated.
Key
— (String
)Object key for which the multipart upload was initiated.
UploadId
— (String
)ID for the initiated multipart upload.
ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
SSECustomerAlgorithm
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
SSECustomerKeyMD5
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
SSEKMSKeyId
— (String
)If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
createPresignedPost(params, callback) ⇒ map?
All fields passed in when creating presigned post data will be signed as exact match conditions. Any fields that will be interpolated by S3 must be added to the fields hash after signing, and an appropriate condition for such fields must be explicitly added to the Conditions array passed to this function before signing.
You must ensure that you have static or previously resolved credentials if you call this method synchronously (with no callback), otherwise it may not properly sign the request. If you cannot guarantee this (you are using an asynchronous credential provider, i.e., EC2 IAM roles), you should always call this method with an asynchronous callback.
Get a pre-signed POST policy to support uploading to S3 directly from an HTML form.
Examples:
Presiging post data with a known key
var params = {
Bucket: 'bucket',
Fields: {
key: 'key'
}
};
s3.createPresignedPost(params, function(err, data) {
if (err) {
console.error('Presigning post data encountered an error', err);
} else {
console.log('The post data is', data);
}
});
Presigning post data with an interpolated key
var params = {
Bucket: 'bucket',
Conditions: [
['starts-with', '$key', 'path/to/uploads/']
]
};
s3.createPresignedPost(params, function(err, data) {
if (err) {
console.error('Presigning post data encountered an error', err);
} else {
data.Fields.key = 'path/to/uploads/${filename}';
console.log('The post data is', data);
}
});
Parameters:
- params (map)
- callback (Function)
Callback (callback):
-
function(err, data) { ... }
Parameters:
-
err
(Error)
—
the error object returned from the policy signer
-
data
(map)
—
The data necessary to construct an HTML form
-
data.url
(String)
—
The URL to use as the action of the form
-
data.fields
(map)
—
A hash of fields that must be included in the form for the upload to succeed. This hash will include the signed POST policy, your access key ID and security token (if present), etc. These may be safely included as input elements of type 'hidden.'
-
err
(Error)
—
Options Hash (params):
-
Bucket
(String)
—
The bucket to which the post should be uploaded
-
Expires
(Integer)
— default:
3600
—
The number of seconds for which the presigned policy should be valid.
-
Conditions
(Array)
—
An array of conditions that must be met for the presigned policy to allow the upload. This can include required tags, the accepted range for content lengths, etc.
-
Fields
(map)
—
Fields to include in the form. All values passed in as fields will be signed as exact match conditions.
Returns:
-
(map)
—
If called synchronously (with no callback), returns a hash with the url to set as the form action and a hash of fields to include in the form.
-
(null)
—
Nothing is returned if a callback is provided.
See Also:
deleteBucket(params = {}, callback) ⇒ AWS.Request
Deletes the bucket. All objects (including all object versions and Delete Markers) in the bucket must be deleted before the bucket itself can be deleted.
Note: This operation cannot be used in a browser. S3 does not support CORS on this operation.
Service Reference:
Examples:
To delete a bucket
/* The following example deletes the specified bucket. */
var params = {
Bucket: "forrandall2"
};
s3.deleteBucket(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the deleteBucket operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.deleteBucket(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
deleteBucketAnalyticsConfiguration(params = {}, callback) ⇒ AWS.Request
Deletes an analytics configuration for the bucket (specified by the analytics configuration ID).
Service Reference:
Examples:
Calling the deleteBucketAnalyticsConfiguration operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Id: 'STRING_VALUE' /* required */
};
s3.deleteBucketAnalyticsConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket from which an analytics configuration is deleted.
Id
— (String
)The identifier used to represent an analytics configuration.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
deleteBucketCors(params = {}, callback) ⇒ AWS.Request
Deletes the CORS configuration information set for the bucket.
Service Reference:
Examples:
To delete cors configuration on a bucket.
/* The following example deletes CORS configuration on a bucket. */
var params = {
Bucket: "examplebucket"
};
s3.deleteBucketCors(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the deleteBucketCors operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.deleteBucketCors(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
deleteBucketEncryption(params = {}, callback) ⇒ AWS.Request
Deletes the server-side encryption configuration from the bucket.
Service Reference:
Examples:
Calling the deleteBucketEncryption operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.deleteBucketEncryption(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket containing the server-side encryption configuration to delete.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
deleteBucketInventoryConfiguration(params = {}, callback) ⇒ AWS.Request
Deletes an inventory configuration (identified by the inventory ID) from the bucket.
Service Reference:
Examples:
Calling the deleteBucketInventoryConfiguration operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Id: 'STRING_VALUE' /* required */
};
s3.deleteBucketInventoryConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket containing the inventory configuration to delete.
Id
— (String
)The ID used to identify the inventory configuration.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
deleteBucketLifecycle(params = {}, callback) ⇒ AWS.Request
Deletes the lifecycle configuration from the bucket.
Service Reference:
Examples:
To delete lifecycle configuration on a bucket.
/* The following example deletes lifecycle configuration on a bucket. */
var params = {
Bucket: "examplebucket"
};
s3.deleteBucketLifecycle(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the deleteBucketLifecycle operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.deleteBucketLifecycle(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
deleteBucketMetricsConfiguration(params = {}, callback) ⇒ AWS.Request
Deletes a metrics configuration (specified by the metrics configuration ID) from the bucket.
Service Reference:
Examples:
Calling the deleteBucketMetricsConfiguration operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Id: 'STRING_VALUE' /* required */
};
s3.deleteBucketMetricsConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket containing the metrics configuration to delete.
Id
— (String
)The ID used to identify the metrics configuration.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
deleteBucketPolicy(params = {}, callback) ⇒ AWS.Request
Deletes the policy from the bucket.
Service Reference:
Examples:
To delete bucket policy
/* The following example deletes bucket policy on the specified bucket. */
var params = {
Bucket: "examplebucket"
};
s3.deleteBucketPolicy(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the deleteBucketPolicy operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.deleteBucketPolicy(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
deleteBucketReplication(params = {}, callback) ⇒ AWS.Request
Deletes the replication configuration from the bucket. For information about replication configuration, see Cross-Region Replication (CRR) in the Amazon S3 Developer Guide.
Service Reference:
Examples:
To delete bucket replication configuration
/* The following example deletes replication configuration set on bucket. */
var params = {
Bucket: "example"
};
s3.deleteBucketReplication(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the deleteBucketReplication operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.deleteBucketReplication(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The bucket name.
Note: It can take a while to propagate the deletion of a replication configuration to all Amazon S3 systems.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
deleteBucketTagging(params = {}, callback) ⇒ AWS.Request
Deletes the tags from the bucket.
Service Reference:
Examples:
To delete bucket tags
/* The following example deletes bucket tags. */
var params = {
Bucket: "examplebucket"
};
s3.deleteBucketTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the deleteBucketTagging operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.deleteBucketTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
deleteBucketWebsite(params = {}, callback) ⇒ AWS.Request
This operation removes the website configuration from the bucket.
Service Reference:
Examples:
To delete bucket website configuration
/* The following example deletes bucket website configuration. */
var params = {
Bucket: "examplebucket"
};
s3.deleteBucketWebsite(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the deleteBucketWebsite operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.deleteBucketWebsite(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
deleteObject(params = {}, callback) ⇒ AWS.Request
Removes the null version (if there is one) of an object and inserts a delete marker, which becomes the latest version of the object. If there isn't a null version, Amazon S3 does not remove any objects.
Service Reference:
Examples:
To delete an object (from a non-versioned bucket)
/* The following example deletes an object from a non-versioned bucket. */
var params = {
Bucket: "ExampleBucket",
Key: "HappyFace.jpg"
};
s3.deleteObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
}
*/
});
To delete an object
/* The following example deletes an object from an S3 bucket. */
var params = {
Bucket: "examplebucket",
Key: "objectkey.jpg"
};
s3.deleteObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
}
*/
});
Calling the deleteObject operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
BypassGovernanceRetention: true || false,
MFA: 'STRING_VALUE',
RequestPayer: requester,
VersionId: 'STRING_VALUE'
};
s3.deleteObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Key
— (String
)MFA
— (String
)The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
VersionId
— (String
)VersionId used to reference a specific version of the object.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
BypassGovernanceRetention
— (Boolean
)Indicates whether S3 Object Lock should bypass Governance-mode restrictions to process this operation.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:DeleteMarker
— (Boolean
)Specifies whether the versioned object that was permanently deleted was (true) or was not (false) a delete marker.
VersionId
— (String
)Returns the version ID of the delete marker created as a result of the DELETE operation.
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
deleteObjects(params = {}, callback) ⇒ AWS.Request
This operation enables you to delete multiple objects from a bucket using a single HTTP request. You may specify up to 1000 keys.
Service Reference:
Examples:
To delete multiple objects from a versioned bucket
/* The following example deletes objects from a bucket. The bucket is versioned, and the request does not specify the object version to delete. In this case, all versions remain in the bucket and S3 adds a delete marker. */
var params = {
Bucket: "examplebucket",
Delete: {
Objects: [
{
Key: "objectkey1"
},
{
Key: "objectkey2"
}
],
Quiet: false
}
};
s3.deleteObjects(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Deleted: [
{
DeleteMarker: true,
DeleteMarkerVersionId: "A._w1z6EFiCF5uhtQMDal9JDkID9tQ7F",
Key: "objectkey1"
},
{
DeleteMarker: true,
DeleteMarkerVersionId: "iOd_ORxhkKe_e8G8_oSGxt2PjsCZKlkt",
Key: "objectkey2"
}
]
}
*/
});
To delete multiple object versions from a versioned bucket
/* The following example deletes objects from a bucket. The request specifies object versions. S3 deletes specific object versions and returns the key and versions of deleted objects in the response. */
var params = {
Bucket: "examplebucket",
Delete: {
Objects: [
{
Key: "HappyFace.jpg",
VersionId: "2LWg7lQLnY41.maGB5Z6SWW.dcq0vx7b"
},
{
Key: "HappyFace.jpg",
VersionId: "yoz3HB.ZhCS_tKVEmIOr7qYyyAaZSKVd"
}
],
Quiet: false
}
};
s3.deleteObjects(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Deleted: [
{
Key: "HappyFace.jpg",
VersionId: "yoz3HB.ZhCS_tKVEmIOr7qYyyAaZSKVd"
},
{
Key: "HappyFace.jpg",
VersionId: "2LWg7lQLnY41.maGB5Z6SWW.dcq0vx7b"
}
]
}
*/
});
Calling the deleteObjects operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Delete: { /* required */
Objects: [ /* required */
{
Key: 'STRING_VALUE', /* required */
VersionId: 'STRING_VALUE'
},
/* more items */
],
Quiet: true || false
},
BypassGovernanceRetention: true || false,
MFA: 'STRING_VALUE',
RequestPayer: requester
};
s3.deleteObjects(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Delete
— (map
)Objects
— required — (Array<map>
)Key
— required — (String
)Key name of the object to delete.
VersionId
— (String
)VersionId for the specific version of the object to delete.
Quiet
— (Boolean
)Element to enable quiet mode for the request. When you add this element, you must set its value to true.
MFA
— (String
)The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
BypassGovernanceRetention
— (Boolean
)Specifies whether you want to delete this object even if it has a Governance-type Object Lock in place. You must have sufficient permissions to perform this operation.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Deleted
— (Array<map>
)Key
— (String
)VersionId
— (String
)DeleteMarker
— (Boolean
)DeleteMarkerVersionId
— (String
)
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
Errors
— (Array<map>
)Key
— (String
)VersionId
— (String
)Code
— (String
)Message
— (String
)
-
(AWS.Response)
—
Returns:
deleteObjectTagging(params = {}, callback) ⇒ AWS.Request
Removes the tag-set from an existing object.
Service Reference:
Examples:
To remove tag set from an object version
/* The following example removes tag set associated with the specified object version. The request specifies both the object key and object version. */
var params = {
Bucket: "examplebucket",
Key: "HappyFace.jpg",
VersionId: "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI"
};
s3.deleteObjectTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
VersionId: "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI"
}
*/
});
To remove tag set from an object
/* The following example removes tag set associated with the specified object. If the bucket is versioning enabled, the operation removes tag set from the latest object version. */
var params = {
Bucket: "examplebucket",
Key: "HappyFace.jpg"
};
s3.deleteObjectTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
VersionId: "null"
}
*/
});
Calling the deleteObjectTagging operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
VersionId: 'STRING_VALUE'
};
s3.deleteObjectTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Key
— (String
)VersionId
— (String
)The versionId of the object that the tag-set will be removed from.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:VersionId
— (String
)The versionId of the object the tag-set was removed from.
-
(AWS.Response)
—
Returns:
deletePublicAccessBlock(params = {}, callback) ⇒ AWS.Request
Removes the PublicAccessBlock
configuration from an Amazon S3 bucket.
Service Reference:
Examples:
Calling the deletePublicAccessBlock operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.deletePublicAccessBlock(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The Amazon S3 bucket whose
PublicAccessBlock
configuration you want to delete.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
getBucketAccelerateConfiguration(params = {}, callback) ⇒ AWS.Request
Returns the accelerate configuration of a bucket.
Service Reference:
Examples:
Calling the getBucketAccelerateConfiguration operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketAccelerateConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Name of the bucket for which the accelerate configuration is retrieved.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Status
— (String
)The accelerate configuration of the bucket.
Possible values include:"Enabled"
"Suspended"
-
(AWS.Response)
—
Returns:
getBucketAcl(params = {}, callback) ⇒ AWS.Request
Gets the access control policy for the bucket.
Service Reference:
Examples:
Calling the getBucketAcl operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketAcl(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Owner
— (map
)DisplayName
— (String
)ID
— (String
)
Grants
— (Array<map>
)A list of grants.
Grantee
— (map
)DisplayName
— (String
)Screen name of the grantee.
EmailAddress
— (String
)Email address of the grantee.
ID
— (String
)The canonical user ID of the grantee.
Type
— required — (String
)Type of grantee
Possible values include:"CanonicalUser"
"AmazonCustomerByEmail"
"Group"
URI
— (String
)URI of the grantee group.
Permission
— (String
)Specifies the permission given to the grantee.
Possible values include:"FULL_CONTROL"
"WRITE"
"WRITE_ACP"
"READ"
"READ_ACP"
-
(AWS.Response)
—
Returns:
getBucketAnalyticsConfiguration(params = {}, callback) ⇒ AWS.Request
Gets an analytics configuration for the bucket (specified by the analytics configuration ID).
Service Reference:
Examples:
Calling the getBucketAnalyticsConfiguration operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Id: 'STRING_VALUE' /* required */
};
s3.getBucketAnalyticsConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket from which an analytics configuration is retrieved.
Id
— (String
)The identifier used to represent an analytics configuration.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:AnalyticsConfiguration
— (map
)The configuration and any analyses for the analytics filter.
Id
— required — (String
)The identifier used to represent an analytics configuration.
Filter
— (map
)The filter used to describe a set of objects for analyses. A filter must have exactly one prefix, one tag, or one conjunction (AnalyticsAndOperator). If no filter is provided, all objects will be considered in any analysis.
Prefix
— (String
)The prefix to use when evaluating an analytics filter.
Tag
— (map
)The tag to use when evaluating an analytics filter.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
And
— (map
)A conjunction (logical AND) of predicates, which is used in evaluating an analytics filter. The operator must have at least two predicates.
Prefix
— (String
)The prefix to use when evaluating an AND predicate.
Tags
— (Array<map>
)The list of tags to use when evaluating an AND predicate.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
StorageClassAnalysis
— required — (map
)If present, it indicates that data related to access patterns will be collected and made available to analyze the tradeoffs between different storage classes.
DataExport
— (map
)A container used to describe how data related to the storage class analysis should be exported.
OutputSchemaVersion
— required — (String
)The version of the output schema to use when exporting data. Must be V_1.
Possible values include:"V_1"
Destination
— required — (map
)The place to store the data for an analysis.
S3BucketDestination
— required — (map
)A destination signifying output to an S3 bucket.
Format
— required — (String
)The file format used when exporting data to Amazon S3.
Possible values include:"CSV"
BucketAccountId
— (String
)The account ID that owns the destination bucket. If no account ID is provided, the owner will not be validated prior to exporting data.
Bucket
— required — (String
)The Amazon resource name (ARN) of the bucket to which data is exported.
Prefix
— (String
)The prefix to use when exporting data. The exported data begins with this prefix.
-
(AWS.Response)
—
Returns:
getBucketCors(params = {}, callback) ⇒ AWS.Request
Returns the CORS configuration for the bucket.
Service Reference:
Examples:
To get cors configuration set on a bucket
/* The following example returns cross-origin resource sharing (CORS) configuration set on a bucket. */
var params = {
Bucket: "examplebucket"
};
s3.getBucketCors(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
CORSRules: [
{
AllowedHeaders: [
"Authorization"
],
AllowedMethods: [
"GET"
],
AllowedOrigins: [
"*"
],
MaxAgeSeconds: 3000
}
]
}
*/
});
Calling the getBucketCors operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketCors(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:CORSRules
— (Array<map>
)AllowedHeaders
— (Array<String>
)Specifies which headers are allowed in a pre-flight OPTIONS request.
AllowedMethods
— required — (Array<String>
)Identifies HTTP methods that the domain/origin specified in the rule is allowed to execute.
AllowedOrigins
— required — (Array<String>
)One or more origins you want customers to be able to access the bucket from.
ExposeHeaders
— (Array<String>
)One or more headers in the response that you want customers to be able to access from their applications (for example, from a JavaScript XMLHttpRequest object).
MaxAgeSeconds
— (Integer
)The time in seconds that your browser is to cache the preflight response for the specified resource.
-
(AWS.Response)
—
Returns:
getBucketEncryption(params = {}, callback) ⇒ AWS.Request
Returns the server-side encryption configuration of a bucket.
Service Reference:
Examples:
Calling the getBucketEncryption operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketEncryption(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket from which the server-side encryption configuration is retrieved.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:ServerSideEncryptionConfiguration
— (map
)Container for server-side encryption configuration rules. Currently S3 supports one rule only.
Rules
— required — (Array<map>
)Container for information about a particular server-side encryption configuration rule.
ApplyServerSideEncryptionByDefault
— (map
)Describes the default server-side encryption to apply to new objects in the bucket. If Put Object request does not specify any server-side encryption, this default encryption will be applied.
SSEAlgorithm
— required — (String
)Server-side encryption algorithm to use for the default encryption.
Possible values include:"AES256"
"aws:kms"
KMSMasterKeyID
— (String
)KMS master key ID to use for the default encryption. This parameter is allowed if SSEAlgorithm is aws:kms.
-
(AWS.Response)
—
Returns:
getBucketInventoryConfiguration(params = {}, callback) ⇒ AWS.Request
Returns an inventory configuration (identified by the inventory ID) from the bucket.
Service Reference:
Examples:
Calling the getBucketInventoryConfiguration operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Id: 'STRING_VALUE' /* required */
};
s3.getBucketInventoryConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket containing the inventory configuration to retrieve.
Id
— (String
)The ID used to identify the inventory configuration.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:InventoryConfiguration
— (map
)Specifies the inventory configuration.
Destination
— required — (map
)Contains information about where to publish the inventory results.
S3BucketDestination
— required — (map
)Contains the bucket name, file format, bucket owner (optional), and prefix (optional) where inventory results are published.
AccountId
— (String
)The ID of the account that owns the destination bucket.
Bucket
— required — (String
)The Amazon resource name (ARN) of the bucket where inventory results will be published.
Format
— required — (String
)Specifies the output format of the inventory results.
Possible values include:"CSV"
"ORC"
"Parquet"
Prefix
— (String
)The prefix that is prepended to all inventory results.
Encryption
— (map
)Contains the type of server-side encryption used to encrypt the inventory results.
SSES3
— (map
)Specifies the use of SSE-S3 to encrypt delivered Inventory reports.
SSEKMS
— (map
)Specifies the use of SSE-KMS to encrypt delivered Inventory reports.
KeyId
— required — (String
)Specifies the ID of the AWS Key Management Service (KMS) master encryption key to use for encrypting Inventory reports.
IsEnabled
— required — (Boolean
)Specifies whether the inventory is enabled or disabled.
Filter
— (map
)Specifies an inventory filter. The inventory only includes objects that meet the filter's criteria.
Prefix
— required — (String
)The prefix that an object must have to be included in the inventory results.
Id
— required — (String
)The ID used to identify the inventory configuration.
IncludedObjectVersions
— required — (String
)Specifies which object version(s) to included in the inventory results.
Possible values include:"All"
"Current"
OptionalFields
— (Array<String>
)Contains the optional fields that are included in the inventory results.
Schedule
— required — (map
)Specifies the schedule for generating inventory results.
Frequency
— required — (String
)Specifies how frequently inventory results are produced.
Possible values include:"Daily"
"Weekly"
-
(AWS.Response)
—
Returns:
getBucketLifecycle(params = {}, callback) ⇒ AWS.Request
No longer used, see the GetBucketLifecycleConfiguration operation.
Service Reference:
Examples:
To get a bucket acl
/* The following example gets ACL on the specified bucket. */
var params = {
Bucket: "acl1"
};
s3.getBucketLifecycle(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Rules: [
{
Expiration: {
Days: 1
},
ID: "delete logs",
Prefix: "123/",
Status: "Enabled"
}
]
}
*/
});
Calling the getBucketLifecycle operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketLifecycle(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Rules
— (Array<map>
)Expiration
— (map
)Date
— (Date
)Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
Days
— (Integer
)Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
ExpiredObjectDeleteMarker
— (Boolean
)Indicates whether Amazon S3 will remove a delete marker with no noncurrent versions. If set to true, the delete marker will be expired; if set to false the policy takes no action. This cannot be specified with Days or Date in a Lifecycle Expiration Policy.
ID
— (String
)Unique identifier for the rule. The value cannot be longer than 255 characters.
Prefix
— required — (String
)Prefix identifying one or more objects to which the rule applies.
Status
— required — (String
)If 'Enabled', the rule is currently being applied. If 'Disabled', the rule is not currently being applied.
Possible values include:"Enabled"
"Disabled"
Transition
— (map
)Date
— (Date
)Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
Days
— (Integer
)Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
StorageClass
— (String
)The class of storage used to store the object.
Possible values include:"GLACIER"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"DEEP_ARCHIVE"
NoncurrentVersionTransition
— (map
)Container for the transition rule that describes when noncurrent objects transition to the STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER or DEEP_ARCHIVE storage class. If your bucket is versioning-enabled (or versioning is suspended), you can set this action to request that Amazon S3 transition noncurrent object versions to the STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER or DEEP_ARCHIVE storage class at a specific period in the object's lifetime.
NoncurrentDays
— (Integer
)Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
StorageClass
— (String
)The class of storage used to store the object.
Possible values include:"GLACIER"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"DEEP_ARCHIVE"
NoncurrentVersionExpiration
— (map
)Specifies when noncurrent object versions expire. Upon expiration, Amazon S3 permanently deletes the noncurrent object versions. You set this lifecycle configuration action on a bucket that has versioning enabled (or suspended) to request that Amazon S3 delete noncurrent object versions at a specific period in the object's lifetime.
NoncurrentDays
— (Integer
)Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
AbortIncompleteMultipartUpload
— (map
)Specifies the days since the initiation of an Incomplete Multipart Upload that Lifecycle will wait before permanently removing all parts of the upload.
DaysAfterInitiation
— (Integer
)Indicates the number of days that must pass since initiation for Lifecycle to abort an Incomplete Multipart Upload.
-
(AWS.Response)
—
Returns:
getBucketLifecycleConfiguration(params = {}, callback) ⇒ AWS.Request
Returns the lifecycle configuration information set on the bucket.
Service Reference:
Examples:
To get lifecycle configuration on a bucket
/* The following example retrieves lifecycle configuration on set on a bucket. */
var params = {
Bucket: "examplebucket"
};
s3.getBucketLifecycleConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Rules: [
{
ID: "Rule for TaxDocs/",
Prefix: "TaxDocs",
Status: "Enabled",
Transitions: [
{
Days: 365,
StorageClass: "STANDARD_IA"
}
]
}
]
}
*/
});
Calling the getBucketLifecycleConfiguration operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketLifecycleConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Rules
— (Array<map>
)Expiration
— (map
)Date
— (Date
)Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
Days
— (Integer
)Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
ExpiredObjectDeleteMarker
— (Boolean
)Indicates whether Amazon S3 will remove a delete marker with no noncurrent versions. If set to true, the delete marker will be expired; if set to false the policy takes no action. This cannot be specified with Days or Date in a Lifecycle Expiration Policy.
ID
— (String
)Unique identifier for the rule. The value cannot be longer than 255 characters.
Prefix
— (String
)Prefix identifying one or more objects to which the rule applies. This is No longer used; use Filter instead.
Filter
— (map
)The Filter is used to identify objects that a Lifecycle Rule applies to. A Filter must have exactly one of Prefix, Tag, or And specified.
Prefix
— (String
)Prefix identifying one or more objects to which the rule applies.
Tag
— (map
)This tag must exist in the object's tag set in order for the rule to apply.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
And
— (map
)This is used in a Lifecycle Rule Filter to apply a logical AND to two or more predicates. The Lifecycle Rule will apply to any object matching all of the predicates configured inside the And operator.
Prefix
— (String
)Tags
— (Array<map>
)All of these tags must exist in the object's tag set in order for the rule to apply.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
Status
— required — (String
)If 'Enabled', the rule is currently being applied. If 'Disabled', the rule is not currently being applied.
Possible values include:"Enabled"
"Disabled"
Transitions
— (Array<map>
)Date
— (Date
)Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
Days
— (Integer
)Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
StorageClass
— (String
)The class of storage used to store the object.
Possible values include:"GLACIER"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"DEEP_ARCHIVE"
NoncurrentVersionTransitions
— (Array<map>
)NoncurrentDays
— (Integer
)Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
StorageClass
— (String
)The class of storage used to store the object.
Possible values include:"GLACIER"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"DEEP_ARCHIVE"
NoncurrentVersionExpiration
— (map
)Specifies when noncurrent object versions expire. Upon expiration, Amazon S3 permanently deletes the noncurrent object versions. You set this lifecycle configuration action on a bucket that has versioning enabled (or suspended) to request that Amazon S3 delete noncurrent object versions at a specific period in the object's lifetime.
NoncurrentDays
— (Integer
)Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
AbortIncompleteMultipartUpload
— (map
)Specifies the days since the initiation of an Incomplete Multipart Upload that Lifecycle will wait before permanently removing all parts of the upload.
DaysAfterInitiation
— (Integer
)Indicates the number of days that must pass since initiation for Lifecycle to abort an Incomplete Multipart Upload.
-
(AWS.Response)
—
Returns:
getBucketLocation(params = {}, callback) ⇒ AWS.Request
Returns the region the bucket resides in.
Service Reference:
Examples:
To get bucket location
/* The following example returns bucket location. */
var params = {
Bucket: "examplebucket"
};
s3.getBucketLocation(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
LocationConstraint: "us-west-2"
}
*/
});
Calling the getBucketLocation operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketLocation(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:LocationConstraint
— (String
)Possible values include:
"EU"
"eu-west-1"
"us-west-1"
"us-west-2"
"ap-south-1"
"ap-southeast-1"
"ap-southeast-2"
"ap-northeast-1"
"sa-east-1"
"cn-north-1"
"eu-central-1"
-
(AWS.Response)
—
Returns:
getBucketLogging(params = {}, callback) ⇒ AWS.Request
Returns the logging status of a bucket and the permissions users have to view and modify that status. To use GET, you must be the bucket owner.
Service Reference:
Examples:
Calling the getBucketLogging operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketLogging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:LoggingEnabled
— (map
)Container for logging information. Presence of this element indicates that logging is enabled. Parameters TargetBucket and TargetPrefix are required in this case.
TargetBucket
— required — (String
)Specifies the bucket where you want Amazon S3 to store server access logs. You can have your logs delivered to any bucket that you own, including the same bucket that is being logged. You can also configure multiple buckets to deliver their logs to the same target bucket. In this case you should choose a different TargetPrefix for each source bucket so that the delivered log files can be distinguished by key.
TargetGrants
— (Array<map>
)Grantee
— (map
)DisplayName
— (String
)Screen name of the grantee.
EmailAddress
— (String
)Email address of the grantee.
ID
— (String
)The canonical user ID of the grantee.
Type
— required — (String
)Type of grantee
Possible values include:"CanonicalUser"
"AmazonCustomerByEmail"
"Group"
URI
— (String
)URI of the grantee group.
Permission
— (String
)Logging permissions assigned to the Grantee for the bucket.
Possible values include:"FULL_CONTROL"
"READ"
"WRITE"
TargetPrefix
— required — (String
)This element lets you specify a prefix for the keys that the log files will be stored under.
-
(AWS.Response)
—
Returns:
getBucketMetricsConfiguration(params = {}, callback) ⇒ AWS.Request
Gets a metrics configuration (specified by the metrics configuration ID) from the bucket.
Service Reference:
Examples:
Calling the getBucketMetricsConfiguration operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Id: 'STRING_VALUE' /* required */
};
s3.getBucketMetricsConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket containing the metrics configuration to retrieve.
Id
— (String
)The ID used to identify the metrics configuration.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:MetricsConfiguration
— (map
)Specifies the metrics configuration.
Id
— required — (String
)The ID used to identify the metrics configuration.
Filter
— (map
)Specifies a metrics configuration filter. The metrics configuration will only include objects that meet the filter's criteria. A filter must be a prefix, a tag, or a conjunction (MetricsAndOperator).
Prefix
— (String
)The prefix used when evaluating a metrics filter.
Tag
— (map
)The tag used when evaluating a metrics filter.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
And
— (map
)A conjunction (logical AND) of predicates, which is used in evaluating a metrics filter. The operator must have at least two predicates, and an object must match all of the predicates in order for the filter to apply.
Prefix
— (String
)The prefix used when evaluating an AND predicate.
Tags
— (Array<map>
)The list of tags used when evaluating an AND predicate.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
-
(AWS.Response)
—
Returns:
getBucketNotification(params = {}, callback) ⇒ AWS.Request
No longer used, see the GetBucketNotificationConfiguration operation.
Service Reference:
Examples:
To get notification configuration set on a bucket
/* The following example returns notification configuration set on a bucket. */
var params = {
Bucket: "examplebucket"
};
s3.getBucketNotification(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
QueueConfiguration: {
Event: "s3:ObjectCreated:Put",
Events: [
"s3:ObjectCreated:Put"
],
Id: "MDQ2OGQ4NDEtOTBmNi00YTM4LTk0NzYtZDIwN2I3NWQ1NjIx",
Queue: "arn:aws:sqs:us-east-1:acct-id:S3ObjectCreatedEventQueue"
},
TopicConfiguration: {
Event: "s3:ObjectCreated:Copy",
Events: [
"s3:ObjectCreated:Copy"
],
Id: "YTVkMWEzZGUtNTY1NS00ZmE2LWJjYjktMmRlY2QwODFkNTJi",
Topic: "arn:aws:sns:us-east-1:acct-id:S3ObjectCreatedEventTopic"
}
}
*/
});
To get notification configuration set on a bucket
/* The following example returns notification configuration set on a bucket. */
var params = {
Bucket: "examplebucket"
};
s3.getBucketNotification(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
QueueConfiguration: {
Event: "s3:ObjectCreated:Put",
Events: [
"s3:ObjectCreated:Put"
],
Id: "MDQ2OGQ4NDEtOTBmNi00YTM4LTk0NzYtZDIwN2I3NWQ1NjIx",
Queue: "arn:aws:sqs:us-east-1:acct-id:S3ObjectCreatedEventQueue"
},
TopicConfiguration: {
Event: "s3:ObjectCreated:Copy",
Events: [
"s3:ObjectCreated:Copy"
],
Id: "YTVkMWEzZGUtNTY1NS00ZmE2LWJjYjktMmRlY2QwODFkNTJi",
Topic: "arn:aws:sns:us-east-1:acct-id:S3ObjectCreatedEventTopic"
}
}
*/
});
Calling the getBucketNotification operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketNotification(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Name of the bucket to get the notification configuration for.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:TopicConfiguration
— (map
)Id
— (String
)An optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
Events
— (Array<String>
)Event
— (String
)Bucket event for which to send notifications.
Possible values include:"s3:ReducedRedundancyLostObject"
"s3:ObjectCreated:*"
"s3:ObjectCreated:Put"
"s3:ObjectCreated:Post"
"s3:ObjectCreated:Copy"
"s3:ObjectCreated:CompleteMultipartUpload"
"s3:ObjectRemoved:*"
"s3:ObjectRemoved:Delete"
"s3:ObjectRemoved:DeleteMarkerCreated"
"s3:ObjectRestore:Post"
"s3:ObjectRestore:Completed"
Topic
— (String
)Amazon SNS topic to which Amazon S3 will publish a message to report the specified events for the bucket.
QueueConfiguration
— (map
)Id
— (String
)An optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
Event
— (String
)The bucket event for which to send notifications.
Possible values include:"s3:ReducedRedundancyLostObject"
"s3:ObjectCreated:*"
"s3:ObjectCreated:Put"
"s3:ObjectCreated:Post"
"s3:ObjectCreated:Copy"
"s3:ObjectCreated:CompleteMultipartUpload"
"s3:ObjectRemoved:*"
"s3:ObjectRemoved:Delete"
"s3:ObjectRemoved:DeleteMarkerCreated"
"s3:ObjectRestore:Post"
"s3:ObjectRestore:Completed"
Events
— (Array<String>
)Queue
— (String
)
CloudFunctionConfiguration
— (map
)Id
— (String
)An optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
Event
— (String
)The bucket event for which to send notifications.
Possible values include:"s3:ReducedRedundancyLostObject"
"s3:ObjectCreated:*"
"s3:ObjectCreated:Put"
"s3:ObjectCreated:Post"
"s3:ObjectCreated:Copy"
"s3:ObjectCreated:CompleteMultipartUpload"
"s3:ObjectRemoved:*"
"s3:ObjectRemoved:Delete"
"s3:ObjectRemoved:DeleteMarkerCreated"
"s3:ObjectRestore:Post"
"s3:ObjectRestore:Completed"
Events
— (Array<String>
)CloudFunction
— (String
)InvocationRole
— (String
)
-
(AWS.Response)
—
Returns:
getBucketNotificationConfiguration(params = {}, callback) ⇒ AWS.Request
Returns the notification configuration of a bucket.
Service Reference:
Examples:
Calling the getBucketNotificationConfiguration operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketNotificationConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Name of the bucket to get the notification configuration for.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:TopicConfigurations
— (Array<map>
)Id
— (String
)An optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
TopicArn
— required — (String
)The Amazon Resource Name (ARN) of the Amazon SNS topic to which Amazon S3 will publish a message when it detects events of the specified type.
Events
— required — (Array<String>
)Filter
— (map
)A container for object key name filtering rules. For information about key name filtering, see Configuring Event Notifications in the Amazon Simple Storage Service Developer Guide.
Key
— (map
)A container for object key name prefix and suffix filtering rules.
FilterRules
— (Array<map>
)A list of containers for the key value pair that defines the criteria for the filter rule.
Name
— (String
)The object key name prefix or suffix identifying one or more objects to which the filtering rule applies. The maximum prefix length is 1,024 characters. Overlapping prefixes and suffixes are not supported. For more information, see Configuring Event Notifications in the Amazon Simple Storage Service Developer Guide.
Possible values include:"prefix"
"suffix"
Value
— (String
)
QueueConfigurations
— (Array<map>
)Id
— (String
)An optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
QueueArn
— required — (String
)The Amazon Resource Name (ARN) of the Amazon SQS queue to which Amazon S3 will publish a message when it detects events of the specified type.
Events
— required — (Array<String>
)Filter
— (map
)A container for object key name filtering rules. For information about key name filtering, see Configuring Event Notifications in the Amazon Simple Storage Service Developer Guide.
Key
— (map
)A container for object key name prefix and suffix filtering rules.
FilterRules
— (Array<map>
)A list of containers for the key value pair that defines the criteria for the filter rule.
Name
— (String
)The object key name prefix or suffix identifying one or more objects to which the filtering rule applies. The maximum prefix length is 1,024 characters. Overlapping prefixes and suffixes are not supported. For more information, see Configuring Event Notifications in the Amazon Simple Storage Service Developer Guide.
Possible values include:"prefix"
"suffix"
Value
— (String
)
LambdaFunctionConfigurations
— (Array<map>
)Id
— (String
)An optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
LambdaFunctionArn
— required — (String
)The Amazon Resource Name (ARN) of the Lambda cloud function that Amazon S3 can invoke when it detects events of the specified type.
Events
— required — (Array<String>
)Filter
— (map
)A container for object key name filtering rules. For information about key name filtering, see Configuring Event Notifications in the Amazon Simple Storage Service Developer Guide.
Key
— (map
)A container for object key name prefix and suffix filtering rules.
FilterRules
— (Array<map>
)A list of containers for the key value pair that defines the criteria for the filter rule.
Name
— (String
)The object key name prefix or suffix identifying one or more objects to which the filtering rule applies. The maximum prefix length is 1,024 characters. Overlapping prefixes and suffixes are not supported. For more information, see Configuring Event Notifications in the Amazon Simple Storage Service Developer Guide.
Possible values include:"prefix"
"suffix"
Value
— (String
)
-
(AWS.Response)
—
Returns:
getBucketPolicy(params = {}, callback) ⇒ AWS.Request
Returns the policy of a specified bucket.
Service Reference:
Examples:
To get bucket policy
/* The following example returns bucket policy associated with a bucket. */
var params = {
Bucket: "examplebucket"
};
s3.getBucketPolicy(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Policy: "{\"Version\":\"2008-10-17\",\"Id\":\"LogPolicy\",\"Statement\":[{\"Sid\":\"Enables the log delivery group to publish logs to your bucket \",\"Effect\":\"Allow\",\"Principal\":{\"AWS\":\"111122223333\"},\"Action\":[\"s3:GetBucketAcl\",\"s3:GetObjectAcl\",\"s3:PutObject\"],\"Resource\":[\"arn:aws:s3:::policytest1/*\",\"arn:aws:s3:::policytest1\"]}]}"
}
*/
});
Calling the getBucketPolicy operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketPolicy(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Policy
— (String
)The bucket policy as a JSON document.
-
(AWS.Response)
—
Returns:
getBucketPolicyStatus(params = {}, callback) ⇒ AWS.Request
Retrieves the policy status for an Amazon S3 bucket, indicating whether the bucket is public.
Service Reference:
Examples:
Calling the getBucketPolicyStatus operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketPolicyStatus(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the Amazon S3 bucket whose policy status you want to retrieve.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:PolicyStatus
— (map
)The policy status for the specified bucket.
IsPublic
— (Boolean
)The policy status for this bucket.
TRUE
indicates that this bucket is public.FALSE
indicates that the bucket is not public.
-
(AWS.Response)
—
Returns:
getBucketReplication(params = {}, callback) ⇒ AWS.Request
Returns the replication configuration of a bucket.
Service Reference:
Examples:
To get replication configuration set on a bucket
/* The following example returns replication configuration set on a bucket. */
var params = {
Bucket: "examplebucket"
};
s3.getBucketReplication(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
ReplicationConfiguration: {
Role: "arn:aws:iam::acct-id:role/example-role",
Rules: [
{
Destination: {
Bucket: "arn:aws:s3:::destination-bucket"
},
ID: "MWIwNTkwZmItMTE3MS00ZTc3LWJkZDEtNzRmODQwYzc1OTQy",
Prefix: "Tax",
Status: "Enabled"
}
]
}
}
*/
});
Calling the getBucketReplication operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketReplication(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:ReplicationConfiguration
— (map
)A container for replication rules. You can add up to 1,000 rules. The maximum size of a replication configuration is 2 MB.
Role
— required — (String
)The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that Amazon S3 can assume when replicating the objects.
Rules
— required — (Array<map>
)A container for one or more replication rules. A replication configuration must have at least one rule and can contain a maximum of 1,000 rules.
ID
— (String
)A unique identifier for the rule. The maximum value is 255 characters.
Priority
— (Integer
)The priority associated with the rule. If you specify multiple rules in a replication configuration, Amazon S3 prioritizes the rules to prevent conflicts when filtering. If two or more rules identify the same object based on a specified filter, the rule with higher priority takes precedence. For example:
-
Same object quality prefix based filter criteria If prefixes you specified in multiple rules overlap
-
Same object qualify tag based filter criteria specified in multiple rules
For more information, see Cross-Region Replication (CRR) in the Amazon S3 Developer Guide.
-
Prefix
— (String
)An object keyname prefix that identifies the object or objects to which the rule applies. The maximum prefix length is 1,024 characters.
Filter
— (map
)A filter that identifies the subset of objects to which the replication rule applies. A
Filter
must specify exactly onePrefix
,Tag
, or anAnd
child element.Prefix
— (String
)An object keyname prefix that identifies the subset of objects to which the rule applies.
Tag
— (map
)A container for specifying a tag key and value.
The rule applies only to objects that have the tag in their tag set.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
And
— (map
)A container for specifying rule filters. The filters determine the subset of objects to which the rule applies. This element is required only if you specify more than one filter. For example:
-
If you specify both a
Prefix
and aTag
filter, wrap these filters in anAnd
tag. -
If you specify a filter based on multiple tags, wrap the
Tag
elements in anAnd
tag.
Prefix
— (String
)Tags
— (Array<map>
)Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
-
Status
— required — (String
)If status isn't enabled, the rule is ignored.
Possible values include:"Enabled"
"Disabled"
SourceSelectionCriteria
— (map
)A container that describes additional filters for identifying the source objects that you want to replicate. You can choose to enable or disable the replication of these objects. Currently, Amazon S3 supports only the filter that you can specify for objects created with server-side encryption using an AWS KMS-Managed Key (SSE-KMS).
If you want Amazon S3 to replicate objects created with server-side encryption using AWS KMS-Managed Keys.
SseKmsEncryptedObjects
— (map
)A container for filter information for the selection of S3 objects encrypted with AWS KMS. If you include
SourceSelectionCriteria
in the replication configuration, this element is required.Status
— required — (String
)If the status is not
Possible values include:Enabled
, replication for S3 objects encrypted with AWS KMS is disabled."Enabled"
"Disabled"
Destination
— required — (map
)A container for information about the replication destination.
Bucket
— required — (String
)The Amazon Resource Name (ARN) of the bucket where you want Amazon S3 to store replicas of the object identified by the rule.
If there are multiple rules in your replication configuration, all rules must specify the same bucket as the destination. A replication configuration can replicate objects to only one destination bucket.
Account
— (String
)The account ID of the destination bucket. Currently, Amazon S3 verifies this value only if Access Control Translation is enabled.
In a cross-account scenario, if you change replica ownership to the AWS account that owns the destination bucket by adding the
AccessControlTranslation
element, this is the account ID of the owner of the destination bucket.StorageClass
— (String
)The class of storage used to store the object. By default Amazon S3 uses storage class of the source object when creating a replica.
Possible values include:"STANDARD"
"REDUCED_REDUNDANCY"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"GLACIER"
"DEEP_ARCHIVE"
AccessControlTranslation
— (map
)A container for information about access control for replicas.
Use this element only in a cross-account scenario where source and destination bucket owners are not the same to change replica ownership to the AWS account that owns the destination bucket. If you don't add this element to the replication configuration, the replicas are owned by same AWS account that owns the source object.
Owner
— required — (String
)The override value for the owner of the replica object.
Possible values include:"Destination"
EncryptionConfiguration
— (map
)A container that provides information about encryption. If
SourceSelectionCriteria
is specified, you must specify this element.ReplicaKmsKeyID
— (String
)The ID of the AWS KMS key for the AWS Region where the destination bucket resides. Amazon S3 uses this key to encrypt the replica object.
DeleteMarkerReplication
— (map
)Specifies whether Amazon S3 should replicate delete makers.
Status
— (String
)The status of the delete marker replication.
Note: In the current implementation, Amazon S3 doesn't replicate the delete markers. The status must bePossible values include:Disabled
."Enabled"
"Disabled"
-
(AWS.Response)
—
Returns:
getBucketRequestPayment(params = {}, callback) ⇒ AWS.Request
Returns the request payment configuration of a bucket.
Service Reference:
Examples:
To get bucket versioning configuration
/* The following example retrieves bucket versioning configuration. */
var params = {
Bucket: "examplebucket"
};
s3.getBucketRequestPayment(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Payer: "BucketOwner"
}
*/
});
Calling the getBucketRequestPayment operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketRequestPayment(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Payer
— (String
)Specifies who pays for the download and request fees.
Possible values include:"Requester"
"BucketOwner"
-
(AWS.Response)
—
Returns:
getBucketTagging(params = {}, callback) ⇒ AWS.Request
Returns the tag set associated with the bucket.
Service Reference:
Examples:
To get tag set associated with a bucket
/* The following example returns tag set associated with a bucket */
var params = {
Bucket: "examplebucket"
};
s3.getBucketTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
TagSet: [
{
Key: "key1",
Value: "value1"
},
{
Key: "key2",
Value: "value2"
}
]
}
*/
});
Calling the getBucketTagging operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:TagSet
— (Array<map>
)Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
-
(AWS.Response)
—
Returns:
getBucketVersioning(params = {}, callback) ⇒ AWS.Request
Returns the versioning state of a bucket.
Service Reference:
Examples:
To get bucket versioning configuration
/* The following example retrieves bucket versioning configuration. */
var params = {
Bucket: "examplebucket"
};
s3.getBucketVersioning(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
MFADelete: "Disabled",
Status: "Enabled"
}
*/
});
Calling the getBucketVersioning operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketVersioning(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Status
— (String
)The versioning state of the bucket.
Possible values include:"Enabled"
"Suspended"
MFADelete
— (String
)Specifies whether MFA delete is enabled in the bucket versioning configuration. This element is only returned if the bucket has been configured with MFA delete. If the bucket has never been so configured, this element is not returned.
Possible values include:"Enabled"
"Disabled"
-
(AWS.Response)
—
Returns:
getBucketWebsite(params = {}, callback) ⇒ AWS.Request
Returns the website configuration for a bucket.
Service Reference:
Examples:
To get bucket website configuration
/* The following example retrieves website configuration of a bucket. */
var params = {
Bucket: "examplebucket"
};
s3.getBucketWebsite(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
ErrorDocument: {
Key: "error.html"
},
IndexDocument: {
Suffix: "index.html"
}
}
*/
});
Calling the getBucketWebsite operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketWebsite(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:RedirectAllRequestsTo
— (map
)HostName
— required — (String
)Name of the host where requests will be redirected.
Protocol
— (String
)Protocol to use (http, https) when redirecting requests. The default is the protocol that is used in the original request.
Possible values include:"http"
"https"
IndexDocument
— (map
)Suffix
— required — (String
)A suffix that is appended to a request that is for a directory on the website endpoint (e.g. if the suffix is index.html and you make a request to samplebucket/images/ the data that is returned will be for the object with the key name images/index.html) The suffix must not be empty and must not include a slash character.
ErrorDocument
— (map
)Key
— required — (String
)The object key name to use when a 4XX class error occurs.
RoutingRules
— (Array<map>
)Condition
— (map
)A container for describing a condition that must be met for the specified redirect to apply. For example, 1. If request is for pages in the /docs folder, redirect to the /documents folder. 2. If request results in HTTP error 4xx, redirect request to another host where you might process the error.
HttpErrorCodeReturnedEquals
— (String
)The HTTP error code when the redirect is applied. In the event of an error, if the error code equals this value, then the specified redirect is applied. Required when parent element Condition is specified and sibling KeyPrefixEquals is not specified. If both are specified, then both must be true for the redirect to be applied.
KeyPrefixEquals
— (String
)The object key name prefix when the redirect is applied. For example, to redirect requests for ExamplePage.html, the key prefix will be ExamplePage.html. To redirect request for all pages with the prefix docs/, the key prefix will be /docs, which identifies all objects in the docs/ folder. Required when the parent element Condition is specified and sibling HttpErrorCodeReturnedEquals is not specified. If both conditions are specified, both must be true for the redirect to be applied.
Redirect
— required — (map
)Container for redirect information. You can redirect requests to another host, to another page, or with another protocol. In the event of an error, you can specify a different error code to return.
HostName
— (String
)The host name to use in the redirect request.
HttpRedirectCode
— (String
)The HTTP redirect code to use on the response. Not required if one of the siblings is present.
Protocol
— (String
)Protocol to use (http, https) when redirecting requests. The default is the protocol that is used in the original request.
Possible values include:"http"
"https"
ReplaceKeyPrefixWith
— (String
)The object key prefix to use in the redirect request. For example, to redirect requests for all pages with prefix docs/ (objects in the docs/ folder) to documents/, you can set a condition block with KeyPrefixEquals set to docs/ and in the Redirect set ReplaceKeyPrefixWith to /documents. Not required if one of the siblings is present. Can be present only if ReplaceKeyWith is not provided.
ReplaceKeyWith
— (String
)The specific object key to use in the redirect request. For example, redirect request to error.html. Not required if one of the sibling is present. Can be present only if ReplaceKeyPrefixWith is not provided.
-
(AWS.Response)
—
Returns:
getObject(params = {}, callback) ⇒ AWS.Request
Retrieves objects from Amazon S3.
Service Reference:
Examples:
To retrieve an object
/* The following example retrieves an object for an S3 bucket. */
var params = {
Bucket: "examplebucket",
Key: "HappyFace.jpg"
};
s3.getObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
AcceptRanges: "bytes",
ContentLength: 3191,
ContentType: "image/jpeg",
ETag: "\"6805f2cfc46c0f04559748bb039d69ae\"",
LastModified: <Date Representation>,
Metadata: {
},
TagCount: 2,
VersionId: "null"
}
*/
});
To retrieve a byte range of an object
/* The following example retrieves an object for an S3 bucket. The request specifies the range header to retrieve a specific byte range. */
var params = {
Bucket: "examplebucket",
Key: "SampleFile.txt",
Range: "bytes=0-9"
};
s3.getObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
AcceptRanges: "bytes",
ContentLength: 10,
ContentRange: "bytes 0-9/43",
ContentType: "text/plain",
ETag: "\"0d94420ffd0bc68cd3d152506b97a9cc\"",
LastModified: <Date Representation>,
Metadata: {
},
VersionId: "null"
}
*/
});
Calling the getObject operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
IfMatch: 'STRING_VALUE',
IfModifiedSince: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
IfNoneMatch: 'STRING_VALUE',
IfUnmodifiedSince: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
PartNumber: 'NUMBER_VALUE',
Range: 'STRING_VALUE',
RequestPayer: requester,
ResponseCacheControl: 'STRING_VALUE',
ResponseContentDisposition: 'STRING_VALUE',
ResponseContentEncoding: 'STRING_VALUE',
ResponseContentLanguage: 'STRING_VALUE',
ResponseContentType: 'STRING_VALUE',
ResponseExpires: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
SSECustomerAlgorithm: 'STRING_VALUE',
SSECustomerKey: new Buffer('...') || 'STRING_VALUE' /* Strings will be Base-64 encoded on your behalf */,
SSECustomerKeyMD5: 'STRING_VALUE',
VersionId: 'STRING_VALUE'
};
s3.getObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)IfMatch
— (String
)Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
IfModifiedSince
— (Date
)Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
IfNoneMatch
— (String
)Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
IfUnmodifiedSince
— (Date
)Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
Key
— (String
)Range
— (String
)Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
ResponseCacheControl
— (String
)Sets the Cache-Control header of the response.
ResponseContentDisposition
— (String
)Sets the Content-Disposition header of the response
ResponseContentEncoding
— (String
)Sets the Content-Encoding header of the response.
ResponseContentLanguage
— (String
)Sets the Content-Language header of the response.
ResponseContentType
— (String
)Sets the Content-Type header of the response.
ResponseExpires
— (Date
)Sets the Expires header of the response.
VersionId
— (String
)VersionId used to reference a specific version of the object.
SSECustomerAlgorithm
— (String
)Specifies the algorithm to use to when encrypting the object (e.g., AES256).
SSECustomerKey
— (Buffer, Typed Array, Blob, String
)Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
SSECustomerKeyMD5
— (String
)Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
PartNumber
— (Integer
)Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a 'ranged' GET request for the part specified. Useful for downloading just a part of an object.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Body
— (Buffer(Node.js), Typed Array(Browser), ReadableStream
)Object data.
DeleteMarker
— (Boolean
)Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
AcceptRanges
— (String
)Expiration
— (String
)If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
Restore
— (String
)Provides information about object restoration operation and expiration time of the restored object copy.
LastModified
— (Date
)Last modified date of the object
ContentLength
— (Integer
)Size of the body in bytes.
ETag
— (String
)An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
MissingMeta
— (Integer
)This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
VersionId
— (String
)Version of the object.
CacheControl
— (String
)Specifies caching behavior along the request/reply chain.
ContentDisposition
— (String
)Specifies presentational information for the object.
ContentEncoding
— (String
)Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
ContentLanguage
— (String
)The language the content is in.
ContentRange
— (String
)The portion of the object returned in the response.
ContentType
— (String
)A standard MIME type describing the format of the object data.
Expires
— (Date
)The date and time at which the object is no longer cacheable.
WebsiteRedirectLocation
— (String
)If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
Metadata
— (map<String>
)A map of metadata to store with the object in S3.
SSECustomerAlgorithm
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
SSECustomerKeyMD5
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
SSEKMSKeyId
— (String
)If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
StorageClass
— (String
)Possible values include:
"STANDARD"
"REDUCED_REDUNDANCY"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"GLACIER"
"DEEP_ARCHIVE"
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
ReplicationStatus
— (String
)Possible values include:
"COMPLETE"
"PENDING"
"FAILED"
"REPLICA"
PartsCount
— (Integer
)The count of parts this object has.
TagCount
— (Integer
)The number of tags, if any, on the object.
ObjectLockMode
— (String
)The Object Lock mode currently in place for this object.
Possible values include:"GOVERNANCE"
"COMPLIANCE"
ObjectLockRetainUntilDate
— (Date
)The date and time when this object's Object Lock will expire.
ObjectLockLegalHoldStatus
— (String
)Indicates whether this object has an active legal hold. This field is only returned if you have permission to view an object's legal hold status.
Possible values include:"ON"
"OFF"
-
(AWS.Response)
—
Returns:
getObjectAcl(params = {}, callback) ⇒ AWS.Request
Returns the access control list (ACL) of an object.
Service Reference:
Examples:
To retrieve object ACL
/* The following example retrieves access control list (ACL) of an object. */
var params = {
Bucket: "examplebucket",
Key: "HappyFace.jpg"
};
s3.getObjectAcl(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Grants: [
{
Grantee: {
DisplayName: "owner-display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc",
Type: "CanonicalUser"
},
Permission: "WRITE"
},
{
Grantee: {
DisplayName: "owner-display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc",
Type: "CanonicalUser"
},
Permission: "WRITE_ACP"
},
{
Grantee: {
DisplayName: "owner-display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc",
Type: "CanonicalUser"
},
Permission: "READ"
},
{
Grantee: {
DisplayName: "owner-display-name",
ID: "852b113eexamplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc",
Type: "CanonicalUser"
},
Permission: "READ_ACP"
}
],
Owner: {
DisplayName: "owner-display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
}
}
*/
});
Calling the getObjectAcl operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
RequestPayer: requester,
VersionId: 'STRING_VALUE'
};
s3.getObjectAcl(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Key
— (String
)VersionId
— (String
)VersionId used to reference a specific version of the object.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Owner
— (map
)DisplayName
— (String
)ID
— (String
)
Grants
— (Array<map>
)A list of grants.
Grantee
— (map
)DisplayName
— (String
)Screen name of the grantee.
EmailAddress
— (String
)Email address of the grantee.
ID
— (String
)The canonical user ID of the grantee.
Type
— required — (String
)Type of grantee
Possible values include:"CanonicalUser"
"AmazonCustomerByEmail"
"Group"
URI
— (String
)URI of the grantee group.
Permission
— (String
)Specifies the permission given to the grantee.
Possible values include:"FULL_CONTROL"
"WRITE"
"WRITE_ACP"
"READ"
"READ_ACP"
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
getObjectLegalHold(params = {}, callback) ⇒ AWS.Request
Gets an object's current Legal Hold status.
Service Reference:
Examples:
Calling the getObjectLegalHold operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
RequestPayer: requester,
VersionId: 'STRING_VALUE'
};
s3.getObjectLegalHold(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The bucket containing the object whose Legal Hold status you want to retrieve.
Key
— (String
)The key name for the object whose Legal Hold status you want to retrieve.
VersionId
— (String
)The version ID of the object whose Legal Hold status you want to retrieve.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:LegalHold
— (map
)The current Legal Hold status for the specified object.
Status
— (String
)Indicates whether the specified object has a Legal Hold in place.
Possible values include:"ON"
"OFF"
-
(AWS.Response)
—
Returns:
getObjectLockConfiguration(params = {}, callback) ⇒ AWS.Request
Gets the Object Lock configuration for a bucket. The rule specified in the Object Lock configuration will be applied by default to every new object placed in the specified bucket.
Service Reference:
Examples:
Calling the getObjectLockConfiguration operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getObjectLockConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The bucket whose Object Lock configuration you want to retrieve.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:ObjectLockConfiguration
— (map
)The specified bucket's Object Lock configuration.
ObjectLockEnabled
— (String
)Indicates whether this bucket has an Object Lock configuration enabled.
Possible values include:"Enabled"
Rule
— (map
)The Object Lock rule in place for the specified object.
DefaultRetention
— (map
)The default retention period that you want to apply to new objects placed in the specified bucket.
Mode
— (String
)The default Object Lock retention mode you want to apply to new objects placed in the specified bucket.
Possible values include:"GOVERNANCE"
"COMPLIANCE"
Days
— (Integer
)The number of days that you want to specify for the default retention period.
Years
— (Integer
)The number of years that you want to specify for the default retention period.
-
(AWS.Response)
—
Returns:
getObjectRetention(params = {}, callback) ⇒ AWS.Request
Retrieves an object's retention settings.
Service Reference:
Examples:
Calling the getObjectRetention operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
RequestPayer: requester,
VersionId: 'STRING_VALUE'
};
s3.getObjectRetention(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The bucket containing the object whose retention settings you want to retrieve.
Key
— (String
)The key name for the object whose retention settings you want to retrieve.
VersionId
— (String
)The version ID for the object whose retention settings you want to retrieve.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Retention
— (map
)The container element for an object's retention settings.
Mode
— (String
)Indicates the Retention mode for the specified object.
Possible values include:"GOVERNANCE"
"COMPLIANCE"
RetainUntilDate
— (Date
)The date on which this Object Lock Retention will expire.
-
(AWS.Response)
—
Returns:
getObjectTagging(params = {}, callback) ⇒ AWS.Request
Returns the tag-set of an object.
Service Reference:
Examples:
To retrieve tag set of a specific object version
/* The following example retrieves tag set of an object. The request specifies object version. */
var params = {
Bucket: "examplebucket",
Key: "exampleobject",
VersionId: "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI"
};
s3.getObjectTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
TagSet: [
{
Key: "Key1",
Value: "Value1"
}
],
VersionId: "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI"
}
*/
});
To retrieve tag set of an object
/* The following example retrieves tag set of an object. */
var params = {
Bucket: "examplebucket",
Key: "HappyFace.jpg"
};
s3.getObjectTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
TagSet: [
{
Key: "Key4",
Value: "Value4"
},
{
Key: "Key3",
Value: "Value3"
}
],
VersionId: "null"
}
*/
});
Calling the getObjectTagging operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
VersionId: 'STRING_VALUE'
};
s3.getObjectTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Key
— (String
)VersionId
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:VersionId
— (String
)TagSet
— (Array<map>
)Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
-
(AWS.Response)
—
Returns:
getObjectTorrent(params = {}, callback) ⇒ AWS.Request
Return torrent files from a bucket.
Service Reference:
Examples:
To retrieve torrent files for an object
/* The following example retrieves torrent files of an object. */
var params = {
Bucket: "examplebucket",
Key: "HappyFace.jpg"
};
s3.getObjectTorrent(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
}
*/
});
Calling the getObjectTorrent operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
RequestPayer: requester
};
s3.getObjectTorrent(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Key
— (String
)RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Body
— (Buffer(Node.js), Typed Array(Browser), ReadableStream
)RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
getPublicAccessBlock(params = {}, callback) ⇒ AWS.Request
Retrieves the PublicAccessBlock
configuration for an Amazon S3 bucket.
Service Reference:
Examples:
Calling the getPublicAccessBlock operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.getPublicAccessBlock(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the Amazon S3 bucket whose
PublicAccessBlock
configuration you want to retrieve.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:PublicAccessBlockConfiguration
— (map
)The
PublicAccessBlock
configuration currently in effect for this Amazon S3 bucket.BlockPublicAcls
— (Boolean
)Specifies whether Amazon S3 should block public access control lists (ACLs) for this bucket and objects in this bucket. Setting this element to
TRUE
causes the following behavior:-
PUT Bucket acl and PUT Object acl calls fail if the specified ACL is public.
-
PUT Object calls fail if the request includes a public ACL.
Enabling this setting doesn't affect existing policies or ACLs.
-
IgnorePublicAcls
— (Boolean
)Specifies whether Amazon S3 should ignore public ACLs for this bucket and objects in this bucket. Setting this element to
TRUE
causes Amazon S3 to ignore all public ACLs on this bucket and objects in this bucket.Enabling this setting doesn't affect the persistence of any existing ACLs and doesn't prevent new public ACLs from being set.
BlockPublicPolicy
— (Boolean
)Specifies whether Amazon S3 should block public bucket policies for this bucket. Setting this element to
TRUE
causes Amazon S3 to reject calls to PUT Bucket policy if the specified bucket policy allows public access.Enabling this setting doesn't affect existing bucket policies.
RestrictPublicBuckets
— (Boolean
)Specifies whether Amazon S3 should restrict public bucket policies for this bucket. Setting this element to
TRUE
restricts access to this bucket to only AWS services and authorized users within this account if the bucket has a public policy.Enabling this setting doesn't affect previously stored bucket policies, except that public and cross-account access within any public bucket policy, including non-public delegation to specific accounts, is blocked.
-
(AWS.Response)
—
Returns:
getSignedUrl(operation, params, callback) ⇒ String?
You must ensure that you have static or previously resolved credentials if you call this method synchronously (with no callback), otherwise it may not properly sign the request. If you cannot guarantee this (you are using an asynchronous credential provider, i.e., EC2 IAM roles), you should always call this method with an asynchronous callback.
Not all operation parameters are supported when using pre-signed
URLs. Certain parameters, such as SSECustomerKey
, ACL
, Expires
,
ContentLength
, or Tagging
must be provided as headers when sending a
request. If you are using pre-signed URLs to upload from a browser and
need to use these fields, see createPresignedPost().
The default signer allows altering the request by adding corresponding headers to set some parameters (e.g. Range) and these added parameters won't be signed. You must use signatureVersion v4 to to include these parameters in the signed portion of the URL and enforce exact matching between headers and signed params in the URL.
This operation cannot be used with a promise. See note above regarding asynchronous credentials and use with a callback.
Get a pre-signed URL for a given operation name.
Examples:
Pre-signing a getObject operation (synchronously)
var params = {Bucket: 'bucket', Key: 'key'};
var url = s3.getSignedUrl('getObject', params);
console.log('The URL is', url);
Pre-signing a putObject (asynchronously)
var params = {Bucket: 'bucket', Key: 'key'};
s3.getSignedUrl('putObject', params, function (err, url) {
console.log('The URL is', url);
});
Pre-signing a putObject operation with a specific payload
var params = {Bucket: 'bucket', Key: 'key', Body: 'body'};
var url = s3.getSignedUrl('putObject', params);
console.log('The URL is', url);
Passing in a 1-minute expiry time for a pre-signed URL
var params = {Bucket: 'bucket', Key: 'key', Expires: 60};
var url = s3.getSignedUrl('getObject', params);
console.log('The URL is', url); // expires in 60 seconds
Parameters:
-
operation
(String)
—
the name of the operation to call
-
params
(map)
—
parameters to pass to the operation. See the given operation for the expected operation parameters. In addition, you can also pass the "Expires" parameter to inform S3 how long the URL should work for.
-
callback
(Function)
—
if a callback is provided, this function will pass the URL as the second parameter (after the error parameter) to the callback function.
Options Hash (params):
-
Expires
(Integer)
— default:
900
—
the number of seconds to expire the pre-signed URL operation in. Defaults to 15 minutes.
Returns:
-
(String)
—
if called synchronously (with no callback), returns the signed URL.
-
(null)
—
nothing is returned if a callback is provided.
headBucket(params = {}, callback) ⇒ AWS.Request
This operation is useful to determine if a bucket exists and you have permission to access it.
Service Reference:
Examples:
To determine if bucket exists
/* This operation checks to see if a bucket exists. */
var params = {
Bucket: "acl1"
};
s3.headBucket(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the headBucket operation
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.headBucket(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
Waiter Resource States:
headObject(params = {}, callback) ⇒ AWS.Request
The HEAD operation retrieves metadata from an object without returning the object itself. This operation is useful if you're only interested in an object's metadata. To use HEAD, you must have READ access to the object.
Service Reference:
Examples:
To retrieve metadata of an object without returning the object itself
/* The following example retrieves an object metadata. */
var params = {
Bucket: "examplebucket",
Key: "HappyFace.jpg"
};
s3.headObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
AcceptRanges: "bytes",
ContentLength: 3191,
ContentType: "image/jpeg",
ETag: "\"6805f2cfc46c0f04559748bb039d69ae\"",
LastModified: <Date Representation>,
Metadata: {
},
VersionId: "null"
}
*/
});
Calling the headObject operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
IfMatch: 'STRING_VALUE',
IfModifiedSince: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
IfNoneMatch: 'STRING_VALUE',
IfUnmodifiedSince: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
PartNumber: 'NUMBER_VALUE',
Range: 'STRING_VALUE',
RequestPayer: requester,
SSECustomerAlgorithm: 'STRING_VALUE',
SSECustomerKey: new Buffer('...') || 'STRING_VALUE' /* Strings will be Base-64 encoded on your behalf */,
SSECustomerKeyMD5: 'STRING_VALUE',
VersionId: 'STRING_VALUE'
};
s3.headObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)IfMatch
— (String
)Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
IfModifiedSince
— (Date
)Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
IfNoneMatch
— (String
)Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
IfUnmodifiedSince
— (Date
)Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
Key
— (String
)Range
— (String
)Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
VersionId
— (String
)VersionId used to reference a specific version of the object.
SSECustomerAlgorithm
— (String
)Specifies the algorithm to use to when encrypting the object (e.g., AES256).
SSECustomerKey
— (Buffer, Typed Array, Blob, String
)Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
SSECustomerKeyMD5
— (String
)Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
PartNumber
— (Integer
)Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a 'ranged' HEAD request for the part specified. Useful querying about the size of the part and the number of parts in this object.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:DeleteMarker
— (Boolean
)Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
AcceptRanges
— (String
)Expiration
— (String
)If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
Restore
— (String
)Provides information about object restoration operation and expiration time of the restored object copy.
LastModified
— (Date
)Last modified date of the object
ContentLength
— (Integer
)Size of the body in bytes.
ETag
— (String
)An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
MissingMeta
— (Integer
)This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
VersionId
— (String
)Version of the object.
CacheControl
— (String
)Specifies caching behavior along the request/reply chain.
ContentDisposition
— (String
)Specifies presentational information for the object.
ContentEncoding
— (String
)Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
ContentLanguage
— (String
)The language the content is in.
ContentType
— (String
)A standard MIME type describing the format of the object data.
Expires
— (Date
)The date and time at which the object is no longer cacheable.
WebsiteRedirectLocation
— (String
)If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
Metadata
— (map<String>
)A map of metadata to store with the object in S3.
SSECustomerAlgorithm
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
SSECustomerKeyMD5
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
SSEKMSKeyId
— (String
)If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
StorageClass
— (String
)Possible values include:
"STANDARD"
"REDUCED_REDUNDANCY"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"GLACIER"
"DEEP_ARCHIVE"
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
ReplicationStatus
— (String
)Possible values include:
"COMPLETE"
"PENDING"
"FAILED"
"REPLICA"
PartsCount
— (Integer
)The count of parts this object has.
ObjectLockMode
— (String
)The Object Lock mode currently in place for this object.
Possible values include:"GOVERNANCE"
"COMPLIANCE"
ObjectLockRetainUntilDate
— (Date
)The date and time when this object's Object Lock will expire.
ObjectLockLegalHoldStatus
— (String
)The Legal Hold status for the specified object.
Possible values include:"ON"
"OFF"
-
(AWS.Response)
—
Returns:
Waiter Resource States:
listBucketAnalyticsConfigurations(params = {}, callback) ⇒ AWS.Request
Lists the analytics configurations for the bucket.
Service Reference:
Examples:
Calling the listBucketAnalyticsConfigurations operation
var params = {
Bucket: 'STRING_VALUE', /* required */
ContinuationToken: 'STRING_VALUE'
};
s3.listBucketAnalyticsConfigurations(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket from which analytics configurations are retrieved.
ContinuationToken
— (String
)The ContinuationToken that represents a placeholder from where this request should begin.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:IsTruncated
— (Boolean
)Indicates whether the returned list of analytics configurations is complete. A value of true indicates that the list is not complete and the NextContinuationToken will be provided for a subsequent request.
ContinuationToken
— (String
)The ContinuationToken that represents where this request began.
NextContinuationToken
— (String
)NextContinuationToken is sent when isTruncated is true, which indicates that there are more analytics configurations to list. The next request must include this NextContinuationToken. The token is obfuscated and is not a usable value.
AnalyticsConfigurationList
— (Array<map>
)The list of analytics configurations for a bucket.
Id
— required — (String
)The identifier used to represent an analytics configuration.
Filter
— (map
)The filter used to describe a set of objects for analyses. A filter must have exactly one prefix, one tag, or one conjunction (AnalyticsAndOperator). If no filter is provided, all objects will be considered in any analysis.
Prefix
— (String
)The prefix to use when evaluating an analytics filter.
Tag
— (map
)The tag to use when evaluating an analytics filter.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
And
— (map
)A conjunction (logical AND) of predicates, which is used in evaluating an analytics filter. The operator must have at least two predicates.
Prefix
— (String
)The prefix to use when evaluating an AND predicate.
Tags
— (Array<map>
)The list of tags to use when evaluating an AND predicate.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
StorageClassAnalysis
— required — (map
)If present, it indicates that data related to access patterns will be collected and made available to analyze the tradeoffs between different storage classes.
DataExport
— (map
)A container used to describe how data related to the storage class analysis should be exported.
OutputSchemaVersion
— required — (String
)The version of the output schema to use when exporting data. Must be V_1.
Possible values include:"V_1"
Destination
— required — (map
)The place to store the data for an analysis.
S3BucketDestination
— required — (map
)A destination signifying output to an S3 bucket.
Format
— required — (String
)The file format used when exporting data to Amazon S3.
Possible values include:"CSV"
BucketAccountId
— (String
)The account ID that owns the destination bucket. If no account ID is provided, the owner will not be validated prior to exporting data.
Bucket
— required — (String
)The Amazon resource name (ARN) of the bucket to which data is exported.
Prefix
— (String
)The prefix to use when exporting data. The exported data begins with this prefix.
-
(AWS.Response)
—
Returns:
listBucketInventoryConfigurations(params = {}, callback) ⇒ AWS.Request
Returns a list of inventory configurations for the bucket.
Service Reference:
Examples:
Calling the listBucketInventoryConfigurations operation
var params = {
Bucket: 'STRING_VALUE', /* required */
ContinuationToken: 'STRING_VALUE'
};
s3.listBucketInventoryConfigurations(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket containing the inventory configurations to retrieve.
ContinuationToken
— (String
)The marker used to continue an inventory configuration listing that has been truncated. Use the NextContinuationToken from a previously truncated list response to continue the listing. The continuation token is an opaque value that Amazon S3 understands.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:ContinuationToken
— (String
)If sent in the request, the marker that is used as a starting point for this inventory configuration list response.
InventoryConfigurationList
— (Array<map>
)The list of inventory configurations for a bucket.
Destination
— required — (map
)Contains information about where to publish the inventory results.
S3BucketDestination
— required — (map
)Contains the bucket name, file format, bucket owner (optional), and prefix (optional) where inventory results are published.
AccountId
— (String
)The ID of the account that owns the destination bucket.
Bucket
— required — (String
)The Amazon resource name (ARN) of the bucket where inventory results will be published.
Format
— required — (String
)Specifies the output format of the inventory results.
Possible values include:"CSV"
"ORC"
"Parquet"
Prefix
— (String
)The prefix that is prepended to all inventory results.
Encryption
— (map
)Contains the type of server-side encryption used to encrypt the inventory results.
SSES3
— (map
)Specifies the use of SSE-S3 to encrypt delivered Inventory reports.
SSEKMS
— (map
)Specifies the use of SSE-KMS to encrypt delivered Inventory reports.
KeyId
— required — (String
)Specifies the ID of the AWS Key Management Service (KMS) master encryption key to use for encrypting Inventory reports.
IsEnabled
— required — (Boolean
)Specifies whether the inventory is enabled or disabled.
Filter
— (map
)Specifies an inventory filter. The inventory only includes objects that meet the filter's criteria.
Prefix
— required — (String
)The prefix that an object must have to be included in the inventory results.
Id
— required — (String
)The ID used to identify the inventory configuration.
IncludedObjectVersions
— required — (String
)Specifies which object version(s) to included in the inventory results.
Possible values include:"All"
"Current"
OptionalFields
— (Array<String>
)Contains the optional fields that are included in the inventory results.
Schedule
— required — (map
)Specifies the schedule for generating inventory results.
Frequency
— required — (String
)Specifies how frequently inventory results are produced.
Possible values include:"Daily"
"Weekly"
IsTruncated
— (Boolean
)Indicates whether the returned list of inventory configurations is truncated in this response. A value of true indicates that the list is truncated.
NextContinuationToken
— (String
)The marker used to continue this inventory configuration listing. Use the NextContinuationToken from this response to continue the listing in a subsequent request. The continuation token is an opaque value that Amazon S3 understands.
-
(AWS.Response)
—
Returns:
listBucketMetricsConfigurations(params = {}, callback) ⇒ AWS.Request
Lists the metrics configurations for the bucket.
Service Reference:
Examples:
Calling the listBucketMetricsConfigurations operation
var params = {
Bucket: 'STRING_VALUE', /* required */
ContinuationToken: 'STRING_VALUE'
};
s3.listBucketMetricsConfigurations(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket containing the metrics configurations to retrieve.
ContinuationToken
— (String
)The marker that is used to continue a metrics configuration listing that has been truncated. Use the NextContinuationToken from a previously truncated list response to continue the listing. The continuation token is an opaque value that Amazon S3 understands.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:IsTruncated
— (Boolean
)Indicates whether the returned list of metrics configurations is complete. A value of true indicates that the list is not complete and the NextContinuationToken will be provided for a subsequent request.
ContinuationToken
— (String
)The marker that is used as a starting point for this metrics configuration list response. This value is present if it was sent in the request.
NextContinuationToken
— (String
)The marker used to continue a metrics configuration listing that has been truncated. Use the NextContinuationToken from a previously truncated list response to continue the listing. The continuation token is an opaque value that Amazon S3 understands.
MetricsConfigurationList
— (Array<map>
)The list of metrics configurations for a bucket.
Id
— required — (String
)The ID used to identify the metrics configuration.
Filter
— (map
)Specifies a metrics configuration filter. The metrics configuration will only include objects that meet the filter's criteria. A filter must be a prefix, a tag, or a conjunction (MetricsAndOperator).
Prefix
— (String
)The prefix used when evaluating a metrics filter.
Tag
— (map
)The tag used when evaluating a metrics filter.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
And
— (map
)A conjunction (logical AND) of predicates, which is used in evaluating a metrics filter. The operator must have at least two predicates, and an object must match all of the predicates in order for the filter to apply.
Prefix
— (String
)The prefix used when evaluating an AND predicate.
Tags
— (Array<map>
)The list of tags used when evaluating an AND predicate.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
-
(AWS.Response)
—
Returns:
listBuckets(params = {}, callback) ⇒ AWS.Request
Returns a list of all buckets owned by the authenticated sender of the request.
Note: This operation cannot be used in a browser. S3 does not support CORS on this operation.
Service Reference:
Examples:
To list object versions
/* The following example return versions of an object with specific key name prefix. The request limits the number of items returned to two. If there are are more than two object version, S3 returns NextToken in the response. You can specify this token value in your next request to fetch next set of object versions. */
var params = {};
s3.listBuckets(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Buckets: [
{
CreationDate: <Date Representation>,
Name: "examplebucket"
},
{
CreationDate: <Date Representation>,
Name: "examplebucket2"
},
{
CreationDate: <Date Representation>,
Name: "examplebucket3"
}
],
Owner: {
DisplayName: "own-display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31"
}
}
*/
});
Calling the listBuckets operation
s3.listBuckets(function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
- params (Object) (defaults to: {})
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Buckets
— (Array<map>
)Name
— (String
)The name of the bucket.
CreationDate
— (Date
)Date the bucket was created.
Owner
— (map
)DisplayName
— (String
)ID
— (String
)
-
(AWS.Response)
—
Returns:
listMultipartUploads(params = {}, callback) ⇒ AWS.Request
This operation lists in-progress multipart uploads.
Service Reference:
Examples:
To list in-progress multipart uploads on a bucket
/* The following example lists in-progress multipart uploads on a specific bucket. */
var params = {
Bucket: "examplebucket"
};
s3.listMultipartUploads(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Uploads: [
{
Initiated: <Date Representation>,
Initiator: {
DisplayName: "display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
Key: "JavaFile",
Owner: {
DisplayName: "display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
StorageClass: "STANDARD",
UploadId: "examplelUa.CInXklLQtSMJITdUnoZ1Y5GACB5UckOtspm5zbDMCkPF_qkfZzMiFZ6dksmcnqxJyIBvQMG9X9Q--"
},
{
Initiated: <Date Representation>,
Initiator: {
DisplayName: "display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
Key: "JavaFile",
Owner: {
DisplayName: "display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
StorageClass: "STANDARD",
UploadId: "examplelo91lv1iwvWpvCiJWugw2xXLPAD7Z8cJyX9.WiIRgNrdG6Ldsn.9FtS63TCl1Uf5faTB.1U5Ckcbmdw--"
}
]
}
*/
});
List next set of multipart uploads when previous result is truncated
/* The following example specifies the upload-id-marker and key-marker from previous truncated response to retrieve next setup of multipart uploads. */
var params = {
Bucket: "examplebucket",
KeyMarker: "nextkeyfrompreviousresponse",
MaxUploads: 2,
UploadIdMarker: "valuefrompreviousresponse"
};
s3.listMultipartUploads(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Bucket: "acl1",
IsTruncated: true,
KeyMarker: "",
MaxUploads: 2,
NextKeyMarker: "someobjectkey",
NextUploadIdMarker: "examplelo91lv1iwvWpvCiJWugw2xXLPAD7Z8cJyX9.WiIRgNrdG6Ldsn.9FtS63TCl1Uf5faTB.1U5Ckcbmdw--",
UploadIdMarker: "",
Uploads: [
{
Initiated: <Date Representation>,
Initiator: {
DisplayName: "ownder-display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
Key: "JavaFile",
Owner: {
DisplayName: "mohanataws",
ID: "852b113e7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
StorageClass: "STANDARD",
UploadId: "gZ30jIqlUa.CInXklLQtSMJITdUnoZ1Y5GACB5UckOtspm5zbDMCkPF_qkfZzMiFZ6dksmcnqxJyIBvQMG9X9Q--"
},
{
Initiated: <Date Representation>,
Initiator: {
DisplayName: "ownder-display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
Key: "JavaFile",
Owner: {
DisplayName: "ownder-display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
StorageClass: "STANDARD",
UploadId: "b7tZSqIlo91lv1iwvWpvCiJWugw2xXLPAD7Z8cJyX9.WiIRgNrdG6Ldsn.9FtS63TCl1Uf5faTB.1U5Ckcbmdw--"
}
]
}
*/
});
Calling the listMultipartUploads operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Delimiter: 'STRING_VALUE',
EncodingType: url,
KeyMarker: 'STRING_VALUE',
MaxUploads: 'NUMBER_VALUE',
Prefix: 'STRING_VALUE',
UploadIdMarker: 'STRING_VALUE'
};
s3.listMultipartUploads(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Delimiter
— (String
)Character you use to group keys.
EncodingType
— (String
)Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.
Possible values include:"url"
KeyMarker
— (String
)Together with upload-id-marker, this parameter specifies the multipart upload after which listing should begin.
MaxUploads
— (Integer
)Sets the maximum number of multipart uploads, from 1 to 1,000, to return in the response body. 1,000 is the maximum number of uploads that can be returned in a response.
Prefix
— (String
)Lists in-progress uploads only for those keys that begin with the specified prefix.
UploadIdMarker
— (String
)Together with key-marker, specifies the multipart upload after which listing should begin. If key-marker is not specified, the upload-id-marker parameter is ignored.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Bucket
— (String
)Name of the bucket to which the multipart upload was initiated.
KeyMarker
— (String
)The key at or after which the listing began.
UploadIdMarker
— (String
)Upload ID after which listing began.
NextKeyMarker
— (String
)When a list is truncated, this element specifies the value that should be used for the key-marker request parameter in a subsequent request.
Prefix
— (String
)When a prefix is provided in the request, this field contains the specified prefix. The result contains only keys starting with the specified prefix.
Delimiter
— (String
)NextUploadIdMarker
— (String
)When a list is truncated, this element specifies the value that should be used for the upload-id-marker request parameter in a subsequent request.
MaxUploads
— (Integer
)Maximum number of multipart uploads that could have been included in the response.
IsTruncated
— (Boolean
)Indicates whether the returned list of multipart uploads is truncated. A value of true indicates that the list was truncated. The list can be truncated if the number of multipart uploads exceeds the limit allowed or specified by max uploads.
Uploads
— (Array<map>
)UploadId
— (String
)Upload ID that identifies the multipart upload.
Key
— (String
)Key of the object for which the multipart upload was initiated.
Initiated
— (Date
)Date and time at which the multipart upload was initiated.
StorageClass
— (String
)The class of storage used to store the object.
Possible values include:"STANDARD"
"REDUCED_REDUNDANCY"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"GLACIER"
"DEEP_ARCHIVE"
Owner
— (map
)DisplayName
— (String
)ID
— (String
)
Initiator
— (map
)Identifies who initiated the multipart upload.
ID
— (String
)If the principal is an AWS account, it provides the Canonical User ID. If the principal is an IAM User, it provides a user ARN value.
DisplayName
— (String
)Name of the Principal.
CommonPrefixes
— (Array<map>
)Prefix
— (String
)
EncodingType
— (String
)Encoding type used by Amazon S3 to encode object keys in the response.
Possible values include:"url"
-
(AWS.Response)
—
Returns:
listObjects(params = {}, callback) ⇒ AWS.Request
Returns some or all (up to 1000) of the objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket.
Service Reference:
Examples:
To list objects in a bucket
/* The following example list two objects in a bucket. */
var params = {
Bucket: "examplebucket",
MaxKeys: 2
};
s3.listObjects(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Contents: [
{
ETag: "\"70ee1738b6b21e2c8a43f3a5ab0eee71\"",
Key: "example1.jpg",
LastModified: <Date Representation>,
Owner: {
DisplayName: "myname",
ID: "12345example25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
Size: 11,
StorageClass: "STANDARD"
},
{
ETag: "\"9c8af9a76df052144598c115ef33e511\"",
Key: "example2.jpg",
LastModified: <Date Representation>,
Owner: {
DisplayName: "myname",
ID: "12345example25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
Size: 713193,
StorageClass: "STANDARD"
}
],
NextMarker: "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAyfQ=="
}
*/
});
Calling the listObjects operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Delimiter: 'STRING_VALUE',
EncodingType: url,
Marker: 'STRING_VALUE',
MaxKeys: 'NUMBER_VALUE',
Prefix: 'STRING_VALUE',
RequestPayer: requester
};
s3.listObjects(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Delimiter
— (String
)A delimiter is a character you use to group keys.
EncodingType
— (String
)Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.
Possible values include:"url"
Marker
— (String
)Specifies the key to start with when listing objects in a bucket.
MaxKeys
— (Integer
)Sets the maximum number of keys returned in the response. The response might contain fewer keys but will never contain more.
Prefix
— (String
)Limits the response to keys that begin with the specified prefix.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the list objects request. Bucket owners need not specify this parameter in their requests.
Possible values include:"requester"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:IsTruncated
— (Boolean
)A flag that indicates whether or not Amazon S3 returned all of the results that satisfied the search criteria.
Marker
— (String
)NextMarker
— (String
)When response is truncated (the IsTruncated element value in the response is true), you can use the key name in this field as marker in the subsequent request to get next set of objects. Amazon S3 lists objects in alphabetical order Note: This element is returned only if you have delimiter request parameter specified. If response does not include the NextMaker and it is truncated, you can use the value of the last Key in the response as the marker in the subsequent request to get the next set of object keys.
Contents
— (Array<map>
)Key
— (String
)LastModified
— (Date
)ETag
— (String
)Size
— (Integer
)StorageClass
— (String
)The class of storage used to store the object.
Possible values include:"STANDARD"
"REDUCED_REDUNDANCY"
"GLACIER"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"DEEP_ARCHIVE"
Owner
— (map
)DisplayName
— (String
)ID
— (String
)
Name
— (String
)Prefix
— (String
)Delimiter
— (String
)MaxKeys
— (Integer
)CommonPrefixes
— (Array<map>
)Prefix
— (String
)
EncodingType
— (String
)Encoding type used by Amazon S3 to encode object keys in the response.
Possible values include:"url"
-
(AWS.Response)
—
Returns:
listObjectsV2(params = {}, callback) ⇒ AWS.Request
Returns some or all (up to 1000) of the objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket. Note: ListObjectsV2 is the revised List Objects API and we recommend you use this revised API for new application development.
Service Reference:
Examples:
To get object list
/* The following example retrieves object list. The request specifies max keys to limit response to include only 2 object keys. */
var params = {
Bucket: "examplebucket",
MaxKeys: 2
};
s3.listObjectsV2(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Contents: [
{
ETag: "\"70ee1738b6b21e2c8a43f3a5ab0eee71\"",
Key: "happyface.jpg",
LastModified: <Date Representation>,
Size: 11,
StorageClass: "STANDARD"
},
{
ETag: "\"becf17f89c30367a9a44495d62ed521a-1\"",
Key: "test.jpg",
LastModified: <Date Representation>,
Size: 4192256,
StorageClass: "STANDARD"
}
],
IsTruncated: true,
KeyCount: 2,
MaxKeys: 2,
Name: "examplebucket",
NextContinuationToken: "1w41l63U0xa8q7smH50vCxyTQqdxo69O3EmK28Bi5PcROI4wI/EyIJg==",
Prefix: ""
}
*/
});
Calling the listObjectsV2 operation
var params = {
Bucket: 'STRING_VALUE', /* required */
ContinuationToken: 'STRING_VALUE',
Delimiter: 'STRING_VALUE',
EncodingType: url,
FetchOwner: true || false,
MaxKeys: 'NUMBER_VALUE',
Prefix: 'STRING_VALUE',
RequestPayer: requester,
StartAfter: 'STRING_VALUE'
};
s3.listObjectsV2(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Name of the bucket to list.
Delimiter
— (String
)A delimiter is a character you use to group keys.
EncodingType
— (String
)Encoding type used by Amazon S3 to encode object keys in the response.
Possible values include:"url"
MaxKeys
— (Integer
)Sets the maximum number of keys returned in the response. The response might contain fewer keys but will never contain more.
Prefix
— (String
)Limits the response to keys that begin with the specified prefix.
ContinuationToken
— (String
)ContinuationToken indicates Amazon S3 that the list is being continued on this bucket with a token. ContinuationToken is obfuscated and is not a real key
FetchOwner
— (Boolean
)The owner field is not present in listV2 by default, if you want to return owner field with each key in the result then set the fetch owner field to true
StartAfter
— (String
)StartAfter is where you want Amazon S3 to start listing from. Amazon S3 starts listing after this specified key. StartAfter can be any key in the bucket
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the list objects request in V2 style. Bucket owners need not specify this parameter in their requests.
Possible values include:"requester"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:IsTruncated
— (Boolean
)A flag that indicates whether or not Amazon S3 returned all of the results that satisfied the search criteria.
Contents
— (Array<map>
)Metadata about each object returned.
Key
— (String
)LastModified
— (Date
)ETag
— (String
)Size
— (Integer
)StorageClass
— (String
)The class of storage used to store the object.
Possible values include:"STANDARD"
"REDUCED_REDUNDANCY"
"GLACIER"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"DEEP_ARCHIVE"
Owner
— (map
)DisplayName
— (String
)ID
— (String
)
Name
— (String
)Name of the bucket to list.
Prefix
— (String
)Limits the response to keys that begin with the specified prefix.
Delimiter
— (String
)A delimiter is a character you use to group keys.
MaxKeys
— (Integer
)Sets the maximum number of keys returned in the response. The response might contain fewer keys but will never contain more.
CommonPrefixes
— (Array<map>
)CommonPrefixes contains all (if there are any) keys between Prefix and the next occurrence of the string specified by delimiter
Prefix
— (String
)
EncodingType
— (String
)Encoding type used by Amazon S3 to encode object keys in the response.
Possible values include:"url"
KeyCount
— (Integer
)KeyCount is the number of keys returned with this request. KeyCount will always be less than equals to MaxKeys field. Say you ask for 50 keys, your result will include less than equals 50 keys
ContinuationToken
— (String
)ContinuationToken indicates Amazon S3 that the list is being continued on this bucket with a token. ContinuationToken is obfuscated and is not a real key
NextContinuationToken
— (String
)NextContinuationToken is sent when isTruncated is true which means there are more keys in the bucket that can be listed. The next list requests to Amazon S3 can be continued with this NextContinuationToken. NextContinuationToken is obfuscated and is not a real key
StartAfter
— (String
)StartAfter is where you want Amazon S3 to start listing from. Amazon S3 starts listing after this specified key. StartAfter can be any key in the bucket
-
(AWS.Response)
—
Returns:
listObjectVersions(params = {}, callback) ⇒ AWS.Request
Returns metadata about all of the versions of objects in a bucket.
Service Reference:
Examples:
To list object versions
/* The following example return versions of an object with specific key name prefix. The request limits the number of items returned to two. If there are are more than two object version, S3 returns NextToken in the response. You can specify this token value in your next request to fetch next set of object versions. */
var params = {
Bucket: "examplebucket",
Prefix: "HappyFace.jpg"
};
s3.listObjectVersions(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Versions: [
{
ETag: "\"6805f2cfc46c0f04559748bb039d69ae\"",
IsLatest: true,
Key: "HappyFace.jpg",
LastModified: <Date Representation>,
Owner: {
DisplayName: "owner-display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
Size: 3191,
StorageClass: "STANDARD",
VersionId: "null"
},
{
ETag: "\"6805f2cfc46c0f04559748bb039d69ae\"",
IsLatest: false,
Key: "HappyFace.jpg",
LastModified: <Date Representation>,
Owner: {
DisplayName: "owner-display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
Size: 3191,
StorageClass: "STANDARD",
VersionId: "PHtexPGjH2y.zBgT8LmB7wwLI2mpbz.k"
}
]
}
*/
});
Calling the listObjectVersions operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Delimiter: 'STRING_VALUE',
EncodingType: url,
KeyMarker: 'STRING_VALUE',
MaxKeys: 'NUMBER_VALUE',
Prefix: 'STRING_VALUE',
VersionIdMarker: 'STRING_VALUE'
};
s3.listObjectVersions(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Delimiter
— (String
)A delimiter is a character you use to group keys.
EncodingType
— (String
)Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.
Possible values include:"url"
KeyMarker
— (String
)Specifies the key to start with when listing objects in a bucket.
MaxKeys
— (Integer
)Sets the maximum number of keys returned in the response. The response might contain fewer keys but will never contain more.
Prefix
— (String
)Limits the response to keys that begin with the specified prefix.
VersionIdMarker
— (String
)Specifies the object version you want to start listing from.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:IsTruncated
— (Boolean
)A flag that indicates whether or not Amazon S3 returned all of the results that satisfied the search criteria. If your results were truncated, you can make a follow-up paginated request using the NextKeyMarker and NextVersionIdMarker response parameters as a starting place in another request to return the rest of the results.
KeyMarker
— (String
)Marks the last Key returned in a truncated response.
VersionIdMarker
— (String
)NextKeyMarker
— (String
)Use this value for the key marker request parameter in a subsequent request.
NextVersionIdMarker
— (String
)Use this value for the next version id marker parameter in a subsequent request.
Versions
— (Array<map>
)ETag
— (String
)Size
— (Integer
)Size in bytes of the object.
StorageClass
— (String
)The class of storage used to store the object.
Possible values include:"STANDARD"
Key
— (String
)The object key.
VersionId
— (String
)Version ID of an object.
IsLatest
— (Boolean
)Specifies whether the object is (true) or is not (false) the latest version of an object.
LastModified
— (Date
)Date and time the object was last modified.
Owner
— (map
)DisplayName
— (String
)ID
— (String
)
DeleteMarkers
— (Array<map>
)Owner
— (map
)DisplayName
— (String
)ID
— (String
)
Key
— (String
)The object key.
VersionId
— (String
)Version ID of an object.
IsLatest
— (Boolean
)Specifies whether the object is (true) or is not (false) the latest version of an object.
LastModified
— (Date
)Date and time the object was last modified.
Name
— (String
)Prefix
— (String
)Delimiter
— (String
)MaxKeys
— (Integer
)CommonPrefixes
— (Array<map>
)Prefix
— (String
)
EncodingType
— (String
)Encoding type used by Amazon S3 to encode object keys in the response.
Possible values include:"url"
-
(AWS.Response)
—
Returns:
listParts(params = {}, callback) ⇒ AWS.Request
Lists the parts that have been uploaded for a specific multipart upload.
Service Reference:
Examples:
To list parts of a multipart upload.
/* The following example lists parts uploaded for a specific multipart upload. */
var params = {
Bucket: "examplebucket",
Key: "bigobject",
UploadId: "example7YPBOJuoFiQ9cz4P3Pe6FIZwO4f7wN93uHsNBEw97pl5eNwzExg0LAT2dUN91cOmrEQHDsP3WA60CEg--"
};
s3.listParts(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
Initiator: {
DisplayName: "owner-display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
Owner: {
DisplayName: "owner-display-name",
ID: "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
Parts: [
{
ETag: "\"d8c2eafd90c266e19ab9dcacc479f8af\"",
LastModified: <Date Representation>,
PartNumber: 1,
Size: 26246026
},
{
ETag: "\"d8c2eafd90c266e19ab9dcacc479f8af\"",
LastModified: <Date Representation>,
PartNumber: 2,
Size: 26246026
}
],
StorageClass: "STANDARD"
}
*/
});
Calling the listParts operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
UploadId: 'STRING_VALUE', /* required */
MaxParts: 'NUMBER_VALUE',
PartNumberMarker: 'NUMBER_VALUE',
RequestPayer: requester
};
s3.listParts(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Key
— (String
)MaxParts
— (Integer
)Sets the maximum number of parts to return.
PartNumberMarker
— (Integer
)Specifies the part after which listing should begin. Only parts with higher part numbers will be listed.
UploadId
— (String
)Upload ID identifying the multipart upload whose parts are being listed.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:AbortDate
— (Date
)Date when multipart upload will become eligible for abort operation by lifecycle.
AbortRuleId
— (String
)Id of the lifecycle rule that makes a multipart upload eligible for abort operation.
Bucket
— (String
)Name of the bucket to which the multipart upload was initiated.
Key
— (String
)Object key for which the multipart upload was initiated.
UploadId
— (String
)Upload ID identifying the multipart upload whose parts are being listed.
PartNumberMarker
— (Integer
)Part number after which listing begins.
NextPartNumberMarker
— (Integer
)When a list is truncated, this element specifies the last part in the list, as well as the value to use for the part-number-marker request parameter in a subsequent request.
MaxParts
— (Integer
)Maximum number of parts that were allowed in the response.
IsTruncated
— (Boolean
)Indicates whether the returned list of parts is truncated.
Parts
— (Array<map>
)PartNumber
— (Integer
)Part number identifying the part. This is a positive integer between 1 and 10,000.
LastModified
— (Date
)Date and time at which the part was uploaded.
ETag
— (String
)Entity tag returned when the part was uploaded.
Size
— (Integer
)Size in bytes of the uploaded part data.
Initiator
— (map
)Identifies who initiated the multipart upload.
ID
— (String
)If the principal is an AWS account, it provides the Canonical User ID. If the principal is an IAM User, it provides a user ARN value.
DisplayName
— (String
)Name of the Principal.
Owner
— (map
)DisplayName
— (String
)ID
— (String
)
StorageClass
— (String
)The class of storage used to store the object.
Possible values include:"STANDARD"
"REDUCED_REDUNDANCY"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"GLACIER"
"DEEP_ARCHIVE"
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
putBucketAccelerateConfiguration(params = {}, callback) ⇒ AWS.Request
Sets the accelerate configuration of an existing bucket.
Service Reference:
Examples:
Calling the putBucketAccelerateConfiguration operation
var params = {
AccelerateConfiguration: { /* required */
Status: Enabled | Suspended
},
Bucket: 'STRING_VALUE' /* required */
};
s3.putBucketAccelerateConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Name of the bucket for which the accelerate configuration is set.
AccelerateConfiguration
— (map
)Specifies the Accelerate Configuration you want to set for the bucket.
Status
— (String
)The accelerate configuration of the bucket.
Possible values include:"Enabled"
"Suspended"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketAcl(params = {}, callback) ⇒ AWS.Request
Sets the permissions on a bucket using access control lists (ACL).
Service Reference:
Examples:
Put bucket acl
/* The following example replaces existing ACL on a bucket. The ACL grants the bucket owner (specified using the owner ID) and write permission to the LogDelivery group. Because this is a replace operation, you must specify all the grants in your request. To incrementally add or remove ACL grants, you might use the console. */
var params = {
Bucket: "examplebucket",
GrantFullControl: "id=examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484",
GrantWrite: "uri=http://acs.amazonaws.com/groups/s3/LogDelivery"
};
s3.putBucketAcl(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the putBucketAcl operation
var params = {
Bucket: 'STRING_VALUE', /* required */
ACL: private | public-read | public-read-write | authenticated-read,
AccessControlPolicy: {
Grants: [
{
Grantee: {
Type: CanonicalUser | AmazonCustomerByEmail | Group, /* required */
DisplayName: 'STRING_VALUE',
EmailAddress: 'STRING_VALUE',
ID: 'STRING_VALUE',
URI: 'STRING_VALUE'
},
Permission: FULL_CONTROL | WRITE | WRITE_ACP | READ | READ_ACP
},
/* more items */
],
Owner: {
DisplayName: 'STRING_VALUE',
ID: 'STRING_VALUE'
}
},
ContentMD5: 'STRING_VALUE',
GrantFullControl: 'STRING_VALUE',
GrantRead: 'STRING_VALUE',
GrantReadACP: 'STRING_VALUE',
GrantWrite: 'STRING_VALUE',
GrantWriteACP: 'STRING_VALUE'
};
s3.putBucketAcl(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
ACL
— (String
)The canned ACL to apply to the bucket.
Possible values include:"private"
"public-read"
"public-read-write"
"authenticated-read"
AccessControlPolicy
— (map
)Grants
— (Array<map>
)A list of grants.
Grantee
— (map
)DisplayName
— (String
)Screen name of the grantee.
EmailAddress
— (String
)Email address of the grantee.
ID
— (String
)The canonical user ID of the grantee.
Type
— required — (String
)Type of grantee
Possible values include:"CanonicalUser"
"AmazonCustomerByEmail"
"Group"
URI
— (String
)URI of the grantee group.
Permission
— (String
)Specifies the permission given to the grantee.
Possible values include:"FULL_CONTROL"
"WRITE"
"WRITE_ACP"
"READ"
"READ_ACP"
Owner
— (map
)DisplayName
— (String
)ID
— (String
)
Bucket
— (String
)ContentMD5
— (String
)GrantFullControl
— (String
)Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
GrantRead
— (String
)Allows grantee to list the objects in the bucket.
GrantReadACP
— (String
)Allows grantee to read the bucket ACL.
GrantWrite
— (String
)Allows grantee to create, overwrite, and delete any object in the bucket.
GrantWriteACP
— (String
)Allows grantee to write the ACL for the applicable bucket.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketAnalyticsConfiguration(params = {}, callback) ⇒ AWS.Request
Sets an analytics configuration for the bucket (specified by the analytics configuration ID).
Service Reference:
Examples:
Calling the putBucketAnalyticsConfiguration operation
var params = {
AnalyticsConfiguration: { /* required */
Id: 'STRING_VALUE', /* required */
StorageClassAnalysis: { /* required */
DataExport: {
Destination: { /* required */
S3BucketDestination: { /* required */
Bucket: 'STRING_VALUE', /* required */
Format: CSV, /* required */
BucketAccountId: 'STRING_VALUE',
Prefix: 'STRING_VALUE'
}
},
OutputSchemaVersion: V_1 /* required */
}
},
Filter: {
And: {
Prefix: 'STRING_VALUE',
Tags: [
{
Key: 'STRING_VALUE', /* required */
Value: 'STRING_VALUE' /* required */
},
/* more items */
]
},
Prefix: 'STRING_VALUE',
Tag: {
Key: 'STRING_VALUE', /* required */
Value: 'STRING_VALUE' /* required */
}
}
},
Bucket: 'STRING_VALUE', /* required */
Id: 'STRING_VALUE' /* required */
};
s3.putBucketAnalyticsConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket to which an analytics configuration is stored.
Id
— (String
)The identifier used to represent an analytics configuration.
AnalyticsConfiguration
— (map
)The configuration and any analyses for the analytics filter.
Id
— required — (String
)The identifier used to represent an analytics configuration.
Filter
— (map
)The filter used to describe a set of objects for analyses. A filter must have exactly one prefix, one tag, or one conjunction (AnalyticsAndOperator). If no filter is provided, all objects will be considered in any analysis.
Prefix
— (String
)The prefix to use when evaluating an analytics filter.
Tag
— (map
)The tag to use when evaluating an analytics filter.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
And
— (map
)A conjunction (logical AND) of predicates, which is used in evaluating an analytics filter. The operator must have at least two predicates.
Prefix
— (String
)The prefix to use when evaluating an AND predicate.
Tags
— (Array<map>
)The list of tags to use when evaluating an AND predicate.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
StorageClassAnalysis
— required — (map
)If present, it indicates that data related to access patterns will be collected and made available to analyze the tradeoffs between different storage classes.
DataExport
— (map
)A container used to describe how data related to the storage class analysis should be exported.
OutputSchemaVersion
— required — (String
)The version of the output schema to use when exporting data. Must be V_1.
Possible values include:"V_1"
Destination
— required — (map
)The place to store the data for an analysis.
S3BucketDestination
— required — (map
)A destination signifying output to an S3 bucket.
Format
— required — (String
)The file format used when exporting data to Amazon S3.
Possible values include:"CSV"
BucketAccountId
— (String
)The account ID that owns the destination bucket. If no account ID is provided, the owner will not be validated prior to exporting data.
Bucket
— required — (String
)The Amazon resource name (ARN) of the bucket to which data is exported.
Prefix
— (String
)The prefix to use when exporting data. The exported data begins with this prefix.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketCors(params = {}, callback) ⇒ AWS.Request
Sets the CORS configuration for a bucket.
Service Reference:
Examples:
To set cors configuration on a bucket.
/* The following example enables PUT, POST, and DELETE requests from www.example.com, and enables GET requests from any domain. */
var params = {
Bucket: "",
CORSConfiguration: {
CORSRules: [
{
AllowedHeaders: [
"*"
],
AllowedMethods: [
"PUT",
"POST",
"DELETE"
],
AllowedOrigins: [
"http://www.example.com"
],
ExposeHeaders: [
"x-amz-server-side-encryption"
],
MaxAgeSeconds: 3000
},
{
AllowedHeaders: [
"Authorization"
],
AllowedMethods: [
"GET"
],
AllowedOrigins: [
"*"
],
MaxAgeSeconds: 3000
}
]
},
ContentMD5: ""
};
s3.putBucketCors(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the putBucketCors operation
var params = {
Bucket: 'STRING_VALUE', /* required */
CORSConfiguration: { /* required */
CORSRules: [ /* required */
{
AllowedMethods: [ /* required */
'STRING_VALUE',
/* more items */
],
AllowedOrigins: [ /* required */
'STRING_VALUE',
/* more items */
],
AllowedHeaders: [
'STRING_VALUE',
/* more items */
],
ExposeHeaders: [
'STRING_VALUE',
/* more items */
],
MaxAgeSeconds: 'NUMBER_VALUE'
},
/* more items */
]
},
ContentMD5: 'STRING_VALUE'
};
s3.putBucketCors(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)CORSConfiguration
— (map
)CORSRules
— required — (Array<map>
)AllowedHeaders
— (Array<String>
)Specifies which headers are allowed in a pre-flight OPTIONS request.
AllowedMethods
— required — (Array<String>
)Identifies HTTP methods that the domain/origin specified in the rule is allowed to execute.
AllowedOrigins
— required — (Array<String>
)One or more origins you want customers to be able to access the bucket from.
ExposeHeaders
— (Array<String>
)One or more headers in the response that you want customers to be able to access from their applications (for example, from a JavaScript XMLHttpRequest object).
MaxAgeSeconds
— (Integer
)The time in seconds that your browser is to cache the preflight response for the specified resource.
ContentMD5
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketEncryption(params = {}, callback) ⇒ AWS.Request
Creates a new server-side encryption configuration (or replaces an existing one, if present).
Service Reference:
Examples:
Calling the putBucketEncryption operation
var params = {
Bucket: 'STRING_VALUE', /* required */
ServerSideEncryptionConfiguration: { /* required */
Rules: [ /* required */
{
ApplyServerSideEncryptionByDefault: {
SSEAlgorithm: AES256 | aws:kms, /* required */
KMSMasterKeyID: 'STRING_VALUE'
}
},
/* more items */
]
},
ContentMD5: 'STRING_VALUE'
};
s3.putBucketEncryption(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket for which the server-side encryption configuration is set.
ContentMD5
— (String
)The base64-encoded 128-bit MD5 digest of the server-side encryption configuration. This parameter is auto-populated when using the command from the CLI
ServerSideEncryptionConfiguration
— (map
)Container for server-side encryption configuration rules. Currently S3 supports one rule only.
Rules
— required — (Array<map>
)Container for information about a particular server-side encryption configuration rule.
ApplyServerSideEncryptionByDefault
— (map
)Describes the default server-side encryption to apply to new objects in the bucket. If Put Object request does not specify any server-side encryption, this default encryption will be applied.
SSEAlgorithm
— required — (String
)Server-side encryption algorithm to use for the default encryption.
Possible values include:"AES256"
"aws:kms"
KMSMasterKeyID
— (String
)KMS master key ID to use for the default encryption. This parameter is allowed if SSEAlgorithm is aws:kms.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketInventoryConfiguration(params = {}, callback) ⇒ AWS.Request
Adds an inventory configuration (identified by the inventory ID) from the bucket.
Service Reference:
Examples:
Calling the putBucketInventoryConfiguration operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Id: 'STRING_VALUE', /* required */
InventoryConfiguration: { /* required */
Destination: { /* required */
S3BucketDestination: { /* required */
Bucket: 'STRING_VALUE', /* required */
Format: CSV | ORC | Parquet, /* required */
AccountId: 'STRING_VALUE',
Encryption: {
SSEKMS: {
KeyId: 'STRING_VALUE' /* required */
},
SSES3: {
}
},
Prefix: 'STRING_VALUE'
}
},
Id: 'STRING_VALUE', /* required */
IncludedObjectVersions: All | Current, /* required */
IsEnabled: true || false, /* required */
Schedule: { /* required */
Frequency: Daily | Weekly /* required */
},
Filter: {
Prefix: 'STRING_VALUE' /* required */
},
OptionalFields: [
Size | LastModifiedDate | StorageClass | ETag | IsMultipartUploaded | ReplicationStatus | EncryptionStatus | ObjectLockRetainUntilDate | ObjectLockMode | ObjectLockLegalHoldStatus,
/* more items */
]
}
};
s3.putBucketInventoryConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket where the inventory configuration will be stored.
Id
— (String
)The ID used to identify the inventory configuration.
InventoryConfiguration
— (map
)Specifies the inventory configuration.
Destination
— required — (map
)Contains information about where to publish the inventory results.
S3BucketDestination
— required — (map
)Contains the bucket name, file format, bucket owner (optional), and prefix (optional) where inventory results are published.
AccountId
— (String
)The ID of the account that owns the destination bucket.
Bucket
— required — (String
)The Amazon resource name (ARN) of the bucket where inventory results will be published.
Format
— required — (String
)Specifies the output format of the inventory results.
Possible values include:"CSV"
"ORC"
"Parquet"
Prefix
— (String
)The prefix that is prepended to all inventory results.
Encryption
— (map
)Contains the type of server-side encryption used to encrypt the inventory results.
SSES3
— (map
)Specifies the use of SSE-S3 to encrypt delivered Inventory reports.
SSEKMS
— (map
)Specifies the use of SSE-KMS to encrypt delivered Inventory reports.
KeyId
— required — (String
)Specifies the ID of the AWS Key Management Service (KMS) master encryption key to use for encrypting Inventory reports.
IsEnabled
— required — (Boolean
)Specifies whether the inventory is enabled or disabled.
Filter
— (map
)Specifies an inventory filter. The inventory only includes objects that meet the filter's criteria.
Prefix
— required — (String
)The prefix that an object must have to be included in the inventory results.
Id
— required — (String
)The ID used to identify the inventory configuration.
IncludedObjectVersions
— required — (String
)Specifies which object version(s) to included in the inventory results.
Possible values include:"All"
"Current"
OptionalFields
— (Array<String>
)Contains the optional fields that are included in the inventory results.
Schedule
— required — (map
)Specifies the schedule for generating inventory results.
Frequency
— required — (String
)Specifies how frequently inventory results are produced.
Possible values include:"Daily"
"Weekly"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketLifecycle(params = {}, callback) ⇒ AWS.Request
No longer used, see the PutBucketLifecycleConfiguration operation.
Service Reference:
Examples:
Calling the putBucketLifecycle operation
var params = {
Bucket: 'STRING_VALUE', /* required */
ContentMD5: 'STRING_VALUE',
LifecycleConfiguration: {
Rules: [ /* required */
{
Prefix: 'STRING_VALUE', /* required */
Status: Enabled | Disabled, /* required */
AbortIncompleteMultipartUpload: {
DaysAfterInitiation: 'NUMBER_VALUE'
},
Expiration: {
Date: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
Days: 'NUMBER_VALUE',
ExpiredObjectDeleteMarker: true || false
},
ID: 'STRING_VALUE',
NoncurrentVersionExpiration: {
NoncurrentDays: 'NUMBER_VALUE'
},
NoncurrentVersionTransition: {
NoncurrentDays: 'NUMBER_VALUE',
StorageClass: GLACIER | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING | DEEP_ARCHIVE
},
Transition: {
Date: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
Days: 'NUMBER_VALUE',
StorageClass: GLACIER | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING | DEEP_ARCHIVE
}
},
/* more items */
]
}
};
s3.putBucketLifecycle(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)ContentMD5
— (String
)LifecycleConfiguration
— (map
)Rules
— required — (Array<map>
)Expiration
— (map
)Date
— (Date
)Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
Days
— (Integer
)Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
ExpiredObjectDeleteMarker
— (Boolean
)Indicates whether Amazon S3 will remove a delete marker with no noncurrent versions. If set to true, the delete marker will be expired; if set to false the policy takes no action. This cannot be specified with Days or Date in a Lifecycle Expiration Policy.
ID
— (String
)Unique identifier for the rule. The value cannot be longer than 255 characters.
Prefix
— required — (String
)Prefix identifying one or more objects to which the rule applies.
Status
— required — (String
)If 'Enabled', the rule is currently being applied. If 'Disabled', the rule is not currently being applied.
Possible values include:"Enabled"
"Disabled"
Transition
— (map
)Date
— (Date
)Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
Days
— (Integer
)Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
StorageClass
— (String
)The class of storage used to store the object.
Possible values include:"GLACIER"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"DEEP_ARCHIVE"
NoncurrentVersionTransition
— (map
)Container for the transition rule that describes when noncurrent objects transition to the STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER or DEEP_ARCHIVE storage class. If your bucket is versioning-enabled (or versioning is suspended), you can set this action to request that Amazon S3 transition noncurrent object versions to the STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER or DEEP_ARCHIVE storage class at a specific period in the object's lifetime.
NoncurrentDays
— (Integer
)Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
StorageClass
— (String
)The class of storage used to store the object.
Possible values include:"GLACIER"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"DEEP_ARCHIVE"
NoncurrentVersionExpiration
— (map
)Specifies when noncurrent object versions expire. Upon expiration, Amazon S3 permanently deletes the noncurrent object versions. You set this lifecycle configuration action on a bucket that has versioning enabled (or suspended) to request that Amazon S3 delete noncurrent object versions at a specific period in the object's lifetime.
NoncurrentDays
— (Integer
)Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
AbortIncompleteMultipartUpload
— (map
)Specifies the days since the initiation of an Incomplete Multipart Upload that Lifecycle will wait before permanently removing all parts of the upload.
DaysAfterInitiation
— (Integer
)Indicates the number of days that must pass since initiation for Lifecycle to abort an Incomplete Multipart Upload.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketLifecycleConfiguration(params = {}, callback) ⇒ AWS.Request
Sets lifecycle configuration for your bucket. If a lifecycle configuration exists, it replaces it.
Service Reference:
Examples:
Put bucket lifecycle
/* The following example replaces existing lifecycle configuration, if any, on the specified bucket. */
var params = {
Bucket: "examplebucket",
LifecycleConfiguration: {
Rules: [
{
Expiration: {
Days: 3650
},
Filter: {
Prefix: "documents/"
},
ID: "TestOnly",
Status: "Enabled",
Transitions: [
{
Days: 365,
StorageClass: "GLACIER"
}
]
}
]
}
};
s3.putBucketLifecycleConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the putBucketLifecycleConfiguration operation
var params = {
Bucket: 'STRING_VALUE', /* required */
LifecycleConfiguration: {
Rules: [ /* required */
{
Status: Enabled | Disabled, /* required */
AbortIncompleteMultipartUpload: {
DaysAfterInitiation: 'NUMBER_VALUE'
},
Expiration: {
Date: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
Days: 'NUMBER_VALUE',
ExpiredObjectDeleteMarker: true || false
},
Filter: {
And: {
Prefix: 'STRING_VALUE',
Tags: [
{
Key: 'STRING_VALUE', /* required */
Value: 'STRING_VALUE' /* required */
},
/* more items */
]
},
Prefix: 'STRING_VALUE',
Tag: {
Key: 'STRING_VALUE', /* required */
Value: 'STRING_VALUE' /* required */
}
},
ID: 'STRING_VALUE',
NoncurrentVersionExpiration: {
NoncurrentDays: 'NUMBER_VALUE'
},
NoncurrentVersionTransitions: [
{
NoncurrentDays: 'NUMBER_VALUE',
StorageClass: GLACIER | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING | DEEP_ARCHIVE
},
/* more items */
],
Prefix: 'STRING_VALUE',
Transitions: [
{
Date: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
Days: 'NUMBER_VALUE',
StorageClass: GLACIER | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING | DEEP_ARCHIVE
},
/* more items */
]
},
/* more items */
]
}
};
s3.putBucketLifecycleConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)LifecycleConfiguration
— (map
)Rules
— required — (Array<map>
)Expiration
— (map
)Date
— (Date
)Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
Days
— (Integer
)Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
ExpiredObjectDeleteMarker
— (Boolean
)Indicates whether Amazon S3 will remove a delete marker with no noncurrent versions. If set to true, the delete marker will be expired; if set to false the policy takes no action. This cannot be specified with Days or Date in a Lifecycle Expiration Policy.
ID
— (String
)Unique identifier for the rule. The value cannot be longer than 255 characters.
Prefix
— (String
)Prefix identifying one or more objects to which the rule applies. This is No longer used; use Filter instead.
Filter
— (map
)The Filter is used to identify objects that a Lifecycle Rule applies to. A Filter must have exactly one of Prefix, Tag, or And specified.
Prefix
— (String
)Prefix identifying one or more objects to which the rule applies.
Tag
— (map
)This tag must exist in the object's tag set in order for the rule to apply.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
And
— (map
)This is used in a Lifecycle Rule Filter to apply a logical AND to two or more predicates. The Lifecycle Rule will apply to any object matching all of the predicates configured inside the And operator.
Prefix
— (String
)Tags
— (Array<map>
)All of these tags must exist in the object's tag set in order for the rule to apply.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
Status
— required — (String
)If 'Enabled', the rule is currently being applied. If 'Disabled', the rule is not currently being applied.
Possible values include:"Enabled"
"Disabled"
Transitions
— (Array<map>
)Date
— (Date
)Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
Days
— (Integer
)Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
StorageClass
— (String
)The class of storage used to store the object.
Possible values include:"GLACIER"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"DEEP_ARCHIVE"
NoncurrentVersionTransitions
— (Array<map>
)NoncurrentDays
— (Integer
)Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
StorageClass
— (String
)The class of storage used to store the object.
Possible values include:"GLACIER"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"DEEP_ARCHIVE"
NoncurrentVersionExpiration
— (map
)Specifies when noncurrent object versions expire. Upon expiration, Amazon S3 permanently deletes the noncurrent object versions. You set this lifecycle configuration action on a bucket that has versioning enabled (or suspended) to request that Amazon S3 delete noncurrent object versions at a specific period in the object's lifetime.
NoncurrentDays
— (Integer
)Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
AbortIncompleteMultipartUpload
— (map
)Specifies the days since the initiation of an Incomplete Multipart Upload that Lifecycle will wait before permanently removing all parts of the upload.
DaysAfterInitiation
— (Integer
)Indicates the number of days that must pass since initiation for Lifecycle to abort an Incomplete Multipart Upload.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketLogging(params = {}, callback) ⇒ AWS.Request
Set the logging parameters for a bucket and to specify permissions for who can view and modify the logging parameters. To set the logging status of a bucket, you must be the bucket owner.
Service Reference:
Examples:
Set logging configuration for a bucket
/* The following example sets logging policy on a bucket. For the Log Delivery group to deliver logs to the destination bucket, it needs permission for the READ_ACP action which the policy grants. */
var params = {
Bucket: "sourcebucket",
BucketLoggingStatus: {
LoggingEnabled: {
TargetBucket: "targetbucket",
TargetGrants: [
{
Grantee: {
Type: "Group",
URI: "http://acs.amazonaws.com/groups/global/AllUsers"
},
Permission: "READ"
}
],
TargetPrefix: "MyBucketLogs/"
}
}
};
s3.putBucketLogging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the putBucketLogging operation
var params = {
Bucket: 'STRING_VALUE', /* required */
BucketLoggingStatus: { /* required */
LoggingEnabled: {
TargetBucket: 'STRING_VALUE', /* required */
TargetPrefix: 'STRING_VALUE', /* required */
TargetGrants: [
{
Grantee: {
Type: CanonicalUser | AmazonCustomerByEmail | Group, /* required */
DisplayName: 'STRING_VALUE',
EmailAddress: 'STRING_VALUE',
ID: 'STRING_VALUE',
URI: 'STRING_VALUE'
},
Permission: FULL_CONTROL | READ | WRITE
},
/* more items */
]
}
},
ContentMD5: 'STRING_VALUE'
};
s3.putBucketLogging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)BucketLoggingStatus
— (map
)LoggingEnabled
— (map
)Container for logging information. Presence of this element indicates that logging is enabled. Parameters TargetBucket and TargetPrefix are required in this case.
TargetBucket
— required — (String
)Specifies the bucket where you want Amazon S3 to store server access logs. You can have your logs delivered to any bucket that you own, including the same bucket that is being logged. You can also configure multiple buckets to deliver their logs to the same target bucket. In this case you should choose a different TargetPrefix for each source bucket so that the delivered log files can be distinguished by key.
TargetGrants
— (Array<map>
)Grantee
— (map
)DisplayName
— (String
)Screen name of the grantee.
EmailAddress
— (String
)Email address of the grantee.
ID
— (String
)The canonical user ID of the grantee.
Type
— required — (String
)Type of grantee
Possible values include:"CanonicalUser"
"AmazonCustomerByEmail"
"Group"
URI
— (String
)URI of the grantee group.
Permission
— (String
)Logging permissions assigned to the Grantee for the bucket.
Possible values include:"FULL_CONTROL"
"READ"
"WRITE"
TargetPrefix
— required — (String
)This element lets you specify a prefix for the keys that the log files will be stored under.
ContentMD5
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketMetricsConfiguration(params = {}, callback) ⇒ AWS.Request
Sets a metrics configuration (specified by the metrics configuration ID) for the bucket.
Service Reference:
Examples:
Calling the putBucketMetricsConfiguration operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Id: 'STRING_VALUE', /* required */
MetricsConfiguration: { /* required */
Id: 'STRING_VALUE', /* required */
Filter: {
And: {
Prefix: 'STRING_VALUE',
Tags: [
{
Key: 'STRING_VALUE', /* required */
Value: 'STRING_VALUE' /* required */
},
/* more items */
]
},
Prefix: 'STRING_VALUE',
Tag: {
Key: 'STRING_VALUE', /* required */
Value: 'STRING_VALUE' /* required */
}
}
}
};
s3.putBucketMetricsConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the bucket for which the metrics configuration is set.
Id
— (String
)The ID used to identify the metrics configuration.
MetricsConfiguration
— (map
)Specifies the metrics configuration.
Id
— required — (String
)The ID used to identify the metrics configuration.
Filter
— (map
)Specifies a metrics configuration filter. The metrics configuration will only include objects that meet the filter's criteria. A filter must be a prefix, a tag, or a conjunction (MetricsAndOperator).
Prefix
— (String
)The prefix used when evaluating a metrics filter.
Tag
— (map
)The tag used when evaluating a metrics filter.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
And
— (map
)A conjunction (logical AND) of predicates, which is used in evaluating a metrics filter. The operator must have at least two predicates, and an object must match all of the predicates in order for the filter to apply.
Prefix
— (String
)The prefix used when evaluating an AND predicate.
Tags
— (Array<map>
)The list of tags used when evaluating an AND predicate.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketNotification(params = {}, callback) ⇒ AWS.Request
No longer used, see the PutBucketNotificationConfiguration operation.
Service Reference:
Examples:
Calling the putBucketNotification operation
var params = {
Bucket: 'STRING_VALUE', /* required */
NotificationConfiguration: { /* required */
CloudFunctionConfiguration: {
CloudFunction: 'STRING_VALUE',
Event: s3:ReducedRedundancyLostObject | s3:ObjectCreated:* | s3:ObjectCreated:Put | s3:ObjectCreated:Post | s3:ObjectCreated:Copy | s3:ObjectCreated:CompleteMultipartUpload | s3:ObjectRemoved:* | s3:ObjectRemoved:Delete | s3:ObjectRemoved:DeleteMarkerCreated | s3:ObjectRestore:Post | s3:ObjectRestore:Completed,
Events: [
s3:ReducedRedundancyLostObject | s3:ObjectCreated:* | s3:ObjectCreated:Put | s3:ObjectCreated:Post | s3:ObjectCreated:Copy | s3:ObjectCreated:CompleteMultipartUpload | s3:ObjectRemoved:* | s3:ObjectRemoved:Delete | s3:ObjectRemoved:DeleteMarkerCreated | s3:ObjectRestore:Post | s3:ObjectRestore:Completed,
/* more items */
],
Id: 'STRING_VALUE',
InvocationRole: 'STRING_VALUE'
},
QueueConfiguration: {
Event: s3:ReducedRedundancyLostObject | s3:ObjectCreated:* | s3:ObjectCreated:Put | s3:ObjectCreated:Post | s3:ObjectCreated:Copy | s3:ObjectCreated:CompleteMultipartUpload | s3:ObjectRemoved:* | s3:ObjectRemoved:Delete | s3:ObjectRemoved:DeleteMarkerCreated | s3:ObjectRestore:Post | s3:ObjectRestore:Completed,
Events: [
s3:ReducedRedundancyLostObject | s3:ObjectCreated:* | s3:ObjectCreated:Put | s3:ObjectCreated:Post | s3:ObjectCreated:Copy | s3:ObjectCreated:CompleteMultipartUpload | s3:ObjectRemoved:* | s3:ObjectRemoved:Delete | s3:ObjectRemoved:DeleteMarkerCreated | s3:ObjectRestore:Post | s3:ObjectRestore:Completed,
/* more items */
],
Id: 'STRING_VALUE',
Queue: 'STRING_VALUE'
},
TopicConfiguration: {
Event: s3:ReducedRedundancyLostObject | s3:ObjectCreated:* | s3:ObjectCreated:Put | s3:ObjectCreated:Post | s3:ObjectCreated:Copy | s3:ObjectCreated:CompleteMultipartUpload | s3:ObjectRemoved:* | s3:ObjectRemoved:Delete | s3:ObjectRemoved:DeleteMarkerCreated | s3:ObjectRestore:Post | s3:ObjectRestore:Completed,
Events: [
s3:ReducedRedundancyLostObject | s3:ObjectCreated:* | s3:ObjectCreated:Put | s3:ObjectCreated:Post | s3:ObjectCreated:Copy | s3:ObjectCreated:CompleteMultipartUpload | s3:ObjectRemoved:* | s3:ObjectRemoved:Delete | s3:ObjectRemoved:DeleteMarkerCreated | s3:ObjectRestore:Post | s3:ObjectRestore:Completed,
/* more items */
],
Id: 'STRING_VALUE',
Topic: 'STRING_VALUE'
}
},
ContentMD5: 'STRING_VALUE'
};
s3.putBucketNotification(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)ContentMD5
— (String
)NotificationConfiguration
— (map
)TopicConfiguration
— (map
)Id
— (String
)An optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
Events
— (Array<String>
)Event
— (String
)Bucket event for which to send notifications.
Possible values include:"s3:ReducedRedundancyLostObject"
"s3:ObjectCreated:*"
"s3:ObjectCreated:Put"
"s3:ObjectCreated:Post"
"s3:ObjectCreated:Copy"
"s3:ObjectCreated:CompleteMultipartUpload"
"s3:ObjectRemoved:*"
"s3:ObjectRemoved:Delete"
"s3:ObjectRemoved:DeleteMarkerCreated"
"s3:ObjectRestore:Post"
"s3:ObjectRestore:Completed"
Topic
— (String
)Amazon SNS topic to which Amazon S3 will publish a message to report the specified events for the bucket.
QueueConfiguration
— (map
)Id
— (String
)An optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
Event
— (String
)The bucket event for which to send notifications.
Possible values include:"s3:ReducedRedundancyLostObject"
"s3:ObjectCreated:*"
"s3:ObjectCreated:Put"
"s3:ObjectCreated:Post"
"s3:ObjectCreated:Copy"
"s3:ObjectCreated:CompleteMultipartUpload"
"s3:ObjectRemoved:*"
"s3:ObjectRemoved:Delete"
"s3:ObjectRemoved:DeleteMarkerCreated"
"s3:ObjectRestore:Post"
"s3:ObjectRestore:Completed"
Events
— (Array<String>
)Queue
— (String
)
CloudFunctionConfiguration
— (map
)Id
— (String
)An optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
Event
— (String
)The bucket event for which to send notifications.
Possible values include:"s3:ReducedRedundancyLostObject"
"s3:ObjectCreated:*"
"s3:ObjectCreated:Put"
"s3:ObjectCreated:Post"
"s3:ObjectCreated:Copy"
"s3:ObjectCreated:CompleteMultipartUpload"
"s3:ObjectRemoved:*"
"s3:ObjectRemoved:Delete"
"s3:ObjectRemoved:DeleteMarkerCreated"
"s3:ObjectRestore:Post"
"s3:ObjectRestore:Completed"
Events
— (Array<String>
)CloudFunction
— (String
)InvocationRole
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketNotificationConfiguration(params = {}, callback) ⇒ AWS.Request
Enables notifications of specified events for a bucket.
Service Reference:
Examples:
Set notification configuration for a bucket
/* The following example sets notification configuration on a bucket to publish the object created events to an SNS topic. */
var params = {
Bucket: "examplebucket",
NotificationConfiguration: {
TopicConfigurations: [
{
Events: [
"s3:ObjectCreated:*"
],
TopicArn: "arn:aws:sns:us-west-2:123456789012:s3-notification-topic"
}
]
}
};
s3.putBucketNotificationConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the putBucketNotificationConfiguration operation
var params = {
Bucket: 'STRING_VALUE', /* required */
NotificationConfiguration: { /* required */
LambdaFunctionConfigurations: [
{
Events: [ /* required */
s3:ReducedRedundancyLostObject | s3:ObjectCreated:* | s3:ObjectCreated:Put | s3:ObjectCreated:Post | s3:ObjectCreated:Copy | s3:ObjectCreated:CompleteMultipartUpload | s3:ObjectRemoved:* | s3:ObjectRemoved:Delete | s3:ObjectRemoved:DeleteMarkerCreated | s3:ObjectRestore:Post | s3:ObjectRestore:Completed,
/* more items */
],
LambdaFunctionArn: 'STRING_VALUE', /* required */
Filter: {
Key: {
FilterRules: [
{
Name: prefix | suffix,
Value: 'STRING_VALUE'
},
/* more items */
]
}
},
Id: 'STRING_VALUE'
},
/* more items */
],
QueueConfigurations: [
{
Events: [ /* required */
s3:ReducedRedundancyLostObject | s3:ObjectCreated:* | s3:ObjectCreated:Put | s3:ObjectCreated:Post | s3:ObjectCreated:Copy | s3:ObjectCreated:CompleteMultipartUpload | s3:ObjectRemoved:* | s3:ObjectRemoved:Delete | s3:ObjectRemoved:DeleteMarkerCreated | s3:ObjectRestore:Post | s3:ObjectRestore:Completed,
/* more items */
],
QueueArn: 'STRING_VALUE', /* required */
Filter: {
Key: {
FilterRules: [
{
Name: prefix | suffix,
Value: 'STRING_VALUE'
},
/* more items */
]
}
},
Id: 'STRING_VALUE'
},
/* more items */
],
TopicConfigurations: [
{
Events: [ /* required */
s3:ReducedRedundancyLostObject | s3:ObjectCreated:* | s3:ObjectCreated:Put | s3:ObjectCreated:Post | s3:ObjectCreated:Copy | s3:ObjectCreated:CompleteMultipartUpload | s3:ObjectRemoved:* | s3:ObjectRemoved:Delete | s3:ObjectRemoved:DeleteMarkerCreated | s3:ObjectRestore:Post | s3:ObjectRestore:Completed,
/* more items */
],
TopicArn: 'STRING_VALUE', /* required */
Filter: {
Key: {
FilterRules: [
{
Name: prefix | suffix,
Value: 'STRING_VALUE'
},
/* more items */
]
}
},
Id: 'STRING_VALUE'
},
/* more items */
]
}
};
s3.putBucketNotificationConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)NotificationConfiguration
— (map
)A container for specifying the notification configuration of the bucket. If this element is empty, notifications are turned off for the bucket.
TopicConfigurations
— (Array<map>
)Id
— (String
)An optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
TopicArn
— required — (String
)The Amazon Resource Name (ARN) of the Amazon SNS topic to which Amazon S3 will publish a message when it detects events of the specified type.
Events
— required — (Array<String>
)Filter
— (map
)A container for object key name filtering rules. For information about key name filtering, see Configuring Event Notifications in the Amazon Simple Storage Service Developer Guide.
Key
— (map
)A container for object key name prefix and suffix filtering rules.
FilterRules
— (Array<map>
)A list of containers for the key value pair that defines the criteria for the filter rule.
Name
— (String
)The object key name prefix or suffix identifying one or more objects to which the filtering rule applies. The maximum prefix length is 1,024 characters. Overlapping prefixes and suffixes are not supported. For more information, see Configuring Event Notifications in the Amazon Simple Storage Service Developer Guide.
Possible values include:"prefix"
"suffix"
Value
— (String
)
QueueConfigurations
— (Array<map>
)Id
— (String
)An optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
QueueArn
— required — (String
)The Amazon Resource Name (ARN) of the Amazon SQS queue to which Amazon S3 will publish a message when it detects events of the specified type.
Events
— required — (Array<String>
)Filter
— (map
)A container for object key name filtering rules. For information about key name filtering, see Configuring Event Notifications in the Amazon Simple Storage Service Developer Guide.
Key
— (map
)A container for object key name prefix and suffix filtering rules.
FilterRules
— (Array<map>
)A list of containers for the key value pair that defines the criteria for the filter rule.
Name
— (String
)The object key name prefix or suffix identifying one or more objects to which the filtering rule applies. The maximum prefix length is 1,024 characters. Overlapping prefixes and suffixes are not supported. For more information, see Configuring Event Notifications in the Amazon Simple Storage Service Developer Guide.
Possible values include:"prefix"
"suffix"
Value
— (String
)
LambdaFunctionConfigurations
— (Array<map>
)Id
— (String
)An optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
LambdaFunctionArn
— required — (String
)The Amazon Resource Name (ARN) of the Lambda cloud function that Amazon S3 can invoke when it detects events of the specified type.
Events
— required — (Array<String>
)Filter
— (map
)A container for object key name filtering rules. For information about key name filtering, see Configuring Event Notifications in the Amazon Simple Storage Service Developer Guide.
Key
— (map
)A container for object key name prefix and suffix filtering rules.
FilterRules
— (Array<map>
)A list of containers for the key value pair that defines the criteria for the filter rule.
Name
— (String
)The object key name prefix or suffix identifying one or more objects to which the filtering rule applies. The maximum prefix length is 1,024 characters. Overlapping prefixes and suffixes are not supported. For more information, see Configuring Event Notifications in the Amazon Simple Storage Service Developer Guide.
Possible values include:"prefix"
"suffix"
Value
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketPolicy(params = {}, callback) ⇒ AWS.Request
Replaces a policy on a bucket. If the bucket already has a policy, the one in this request completely replaces it.
Service Reference:
Examples:
Set bucket policy
/* The following example sets a permission policy on a bucket. */
var params = {
Bucket: "examplebucket",
Policy: "{\"Version\": \"2012-10-17\", \"Statement\": [{ \"Sid\": \"id-1\",\"Effect\": \"Allow\",\"Principal\": {\"AWS\": \"arn:aws:iam::123456789012:root\"}, \"Action\": [ \"s3:PutObject\",\"s3:PutObjectAcl\"], \"Resource\": [\"arn:aws:s3:::acl3/*\" ] } ]}"
};
s3.putBucketPolicy(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the putBucketPolicy operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Policy: 'STRING_VALUE', /* required */
ConfirmRemoveSelfBucketAccess: true || false,
ContentMD5: 'STRING_VALUE'
};
s3.putBucketPolicy(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)ContentMD5
— (String
)ConfirmRemoveSelfBucketAccess
— (Boolean
)Set this parameter to true to confirm that you want to remove your permissions to change this bucket policy in the future.
Policy
— (String
)The bucket policy as a JSON document.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketReplication(params = {}, callback) ⇒ AWS.Request
Creates a replication configuration or replaces an existing one. For more information, see Cross-Region Replication (CRR) in the Amazon S3 Developer Guide.
Service Reference:
Examples:
Set replication configuration on a bucket
/* The following example sets replication configuration on a bucket. */
var params = {
Bucket: "examplebucket",
ReplicationConfiguration: {
Role: "arn:aws:iam::123456789012:role/examplerole",
Rules: [
{
Destination: {
Bucket: "arn:aws:s3:::destinationbucket",
StorageClass: "STANDARD"
},
Prefix: "",
Status: "Enabled"
}
]
}
};
s3.putBucketReplication(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the putBucketReplication operation
var params = {
Bucket: 'STRING_VALUE', /* required */
ReplicationConfiguration: { /* required */
Role: 'STRING_VALUE', /* required */
Rules: [ /* required */
{
Destination: { /* required */
Bucket: 'STRING_VALUE', /* required */
AccessControlTranslation: {
Owner: Destination /* required */
},
Account: 'STRING_VALUE',
EncryptionConfiguration: {
ReplicaKmsKeyID: 'STRING_VALUE'
},
StorageClass: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE
},
Status: Enabled | Disabled, /* required */
DeleteMarkerReplication: {
Status: Enabled | Disabled
},
Filter: {
And: {
Prefix: 'STRING_VALUE',
Tags: [
{
Key: 'STRING_VALUE', /* required */
Value: 'STRING_VALUE' /* required */
},
/* more items */
]
},
Prefix: 'STRING_VALUE',
Tag: {
Key: 'STRING_VALUE', /* required */
Value: 'STRING_VALUE' /* required */
}
},
ID: 'STRING_VALUE',
Prefix: 'STRING_VALUE',
Priority: 'NUMBER_VALUE',
SourceSelectionCriteria: {
SseKmsEncryptedObjects: {
Status: Enabled | Disabled /* required */
}
}
},
/* more items */
]
},
ContentMD5: 'STRING_VALUE'
};
s3.putBucketReplication(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)ContentMD5
— (String
)ReplicationConfiguration
— (map
)A container for replication rules. You can add up to 1,000 rules. The maximum size of a replication configuration is 2 MB.
Role
— required — (String
)The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that Amazon S3 can assume when replicating the objects.
Rules
— required — (Array<map>
)A container for one or more replication rules. A replication configuration must have at least one rule and can contain a maximum of 1,000 rules.
ID
— (String
)A unique identifier for the rule. The maximum value is 255 characters.
Priority
— (Integer
)The priority associated with the rule. If you specify multiple rules in a replication configuration, Amazon S3 prioritizes the rules to prevent conflicts when filtering. If two or more rules identify the same object based on a specified filter, the rule with higher priority takes precedence. For example:
-
Same object quality prefix based filter criteria If prefixes you specified in multiple rules overlap
-
Same object qualify tag based filter criteria specified in multiple rules
For more information, see Cross-Region Replication (CRR) in the Amazon S3 Developer Guide.
-
Prefix
— (String
)An object keyname prefix that identifies the object or objects to which the rule applies. The maximum prefix length is 1,024 characters.
Filter
— (map
)A filter that identifies the subset of objects to which the replication rule applies. A
Filter
must specify exactly onePrefix
,Tag
, or anAnd
child element.Prefix
— (String
)An object keyname prefix that identifies the subset of objects to which the rule applies.
Tag
— (map
)A container for specifying a tag key and value.
The rule applies only to objects that have the tag in their tag set.
Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
And
— (map
)A container for specifying rule filters. The filters determine the subset of objects to which the rule applies. This element is required only if you specify more than one filter. For example:
-
If you specify both a
Prefix
and aTag
filter, wrap these filters in anAnd
tag. -
If you specify a filter based on multiple tags, wrap the
Tag
elements in anAnd
tag.
Prefix
— (String
)Tags
— (Array<map>
)Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
-
Status
— required — (String
)If status isn't enabled, the rule is ignored.
Possible values include:"Enabled"
"Disabled"
SourceSelectionCriteria
— (map
)A container that describes additional filters for identifying the source objects that you want to replicate. You can choose to enable or disable the replication of these objects. Currently, Amazon S3 supports only the filter that you can specify for objects created with server-side encryption using an AWS KMS-Managed Key (SSE-KMS).
If you want Amazon S3 to replicate objects created with server-side encryption using AWS KMS-Managed Keys.
SseKmsEncryptedObjects
— (map
)A container for filter information for the selection of S3 objects encrypted with AWS KMS. If you include
SourceSelectionCriteria
in the replication configuration, this element is required.Status
— required — (String
)If the status is not
Possible values include:Enabled
, replication for S3 objects encrypted with AWS KMS is disabled."Enabled"
"Disabled"
Destination
— required — (map
)A container for information about the replication destination.
Bucket
— required — (String
)The Amazon Resource Name (ARN) of the bucket where you want Amazon S3 to store replicas of the object identified by the rule.
If there are multiple rules in your replication configuration, all rules must specify the same bucket as the destination. A replication configuration can replicate objects to only one destination bucket.
Account
— (String
)The account ID of the destination bucket. Currently, Amazon S3 verifies this value only if Access Control Translation is enabled.
In a cross-account scenario, if you change replica ownership to the AWS account that owns the destination bucket by adding the
AccessControlTranslation
element, this is the account ID of the owner of the destination bucket.StorageClass
— (String
)The class of storage used to store the object. By default Amazon S3 uses storage class of the source object when creating a replica.
Possible values include:"STANDARD"
"REDUCED_REDUNDANCY"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"GLACIER"
"DEEP_ARCHIVE"
AccessControlTranslation
— (map
)A container for information about access control for replicas.
Use this element only in a cross-account scenario where source and destination bucket owners are not the same to change replica ownership to the AWS account that owns the destination bucket. If you don't add this element to the replication configuration, the replicas are owned by same AWS account that owns the source object.
Owner
— required — (String
)The override value for the owner of the replica object.
Possible values include:"Destination"
EncryptionConfiguration
— (map
)A container that provides information about encryption. If
SourceSelectionCriteria
is specified, you must specify this element.ReplicaKmsKeyID
— (String
)The ID of the AWS KMS key for the AWS Region where the destination bucket resides. Amazon S3 uses this key to encrypt the replica object.
DeleteMarkerReplication
— (map
)Specifies whether Amazon S3 should replicate delete makers.
Status
— (String
)The status of the delete marker replication.
Note: In the current implementation, Amazon S3 doesn't replicate the delete markers. The status must bePossible values include:Disabled
."Enabled"
"Disabled"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketRequestPayment(params = {}, callback) ⇒ AWS.Request
Sets the request payment configuration for a bucket. By default, the bucket owner pays for downloads from the bucket. This configuration parameter enables the bucket owner (only) to specify that the person requesting the download will be charged for the download. Documentation on requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/RequesterPaysBuckets.html
Service Reference:
Examples:
Set request payment configuration on a bucket.
/* The following example sets request payment configuration on a bucket so that person requesting the download is charged. */
var params = {
Bucket: "examplebucket",
RequestPaymentConfiguration: {
Payer: "Requester"
}
};
s3.putBucketRequestPayment(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the putBucketRequestPayment operation
var params = {
Bucket: 'STRING_VALUE', /* required */
RequestPaymentConfiguration: { /* required */
Payer: Requester | BucketOwner /* required */
},
ContentMD5: 'STRING_VALUE'
};
s3.putBucketRequestPayment(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)ContentMD5
— (String
)RequestPaymentConfiguration
— (map
)Payer
— required — (String
)Specifies who pays for the download and request fees.
Possible values include:"Requester"
"BucketOwner"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketTagging(params = {}, callback) ⇒ AWS.Request
Sets the tags for a bucket.
Service Reference:
Examples:
Set tags on a bucket
/* The following example sets tags on a bucket. Any existing tags are replaced. */
var params = {
Bucket: "examplebucket",
Tagging: {
TagSet: [
{
Key: "Key1",
Value: "Value1"
},
{
Key: "Key2",
Value: "Value2"
}
]
}
};
s3.putBucketTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the putBucketTagging operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Tagging: { /* required */
TagSet: [ /* required */
{
Key: 'STRING_VALUE', /* required */
Value: 'STRING_VALUE' /* required */
},
/* more items */
]
},
ContentMD5: 'STRING_VALUE'
};
s3.putBucketTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)ContentMD5
— (String
)Tagging
— (map
)TagSet
— required — (Array<map>
)Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketVersioning(params = {}, callback) ⇒ AWS.Request
Sets the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner.
Service Reference:
Examples:
Set versioning configuration on a bucket
/* The following example sets versioning configuration on bucket. The configuration enables versioning on the bucket. */
var params = {
Bucket: "examplebucket",
VersioningConfiguration: {
MFADelete: "Disabled",
Status: "Enabled"
}
};
s3.putBucketVersioning(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the putBucketVersioning operation
var params = {
Bucket: 'STRING_VALUE', /* required */
VersioningConfiguration: { /* required */
MFADelete: Enabled | Disabled,
Status: Enabled | Suspended
},
ContentMD5: 'STRING_VALUE',
MFA: 'STRING_VALUE'
};
s3.putBucketVersioning(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)ContentMD5
— (String
)MFA
— (String
)The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
VersioningConfiguration
— (map
)MFADelete
— (String
)Specifies whether MFA delete is enabled in the bucket versioning configuration. This element is only returned if the bucket has been configured with MFA delete. If the bucket has never been so configured, this element is not returned.
Possible values include:"Enabled"
"Disabled"
Status
— (String
)The versioning state of the bucket.
Possible values include:"Enabled"
"Suspended"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putBucketWebsite(params = {}, callback) ⇒ AWS.Request
Set the website configuration for a bucket.
Service Reference:
Examples:
Set website configuration on a bucket
/* The following example adds website configuration to a bucket. */
var params = {
Bucket: "examplebucket",
ContentMD5: "",
WebsiteConfiguration: {
ErrorDocument: {
Key: "error.html"
},
IndexDocument: {
Suffix: "index.html"
}
}
};
s3.putBucketWebsite(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Calling the putBucketWebsite operation
var params = {
Bucket: 'STRING_VALUE', /* required */
WebsiteConfiguration: { /* required */
ErrorDocument: {
Key: 'STRING_VALUE' /* required */
},
IndexDocument: {
Suffix: 'STRING_VALUE' /* required */
},
RedirectAllRequestsTo: {
HostName: 'STRING_VALUE', /* required */
Protocol: http | https
},
RoutingRules: [
{
Redirect: { /* required */
HostName: 'STRING_VALUE',
HttpRedirectCode: 'STRING_VALUE',
Protocol: http | https,
ReplaceKeyPrefixWith: 'STRING_VALUE',
ReplaceKeyWith: 'STRING_VALUE'
},
Condition: {
HttpErrorCodeReturnedEquals: 'STRING_VALUE',
KeyPrefixEquals: 'STRING_VALUE'
}
},
/* more items */
]
},
ContentMD5: 'STRING_VALUE'
};
s3.putBucketWebsite(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)ContentMD5
— (String
)WebsiteConfiguration
— (map
)ErrorDocument
— (map
)Key
— required — (String
)The object key name to use when a 4XX class error occurs.
IndexDocument
— (map
)Suffix
— required — (String
)A suffix that is appended to a request that is for a directory on the website endpoint (e.g. if the suffix is index.html and you make a request to samplebucket/images/ the data that is returned will be for the object with the key name images/index.html) The suffix must not be empty and must not include a slash character.
RedirectAllRequestsTo
— (map
)HostName
— required — (String
)Name of the host where requests will be redirected.
Protocol
— (String
)Protocol to use (http, https) when redirecting requests. The default is the protocol that is used in the original request.
Possible values include:"http"
"https"
RoutingRules
— (Array<map>
)Condition
— (map
)A container for describing a condition that must be met for the specified redirect to apply. For example, 1. If request is for pages in the /docs folder, redirect to the /documents folder. 2. If request results in HTTP error 4xx, redirect request to another host where you might process the error.
HttpErrorCodeReturnedEquals
— (String
)The HTTP error code when the redirect is applied. In the event of an error, if the error code equals this value, then the specified redirect is applied. Required when parent element Condition is specified and sibling KeyPrefixEquals is not specified. If both are specified, then both must be true for the redirect to be applied.
KeyPrefixEquals
— (String
)The object key name prefix when the redirect is applied. For example, to redirect requests for ExamplePage.html, the key prefix will be ExamplePage.html. To redirect request for all pages with the prefix docs/, the key prefix will be /docs, which identifies all objects in the docs/ folder. Required when the parent element Condition is specified and sibling HttpErrorCodeReturnedEquals is not specified. If both conditions are specified, both must be true for the redirect to be applied.
Redirect
— required — (map
)Container for redirect information. You can redirect requests to another host, to another page, or with another protocol. In the event of an error, you can specify a different error code to return.
HostName
— (String
)The host name to use in the redirect request.
HttpRedirectCode
— (String
)The HTTP redirect code to use on the response. Not required if one of the siblings is present.
Protocol
— (String
)Protocol to use (http, https) when redirecting requests. The default is the protocol that is used in the original request.
Possible values include:"http"
"https"
ReplaceKeyPrefixWith
— (String
)The object key prefix to use in the redirect request. For example, to redirect requests for all pages with prefix docs/ (objects in the docs/ folder) to documents/, you can set a condition block with KeyPrefixEquals set to docs/ and in the Redirect set ReplaceKeyPrefixWith to /documents. Not required if one of the siblings is present. Can be present only if ReplaceKeyWith is not provided.
ReplaceKeyWith
— (String
)The specific object key to use in the redirect request. For example, redirect request to error.html. Not required if one of the sibling is present. Can be present only if ReplaceKeyPrefixWith is not provided.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
putObject(params = {}, callback) ⇒ AWS.Request
Adds an object to a bucket.
Service Reference:
Examples:
To upload an object and specify optional tags
/* The following example uploads an object. The request specifies optional object tags. The bucket is versioned, therefore S3 returns version ID of the newly created object. */
var params = {
Body: <Binary String>,
Bucket: "examplebucket",
Key: "HappyFace.jpg",
Tagging: "key1=value1&key2=value2"
};
s3.putObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
ETag: "\"6805f2cfc46c0f04559748bb039d69ae\"",
VersionId: "psM2sYY4.o1501dSx8wMvnkOzSBB.V4a"
}
*/
});
To upload an object and specify canned ACL.
/* The following example uploads and object. The request specifies optional canned ACL (access control list) to all READ access to authenticated users. If the bucket is versioning enabled, S3 returns version ID in response. */
var params = {
ACL: "authenticated-read",
Body: <Binary String>,
Bucket: "examplebucket",
Key: "exampleobject"
};
s3.putObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
ETag: "\"6805f2cfc46c0f04559748bb039d69ae\"",
VersionId: "Kirh.unyZwjQ69YxcQLA8z4F5j3kJJKr"
}
*/
});
To create an object.
/* The following example creates an object. If the bucket is versioning enabled, S3 returns version ID in response. */
var params = {
Body: <Binary String>,
Bucket: "examplebucket",
Key: "objectkey"
};
s3.putObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
ETag: "\"6805f2cfc46c0f04559748bb039d69ae\"",
VersionId: "Bvq0EDKxOcXLJXNo_Lkz37eM3R4pfzyQ"
}
*/
});
To upload an object (specify optional headers)
/* The following example uploads an object. The request specifies optional request headers to directs S3 to use specific storage class and use server-side encryption. */
var params = {
Body: <Binary String>,
Bucket: "examplebucket",
Key: "HappyFace.jpg",
ServerSideEncryption: "AES256",
StorageClass: "STANDARD_IA"
};
s3.putObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
ETag: "\"6805f2cfc46c0f04559748bb039d69ae\"",
ServerSideEncryption: "AES256",
VersionId: "CG612hodqujkf8FaaNfp8U..FIhLROcp"
}
*/
});
To upload an object
/* The following example uploads an object to a versioning-enabled bucket. The source file is specified using Windows file syntax. S3 returns VersionId of the newly created object. */
var params = {
Body: <Binary String>,
Bucket: "examplebucket",
Key: "HappyFace.jpg"
};
s3.putObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
ETag: "\"6805f2cfc46c0f04559748bb039d69ae\"",
VersionId: "tpf3zF08nBplQK1XLOefGskR7mGDwcDk"
}
*/
});
To upload object and specify user-defined metadata
/* The following example creates an object. The request also specifies optional metadata. If the bucket is versioning enabled, S3 returns version ID in response. */
var params = {
Body: <Binary String>,
Bucket: "examplebucket",
Key: "exampleobject",
Metadata: {
"metadata1": "value1",
"metadata2": "value2"
}
};
s3.putObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
ETag: "\"6805f2cfc46c0f04559748bb039d69ae\"",
VersionId: "pSKidl4pHBiNwukdbcPXAIs.sshFFOc0"
}
*/
});
To upload an object and specify server-side encryption and object tags
/* The following example uploads and object. The request specifies the optional server-side encryption option. The request also specifies optional object tags. If the bucket is versioning enabled, S3 returns version ID in response. */
var params = {
Body: <Binary String>,
Bucket: "examplebucket",
Key: "exampleobject",
ServerSideEncryption: "AES256",
Tagging: "key1=value1&key2=value2"
};
s3.putObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
ETag: "\"6805f2cfc46c0f04559748bb039d69ae\"",
ServerSideEncryption: "AES256",
VersionId: "Ri.vC6qVlA4dEnjgRV4ZHsHoFIjqEMNt"
}
*/
});
Calling the putObject operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
ACL: private | public-read | public-read-write | authenticated-read | aws-exec-read | bucket-owner-read | bucket-owner-full-control,
Body: new Buffer('...') || 'STRING_VALUE' || streamObject,
CacheControl: 'STRING_VALUE',
ContentDisposition: 'STRING_VALUE',
ContentEncoding: 'STRING_VALUE',
ContentLanguage: 'STRING_VALUE',
ContentLength: 'NUMBER_VALUE',
ContentMD5: 'STRING_VALUE',
ContentType: 'STRING_VALUE',
Expires: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
GrantFullControl: 'STRING_VALUE',
GrantRead: 'STRING_VALUE',
GrantReadACP: 'STRING_VALUE',
GrantWriteACP: 'STRING_VALUE',
Metadata: {
'<MetadataKey>': 'STRING_VALUE',
/* '<MetadataKey>': ... */
},
ObjectLockLegalHoldStatus: ON | OFF,
ObjectLockMode: GOVERNANCE | COMPLIANCE,
ObjectLockRetainUntilDate: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
RequestPayer: requester,
SSECustomerAlgorithm: 'STRING_VALUE',
SSECustomerKey: new Buffer('...') || 'STRING_VALUE' /* Strings will be Base-64 encoded on your behalf */,
SSECustomerKeyMD5: 'STRING_VALUE',
SSEKMSKeyId: 'STRING_VALUE',
ServerSideEncryption: AES256 | aws:kms,
StorageClass: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE,
Tagging: 'STRING_VALUE',
WebsiteRedirectLocation: 'STRING_VALUE'
};
s3.putObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
ACL
— (String
)The canned ACL to apply to the object.
Possible values include:"private"
"public-read"
"public-read-write"
"authenticated-read"
"aws-exec-read"
"bucket-owner-read"
"bucket-owner-full-control"
Body
— (Buffer, Typed Array, Blob, String, ReadableStream
)Object data.
Bucket
— (String
)Name of the bucket to which the PUT operation was initiated.
CacheControl
— (String
)Specifies caching behavior along the request/reply chain.
ContentDisposition
— (String
)Specifies presentational information for the object.
ContentEncoding
— (String
)Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
ContentLanguage
— (String
)The language the content is in.
ContentLength
— (Integer
)Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically.
ContentMD5
— (String
)The base64-encoded 128-bit MD5 digest of the part data. This parameter is auto-populated when using the command from the CLI
ContentType
— (String
)A standard MIME type describing the format of the object data.
Expires
— (Date
)The date and time at which the object is no longer cacheable.
GrantFullControl
— (String
)Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
GrantRead
— (String
)Allows grantee to read the object data and its metadata.
GrantReadACP
— (String
)Allows grantee to read the object ACL.
GrantWriteACP
— (String
)Allows grantee to write the ACL for the applicable object.
Key
— (String
)Object key for which the PUT operation was initiated.
Metadata
— (map<String>
)A map of metadata to store with the object in S3.
ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
StorageClass
— (String
)The type of storage to use for the object. Defaults to 'STANDARD'.
Possible values include:"STANDARD"
"REDUCED_REDUNDANCY"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"GLACIER"
"DEEP_ARCHIVE"
WebsiteRedirectLocation
— (String
)If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
SSECustomerAlgorithm
— (String
)Specifies the algorithm to use to when encrypting the object (e.g., AES256).
SSECustomerKey
— (Buffer, Typed Array, Blob, String
)Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
SSECustomerKeyMD5
— (String
)Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
SSEKMSKeyId
— (String
)Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Tagging
— (String
)The tag-set for the object. The tag-set must be encoded as URL Query parameters. (For example, "Key1=Value1")
ObjectLockMode
— (String
)The Object Lock mode that you want to apply to this object.
Possible values include:"GOVERNANCE"
"COMPLIANCE"
ObjectLockRetainUntilDate
— (Date
)The date and time when you want this object's Object Lock to expire.
ObjectLockLegalHoldStatus
— (String
)The Legal Hold status that you want to apply to the specified object.
Possible values include:"ON"
"OFF"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Expiration
— (String
)If the object expiration is configured, this will contain the expiration date (expiry-date) and rule ID (rule-id). The value of rule-id is URL encoded.
ETag
— (String
)Entity tag for the uploaded object.
ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
VersionId
— (String
)Version of the object.
SSECustomerAlgorithm
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
SSECustomerKeyMD5
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
SSEKMSKeyId
— (String
)If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
putObjectAcl(params = {}, callback) ⇒ AWS.Request
uses the acl subresource to set the access control list (ACL) permissions for an object that already exists in a bucket
Service Reference:
Examples:
To grant permissions using object ACL
/* The following example adds grants to an object ACL. The first permission grants user1 and user2 FULL_CONTROL and the AllUsers group READ permission. */
var params = {
AccessControlPolicy: {
},
Bucket: "examplebucket",
GrantFullControl: "emailaddress=user1@example.com,emailaddress=user2@example.com",
GrantRead: "uri=http://acs.amazonaws.com/groups/global/AllUsers",
Key: "HappyFace.jpg"
};
s3.putObjectAcl(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
}
*/
});
Calling the putObjectAcl operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
ACL: private | public-read | public-read-write | authenticated-read | aws-exec-read | bucket-owner-read | bucket-owner-full-control,
AccessControlPolicy: {
Grants: [
{
Grantee: {
Type: CanonicalUser | AmazonCustomerByEmail | Group, /* required */
DisplayName: 'STRING_VALUE',
EmailAddress: 'STRING_VALUE',
ID: 'STRING_VALUE',
URI: 'STRING_VALUE'
},
Permission: FULL_CONTROL | WRITE | WRITE_ACP | READ | READ_ACP
},
/* more items */
],
Owner: {
DisplayName: 'STRING_VALUE',
ID: 'STRING_VALUE'
}
},
ContentMD5: 'STRING_VALUE',
GrantFullControl: 'STRING_VALUE',
GrantRead: 'STRING_VALUE',
GrantReadACP: 'STRING_VALUE',
GrantWrite: 'STRING_VALUE',
GrantWriteACP: 'STRING_VALUE',
RequestPayer: requester,
VersionId: 'STRING_VALUE'
};
s3.putObjectAcl(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
ACL
— (String
)The canned ACL to apply to the object.
Possible values include:"private"
"public-read"
"public-read-write"
"authenticated-read"
"aws-exec-read"
"bucket-owner-read"
"bucket-owner-full-control"
AccessControlPolicy
— (map
)Grants
— (Array<map>
)A list of grants.
Grantee
— (map
)DisplayName
— (String
)Screen name of the grantee.
EmailAddress
— (String
)Email address of the grantee.
ID
— (String
)The canonical user ID of the grantee.
Type
— required — (String
)Type of grantee
Possible values include:"CanonicalUser"
"AmazonCustomerByEmail"
"Group"
URI
— (String
)URI of the grantee group.
Permission
— (String
)Specifies the permission given to the grantee.
Possible values include:"FULL_CONTROL"
"WRITE"
"WRITE_ACP"
"READ"
"READ_ACP"
Owner
— (map
)DisplayName
— (String
)ID
— (String
)
Bucket
— (String
)ContentMD5
— (String
)GrantFullControl
— (String
)Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
GrantRead
— (String
)Allows grantee to list the objects in the bucket.
GrantReadACP
— (String
)Allows grantee to read the bucket ACL.
GrantWrite
— (String
)Allows grantee to create, overwrite, and delete any object in the bucket.
GrantWriteACP
— (String
)Allows grantee to write the ACL for the applicable bucket.
Key
— (String
)RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
VersionId
— (String
)VersionId used to reference a specific version of the object.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
putObjectLegalHold(params = {}, callback) ⇒ AWS.Request
Applies a Legal Hold configuration to the specified object.
Service Reference:
Examples:
Calling the putObjectLegalHold operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
ContentMD5: 'STRING_VALUE',
LegalHold: {
Status: ON | OFF
},
RequestPayer: requester,
VersionId: 'STRING_VALUE'
};
s3.putObjectLegalHold(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The bucket containing the object that you want to place a Legal Hold on.
Key
— (String
)The key name for the object that you want to place a Legal Hold on.
LegalHold
— (map
)Container element for the Legal Hold configuration you want to apply to the specified object.
Status
— (String
)Indicates whether the specified object has a Legal Hold in place.
Possible values include:"ON"
"OFF"
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
VersionId
— (String
)The version ID of the object that you want to place a Legal Hold on.
ContentMD5
— (String
)The MD5 hash for the request body.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
putObjectLockConfiguration(params = {}, callback) ⇒ AWS.Request
Places an Object Lock configuration on the specified bucket. The rule specified in the Object Lock configuration will be applied by default to every new object placed in the specified bucket.
Service Reference:
Examples:
Calling the putObjectLockConfiguration operation
var params = {
Bucket: 'STRING_VALUE', /* required */
ContentMD5: 'STRING_VALUE',
ObjectLockConfiguration: {
ObjectLockEnabled: Enabled,
Rule: {
DefaultRetention: {
Days: 'NUMBER_VALUE',
Mode: GOVERNANCE | COMPLIANCE,
Years: 'NUMBER_VALUE'
}
}
},
RequestPayer: requester,
Token: 'STRING_VALUE'
};
s3.putObjectLockConfiguration(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The bucket whose Object Lock configuration you want to create or replace.
ObjectLockConfiguration
— (map
)The Object Lock configuration that you want to apply to the specified bucket.
ObjectLockEnabled
— (String
)Indicates whether this bucket has an Object Lock configuration enabled.
Possible values include:"Enabled"
Rule
— (map
)The Object Lock rule in place for the specified object.
DefaultRetention
— (map
)The default retention period that you want to apply to new objects placed in the specified bucket.
Mode
— (String
)The default Object Lock retention mode you want to apply to new objects placed in the specified bucket.
Possible values include:"GOVERNANCE"
"COMPLIANCE"
Days
— (Integer
)The number of days that you want to specify for the default retention period.
Years
— (Integer
)The number of years that you want to specify for the default retention period.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Token
— (String
)A token to allow Object Lock to be enabled for an existing bucket.
ContentMD5
— (String
)The MD5 hash for the request body.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
putObjectRetention(params = {}, callback) ⇒ AWS.Request
Places an Object Retention configuration on an object.
Service Reference:
Examples:
Calling the putObjectRetention operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
BypassGovernanceRetention: true || false,
ContentMD5: 'STRING_VALUE',
RequestPayer: requester,
Retention: {
Mode: GOVERNANCE | COMPLIANCE,
RetainUntilDate: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789
},
VersionId: 'STRING_VALUE'
};
s3.putObjectRetention(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The bucket that contains the object you want to apply this Object Retention configuration to.
Key
— (String
)The key name for the object that you want to apply this Object Retention configuration to.
Retention
— (map
)The container element for the Object Retention configuration.
Mode
— (String
)Indicates the Retention mode for the specified object.
Possible values include:"GOVERNANCE"
"COMPLIANCE"
RetainUntilDate
— (Date
)The date on which this Object Lock Retention will expire.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
VersionId
— (String
)The version ID for the object that you want to apply this Object Retention configuration to.
BypassGovernanceRetention
— (Boolean
)Indicates whether this operation should bypass Governance-mode restrictions.j
ContentMD5
— (String
)The MD5 hash for the request body.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
putObjectTagging(params = {}, callback) ⇒ AWS.Request
Sets the supplied tag-set to an object that already exists in a bucket
Service Reference:
Examples:
To add tags to an existing object
/* The following example adds tags to an existing object. */
var params = {
Bucket: "examplebucket",
Key: "HappyFace.jpg",
Tagging: {
TagSet: [
{
Key: "Key3",
Value: "Value3"
},
{
Key: "Key4",
Value: "Value4"
}
]
}
};
s3.putObjectTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
VersionId: "null"
}
*/
});
Calling the putObjectTagging operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
Tagging: { /* required */
TagSet: [ /* required */
{
Key: 'STRING_VALUE', /* required */
Value: 'STRING_VALUE' /* required */
},
/* more items */
]
},
ContentMD5: 'STRING_VALUE',
VersionId: 'STRING_VALUE'
};
s3.putObjectTagging(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Key
— (String
)VersionId
— (String
)ContentMD5
— (String
)Tagging
— (map
)TagSet
— required — (Array<map>
)Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:VersionId
— (String
)
-
(AWS.Response)
—
Returns:
putPublicAccessBlock(params = {}, callback) ⇒ AWS.Request
Creates or modifies the PublicAccessBlock
configuration for an Amazon S3 bucket.
Service Reference:
Examples:
Calling the putPublicAccessBlock operation
var params = {
Bucket: 'STRING_VALUE', /* required */
PublicAccessBlockConfiguration: { /* required */
BlockPublicAcls: true || false,
BlockPublicPolicy: true || false,
IgnorePublicAcls: true || false,
RestrictPublicBuckets: true || false
},
ContentMD5: 'STRING_VALUE'
};
s3.putPublicAccessBlock(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The name of the Amazon S3 bucket whose
PublicAccessBlock
configuration you want to set.ContentMD5
— (String
)The MD5 hash of the
PutPublicAccessBlock
request body.PublicAccessBlockConfiguration
— (map
)The
PublicAccessBlock
configuration that you want to apply to this Amazon S3 bucket. You can enable the configuration options in any combination. For more information about when Amazon S3 considers a bucket or object public, see The Meaning of "Public" in the Amazon Simple Storage Service Developer Guide.BlockPublicAcls
— (Boolean
)Specifies whether Amazon S3 should block public access control lists (ACLs) for this bucket and objects in this bucket. Setting this element to
TRUE
causes the following behavior:-
PUT Bucket acl and PUT Object acl calls fail if the specified ACL is public.
-
PUT Object calls fail if the request includes a public ACL.
Enabling this setting doesn't affect existing policies or ACLs.
-
IgnorePublicAcls
— (Boolean
)Specifies whether Amazon S3 should ignore public ACLs for this bucket and objects in this bucket. Setting this element to
TRUE
causes Amazon S3 to ignore all public ACLs on this bucket and objects in this bucket.Enabling this setting doesn't affect the persistence of any existing ACLs and doesn't prevent new public ACLs from being set.
BlockPublicPolicy
— (Boolean
)Specifies whether Amazon S3 should block public bucket policies for this bucket. Setting this element to
TRUE
causes Amazon S3 to reject calls to PUT Bucket policy if the specified bucket policy allows public access.Enabling this setting doesn't affect existing bucket policies.
RestrictPublicBuckets
— (Boolean
)Specifies whether Amazon S3 should restrict public bucket policies for this bucket. Setting this element to
TRUE
restricts access to this bucket to only AWS services and authorized users within this account if the bucket has a public policy.Enabling this setting doesn't affect previously stored bucket policies, except that public and cross-account access within any public bucket policy, including non-public delegation to specific accounts, is blocked.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
restoreObject(params = {}, callback) ⇒ AWS.Request
Restores an archived copy of an object back into Amazon S3
Service Reference:
Examples:
To restore an archived object
/* The following example restores for one day an archived copy of an object back into Amazon S3 bucket. */
var params = {
Bucket: "examplebucket",
Key: "archivedobjectkey",
RestoreRequest: {
Days: 1,
GlacierJobParameters: {
Tier: "Expedited"
}
}
};
s3.restoreObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
}
*/
});
Calling the restoreObject operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
RequestPayer: requester,
RestoreRequest: {
Days: 'NUMBER_VALUE',
Description: 'STRING_VALUE',
GlacierJobParameters: {
Tier: Standard | Bulk | Expedited /* required */
},
OutputLocation: {
S3: {
BucketName: 'STRING_VALUE', /* required */
Prefix: 'STRING_VALUE', /* required */
AccessControlList: [
{
Grantee: {
Type: CanonicalUser | AmazonCustomerByEmail | Group, /* required */
DisplayName: 'STRING_VALUE',
EmailAddress: 'STRING_VALUE',
ID: 'STRING_VALUE',
URI: 'STRING_VALUE'
},
Permission: FULL_CONTROL | WRITE | WRITE_ACP | READ | READ_ACP
},
/* more items */
],
CannedACL: private | public-read | public-read-write | authenticated-read | aws-exec-read | bucket-owner-read | bucket-owner-full-control,
Encryption: {
EncryptionType: AES256 | aws:kms, /* required */
KMSContext: 'STRING_VALUE',
KMSKeyId: 'STRING_VALUE'
},
StorageClass: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE,
Tagging: {
TagSet: [ /* required */
{
Key: 'STRING_VALUE', /* required */
Value: 'STRING_VALUE' /* required */
},
/* more items */
]
},
UserMetadata: [
{
Name: 'STRING_VALUE',
Value: 'STRING_VALUE'
},
/* more items */
]
}
},
SelectParameters: {
Expression: 'STRING_VALUE', /* required */
ExpressionType: SQL, /* required */
InputSerialization: { /* required */
CSV: {
AllowQuotedRecordDelimiter: true || false,
Comments: 'STRING_VALUE',
FieldDelimiter: 'STRING_VALUE',
FileHeaderInfo: USE | IGNORE | NONE,
QuoteCharacter: 'STRING_VALUE',
QuoteEscapeCharacter: 'STRING_VALUE',
RecordDelimiter: 'STRING_VALUE'
},
CompressionType: NONE | GZIP | BZIP2,
JSON: {
Type: DOCUMENT | LINES
},
Parquet: {
}
},
OutputSerialization: { /* required */
CSV: {
FieldDelimiter: 'STRING_VALUE',
QuoteCharacter: 'STRING_VALUE',
QuoteEscapeCharacter: 'STRING_VALUE',
QuoteFields: ALWAYS | ASNEEDED,
RecordDelimiter: 'STRING_VALUE'
},
JSON: {
RecordDelimiter: 'STRING_VALUE'
}
}
},
Tier: Standard | Bulk | Expedited,
Type: SELECT
},
VersionId: 'STRING_VALUE'
};
s3.restoreObject(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)Key
— (String
)VersionId
— (String
)RestoreRequest
— (map
)Container for restore job parameters.
Days
— (Integer
)Lifetime of the active copy in days. Do not use with restores that specify OutputLocation.
GlacierJobParameters
— (map
)Glacier related parameters pertaining to this job. Do not use with restores that specify OutputLocation.
Tier
— required — (String
)Glacier retrieval tier at which the restore will be processed.
Possible values include:"Standard"
"Bulk"
"Expedited"
Type
— (String
)Type of restore request.
Possible values include:"SELECT"
Tier
— (String
)Glacier retrieval tier at which the restore will be processed.
Possible values include:"Standard"
"Bulk"
"Expedited"
Description
— (String
)The optional description for the job.
SelectParameters
— (map
)Describes the parameters for Select job types.
InputSerialization
— required — (map
)Describes the serialization format of the object.
CSV
— (map
)Describes the serialization of a CSV-encoded object.
FileHeaderInfo
— (String
)Describes the first line of input. Valid values: None, Ignore, Use.
Possible values include:"USE"
"IGNORE"
"NONE"
Comments
— (String
)The single character used to indicate a row should be ignored when present at the start of a row.
QuoteEscapeCharacter
— (String
)The single character used for escaping the quote character inside an already escaped value.
RecordDelimiter
— (String
)The value used to separate individual records.
FieldDelimiter
— (String
)The value used to separate individual fields in a record.
QuoteCharacter
— (String
)Value used for escaping where the field delimiter is part of the value.
AllowQuotedRecordDelimiter
— (Boolean
)Specifies that CSV field values may contain quoted record delimiters and such records should be allowed. Default value is FALSE. Setting this value to TRUE may lower performance.
CompressionType
— (String
)Specifies object's compression format. Valid values: NONE, GZIP, BZIP2. Default Value: NONE.
Possible values include:"NONE"
"GZIP"
"BZIP2"
JSON
— (map
)Specifies JSON as object's input serialization format.
Type
— (String
)The type of JSON. Valid values: Document, Lines.
Possible values include:"DOCUMENT"
"LINES"
Parquet
— (map
)Specifies Parquet as object's input serialization format.
ExpressionType
— required — (String
)The type of the provided expression (e.g., SQL).
Possible values include:"SQL"
Expression
— required — (String
)The expression that is used to query the object.
OutputSerialization
— required — (map
)Describes how the results of the Select job are serialized.
CSV
— (map
)Describes the serialization of CSV-encoded Select results.
QuoteFields
— (String
)Indicates whether or not all output fields should be quoted.
Possible values include:"ALWAYS"
"ASNEEDED"
QuoteEscapeCharacter
— (String
)Th single character used for escaping the quote character inside an already escaped value.
RecordDelimiter
— (String
)The value used to separate individual records.
FieldDelimiter
— (String
)The value used to separate individual fields in a record.
QuoteCharacter
— (String
)The value used for escaping where the field delimiter is part of the value.
JSON
— (map
)Specifies JSON as request's output serialization format.
RecordDelimiter
— (String
)The value used to separate individual records in the output.
OutputLocation
— (map
)Describes the location where the restore job's output is stored.
S3
— (map
)Describes an S3 location that will receive the results of the restore request.
BucketName
— required — (String
)The name of the bucket where the restore results will be placed.
Prefix
— required — (String
)The prefix that is prepended to the restore results for this request.
Encryption
— (map
)Describes the server-side encryption that will be applied to the restore results.
EncryptionType
— required — (String
)The server-side encryption algorithm used when storing job results in Amazon S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
KMSKeyId
— (String
)If the encryption type is aws:kms, this optional value specifies the AWS KMS key ID to use for encryption of job results.
KMSContext
— (String
)If the encryption type is aws:kms, this optional value can be used to specify the encryption context for the restore results.
CannedACL
— (String
)The canned ACL to apply to the restore results.
Possible values include:"private"
"public-read"
"public-read-write"
"authenticated-read"
"aws-exec-read"
"bucket-owner-read"
"bucket-owner-full-control"
AccessControlList
— (Array<map>
)A list of grants that control access to the staged results.
Grantee
— (map
)DisplayName
— (String
)Screen name of the grantee.
EmailAddress
— (String
)Email address of the grantee.
ID
— (String
)The canonical user ID of the grantee.
Type
— required — (String
)Type of grantee
Possible values include:"CanonicalUser"
"AmazonCustomerByEmail"
"Group"
URI
— (String
)URI of the grantee group.
Permission
— (String
)Specifies the permission given to the grantee.
Possible values include:"FULL_CONTROL"
"WRITE"
"WRITE_ACP"
"READ"
"READ_ACP"
Tagging
— (map
)The tag-set that is applied to the restore results.
TagSet
— required — (Array<map>
)Key
— required — (String
)Name of the tag.
Value
— required — (String
)Value of the tag.
UserMetadata
— (Array<map>
)A list of metadata to store with the restore results in S3.
Name
— (String
)Value
— (String
)
StorageClass
— (String
)The class of storage used to store the restore results.
Possible values include:"STANDARD"
"REDUCED_REDUNDANCY"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"GLACIER"
"DEEP_ARCHIVE"
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
RestoreOutputPath
— (String
)Indicates the path in the provided S3 output location where Select results will be restored to.
-
(AWS.Response)
—
Returns:
selectObjectContent(params = {}, callback) ⇒ AWS.Request
This operation filters the contents of an Amazon S3 object based on a simple Structured Query Language (SQL) statement. In the request, along with the SQL expression, you must also specify a data serialization format (JSON or CSV) of the object. Amazon S3 uses this to parse object data into records, and returns only records that match the specified SQL expression. You must also specify the data serialization format for the response.
Service Reference:
Examples:
Node.js EventStream Example
// In Node.js, events are streamed and can be read as they arrive.
s3.selectObjectContent({/** params **/}, function(err, data) {
if (err) {
// handle error
return console.error(err);
}
var eventStream = data.Payload;
eventStream.on('data', function(event) {
// Check the top-level field to determine which event this is.
if (event.Records) {
// handle Records event
} else if (event.Stats) {
// handle Stats event
} else if (event.Progress) {
// handle Progress event
} else if (event.Cont) {
// handle Cont event
} else if (event.End) {
// handle End event
}
});
eventStream.on('error', function(err) { /** Handle error events **/});
eventStream.on('end', function() { /** Finished reading all events **/});
});
Browser EventStream Example
// In browsers, events aren't processed until the response is fully buffered.
// Events will be accessible as an array.
s3.selectObjectContent({/** params **/}, function(err, data) {
if (err) {
// handle error
return console.error(err);
}
var events = data.Payload;
for (var event of events) {
// Check the top-level field to determine which event this is.
if (event.Records) {
// handle Records event
} else if (event.Stats) {
// handle Stats event
} else if (event.Progress) {
// handle Progress event
} else if (event.Cont) {
// handle Cont event
} else if (event.End) {
// handle End event
}
}
});
Async Iterator EventStream Example (Experimental)
// In Node.js v10.x, Readable streams have experimental support for async iteration.
// Instead of listening to the event stream's 'data' event, you can use a for...await loop.
async function example() {
try {
const result = await s3.selectObjectContent({/** params **/}).promise();
const events = result.Payload;
for await (const event of events) {
// Check the top-level field to determine which event this is.
if (event.Records) {
// handle Records event
} else if (event.Stats) {
// handle Stats event
} else if (event.Progress) {
// handle Progress event
} else if (event.Cont) {
// handle Cont event
} else if (event.End) {
// handle End event
}
}
} catch (err) {
// handle error
}
}
Calling the selectObjectContent operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Expression: 'STRING_VALUE', /* required */
ExpressionType: SQL, /* required */
InputSerialization: { /* required */
CSV: {
AllowQuotedRecordDelimiter: true || false,
Comments: 'STRING_VALUE',
FieldDelimiter: 'STRING_VALUE',
FileHeaderInfo: USE | IGNORE | NONE,
QuoteCharacter: 'STRING_VALUE',
QuoteEscapeCharacter: 'STRING_VALUE',
RecordDelimiter: 'STRING_VALUE'
},
CompressionType: NONE | GZIP | BZIP2,
JSON: {
Type: DOCUMENT | LINES
},
Parquet: {
}
},
Key: 'STRING_VALUE', /* required */
OutputSerialization: { /* required */
CSV: {
FieldDelimiter: 'STRING_VALUE',
QuoteCharacter: 'STRING_VALUE',
QuoteEscapeCharacter: 'STRING_VALUE',
QuoteFields: ALWAYS | ASNEEDED,
RecordDelimiter: 'STRING_VALUE'
},
JSON: {
RecordDelimiter: 'STRING_VALUE'
}
},
RequestProgress: {
Enabled: true || false
},
SSECustomerAlgorithm: 'STRING_VALUE',
SSECustomerKey: new Buffer('...') || 'STRING_VALUE' /* Strings will be Base-64 encoded on your behalf */,
SSECustomerKeyMD5: 'STRING_VALUE'
};
s3.selectObjectContent(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)The S3 bucket.
Key
— (String
)The object key.
SSECustomerAlgorithm
— (String
)The SSE Algorithm used to encrypt the object. For more information, see Server-Side Encryption (Using Customer-Provided Encryption Keys.
SSECustomerKey
— (Buffer, Typed Array, Blob, String
)The SSE Customer Key. For more information, see Server-Side Encryption (Using Customer-Provided Encryption Keys.
SSECustomerKeyMD5
— (String
)The SSE Customer Key MD5. For more information, see Server-Side Encryption (Using Customer-Provided Encryption Keys.
Expression
— (String
)The expression that is used to query the object.
ExpressionType
— (String
)The type of the provided expression (for example., SQL).
Possible values include:"SQL"
RequestProgress
— (map
)Specifies if periodic request progress information should be enabled.
Enabled
— (Boolean
)Specifies whether periodic QueryProgress frames should be sent. Valid values: TRUE, FALSE. Default value: FALSE.
InputSerialization
— (map
)Describes the format of the data in the object that is being queried.
CSV
— (map
)Describes the serialization of a CSV-encoded object.
FileHeaderInfo
— (String
)Describes the first line of input. Valid values: None, Ignore, Use.
Possible values include:"USE"
"IGNORE"
"NONE"
Comments
— (String
)The single character used to indicate a row should be ignored when present at the start of a row.
QuoteEscapeCharacter
— (String
)The single character used for escaping the quote character inside an already escaped value.
RecordDelimiter
— (String
)The value used to separate individual records.
FieldDelimiter
— (String
)The value used to separate individual fields in a record.
QuoteCharacter
— (String
)Value used for escaping where the field delimiter is part of the value.
AllowQuotedRecordDelimiter
— (Boolean
)Specifies that CSV field values may contain quoted record delimiters and such records should be allowed. Default value is FALSE. Setting this value to TRUE may lower performance.
CompressionType
— (String
)Specifies object's compression format. Valid values: NONE, GZIP, BZIP2. Default Value: NONE.
Possible values include:"NONE"
"GZIP"
"BZIP2"
JSON
— (map
)Specifies JSON as object's input serialization format.
Type
— (String
)The type of JSON. Valid values: Document, Lines.
Possible values include:"DOCUMENT"
"LINES"
Parquet
— (map
)Specifies Parquet as object's input serialization format.
OutputSerialization
— (map
)Describes the format of the data that you want Amazon S3 to return in response.
CSV
— (map
)Describes the serialization of CSV-encoded Select results.
QuoteFields
— (String
)Indicates whether or not all output fields should be quoted.
Possible values include:"ALWAYS"
"ASNEEDED"
QuoteEscapeCharacter
— (String
)Th single character used for escaping the quote character inside an already escaped value.
RecordDelimiter
— (String
)The value used to separate individual records.
FieldDelimiter
— (String
)The value used to separate individual fields in a record.
QuoteCharacter
— (String
)The value used for escaping where the field delimiter is part of the value.
JSON
— (map
)Specifies JSON as request's output serialization format.
RecordDelimiter
— (String
)The value used to separate individual records in the output.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:Payload
— (ReadableStream<Events> | Array<Events>
)Payload is an object-mode Readable stream in Node.js v0.10.x and higher. Attach a listener to the
data
event to receive events. Payload is an array of events in browsers. The possible events that may be returned are listed below. Note that the top-level field in each event matches the event name.Records
— (map
)The Records Event.
Payload
— (Buffer
)The byte array of partial, one or more result records.
Stats
— (map
)The Stats Event.
Details
— (map
)The Stats event details.
BytesScanned
— (Integer
)The total number of object bytes scanned.
BytesProcessed
— (Integer
)The total number of uncompressed object bytes processed.
BytesReturned
— (Integer
)The total number of bytes of records payload data returned.
Progress
— (map
)The Progress Event.
Details
— (map
)The Progress event details.
BytesScanned
— (Integer
)The current number of object bytes scanned.
BytesProcessed
— (Integer
)The current number of uncompressed object bytes processed.
BytesReturned
— (Integer
)The current number of bytes of records payload data returned.
Cont
— (map
)The Continuation Event.
End
— (map
)The End Event.
-
(AWS.Response)
—
Returns:
upload(params = {}, [options], [callback]) ⇒ AWS.S3.ManagedUpload
Uploads an arbitrarily sized buffer, blob, or stream, using intelligent
concurrent handling of parts if the payload is large enough. You can
configure the concurrent queue size by setting options
. Note that this
is the only operation for which the SDK can retry requests with stream
bodies.
Examples:
Uploading a stream object
var params = {Bucket: 'bucket', Key: 'key', Body: stream};
s3.upload(params, function(err, data) {
console.log(err, data);
});
Uploading a stream with concurrency of 1 and partSize of 10mb
var params = {Bucket: 'bucket', Key: 'key', Body: stream};
var options = {partSize: 10 * 1024 * 1024, queueSize: 1};
s3.upload(params, options, function(err, data) {
console.log(err, data);
});
Parameters:
-
params
(Object)
(defaults to: {})
—
ACL
— (String
)The canned ACL to apply to the object.
Possible values include:"private"
"public-read"
"public-read-write"
"authenticated-read"
"aws-exec-read"
"bucket-owner-read"
"bucket-owner-full-control"
Body
— (Buffer, Typed Array, Blob, String, ReadableStream
)Object data.
Bucket
— (String
)Name of the bucket to which the PUT operation was initiated.
CacheControl
— (String
)Specifies caching behavior along the request/reply chain.
ContentDisposition
— (String
)Specifies presentational information for the object.
ContentEncoding
— (String
)Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
ContentLanguage
— (String
)The language the content is in.
ContentLength
— (Integer
)Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically.
ContentMD5
— (String
)The base64-encoded 128-bit MD5 digest of the part data. This parameter is auto-populated when using the command from the CLI
ContentType
— (String
)A standard MIME type describing the format of the object data.
Expires
— (Date
)The date and time at which the object is no longer cacheable.
GrantFullControl
— (String
)Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
GrantRead
— (String
)Allows grantee to read the object data and its metadata.
GrantReadACP
— (String
)Allows grantee to read the object ACL.
GrantWriteACP
— (String
)Allows grantee to write the ACL for the applicable object.
Key
— (String
)Object key for which the PUT operation was initiated.
Metadata
— (map<String>
)A map of metadata to store with the object in S3.
ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
StorageClass
— (String
)The type of storage to use for the object. Defaults to 'STANDARD'.
Possible values include:"STANDARD"
"REDUCED_REDUNDANCY"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"GLACIER"
"DEEP_ARCHIVE"
WebsiteRedirectLocation
— (String
)If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
SSECustomerAlgorithm
— (String
)Specifies the algorithm to use to when encrypting the object (e.g., AES256).
SSECustomerKey
— (Buffer, Typed Array, Blob, String
)Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
SSECustomerKeyMD5
— (String
)Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
SSEKMSKeyId
— (String
)Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Tagging
— (String
)The tag-set for the object. The tag-set must be encoded as URL Query parameters. (For example, "Key1=Value1")
ObjectLockMode
— (String
)The Object Lock mode that you want to apply to this object.
Possible values include:"GOVERNANCE"
"COMPLIANCE"
ObjectLockRetainUntilDate
— (Date
)The date and time when you want this object's Object Lock to expire.
ObjectLockLegalHoldStatus
— (String
)The Legal Hold status that you want to apply to the specified object.
Possible values include:"ON"
"OFF"
Returns:
-
(AWS.S3.ManagedUpload)
—
the managed upload object that can call
send()
or track progress.
Callback (callback):
-
function(err, data) { ... }
Parameters:
-
err
(Error)
—
an error or null if no error occurred.
-
data
(map)
—
The response data from the successful upload:
-
data.Location
(String)
—
the URL of the uploaded object
-
data.ETag
(String)
—
the ETag of the uploaded object
-
data.Bucket
(String)
—
the bucket to which the object was uploaded
-
data.Key
(String)
—
the key to which the object was uploaded
-
err
(Error)
—
See Also:
uploadPart(params = {}, callback) ⇒ AWS.Request
Uploads a part in a multipart upload.
Note: After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, Amazon S3 frees up the parts storage and stops charging you for the parts storage.
Service Reference:
Examples:
To upload a part
/* The following example uploads part 1 of a multipart upload. The example specifies a file name for the part data. The Upload ID is same that is returned by the initiate multipart upload. */
var params = {
Body: <Binary String>,
Bucket: "examplebucket",
Key: "examplelargeobject",
PartNumber: 1,
UploadId: "xadcOB_7YPBOJuoFiQ9cz4P3Pe6FIZwO4f7wN93uHsNBEw97pl5eNwzExg0LAT2dUN91cOmrEQHDsP3WA60CEg--"
};
s3.uploadPart(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
ETag: "\"d8c2eafd90c266e19ab9dcacc479f8af\""
}
*/
});
Calling the uploadPart operation
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
PartNumber: 'NUMBER_VALUE', /* required */
UploadId: 'STRING_VALUE', /* required */
Body: new Buffer('...') || 'STRING_VALUE' || streamObject,
ContentLength: 'NUMBER_VALUE',
ContentMD5: 'STRING_VALUE',
RequestPayer: requester,
SSECustomerAlgorithm: 'STRING_VALUE',
SSECustomerKey: new Buffer('...') || 'STRING_VALUE' /* Strings will be Base-64 encoded on your behalf */,
SSECustomerKeyMD5: 'STRING_VALUE'
};
s3.uploadPart(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Body
— (Buffer, Typed Array, Blob, String, ReadableStream
)Object data.
Bucket
— (String
)Name of the bucket to which the multipart upload was initiated.
ContentLength
— (Integer
)Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically.
ContentMD5
— (String
)The base64-encoded 128-bit MD5 digest of the part data.
Key
— (String
)Object key for which the multipart upload was initiated.
PartNumber
— (Integer
)Part number of part being uploaded. This is a positive integer between 1 and 10,000.
UploadId
— (String
)Upload ID identifying the multipart upload whose part is being uploaded.
SSECustomerAlgorithm
— (String
)Specifies the algorithm to use to when encrypting the object (e.g., AES256).
SSECustomerKey
— (Buffer, Typed Array, Blob, String
)Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header. This must be the same encryption key specified in the initiate multipart upload request.
SSECustomerKeyMD5
— (String
)Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
ETag
— (String
)Entity tag for the uploaded object.
SSECustomerAlgorithm
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
SSECustomerKeyMD5
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
SSEKMSKeyId
— (String
)If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
uploadPartCopy(params = {}, callback) ⇒ AWS.Request
Uploads a part by copying data from an existing object as data source.
Service Reference:
Examples:
To upload a part by copying byte range from an existing object as data source
/* The following example uploads a part of a multipart upload by copying a specified byte range from an existing object as data source. */
var params = {
Bucket: "examplebucket",
CopySource: "/bucketname/sourceobjectkey",
CopySourceRange: "bytes=1-100000",
Key: "examplelargeobject",
PartNumber: 2,
UploadId: "exampleuoh_10OhKhT7YukE9bjzTPRiuaCotmZM_pFngJFir9OZNrSr5cWa3cq3LZSUsfjI4FI7PkP91We7Nrw--"
};
s3.uploadPartCopy(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
CopyPartResult: {
ETag: "\"65d16d19e65a7508a51f043180edcc36\"",
LastModified: <Date Representation>
}
}
*/
});
To upload a part by copying data from an existing object as data source
/* The following example uploads a part of a multipart upload by copying data from an existing object as data source. */
var params = {
Bucket: "examplebucket",
CopySource: "/bucketname/sourceobjectkey",
Key: "examplelargeobject",
PartNumber: 1,
UploadId: "exampleuoh_10OhKhT7YukE9bjzTPRiuaCotmZM_pFngJFir9OZNrSr5cWa3cq3LZSUsfjI4FI7PkP91We7Nrw--"
};
s3.uploadPartCopy(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
/*
data = {
CopyPartResult: {
ETag: "\"b0c6f0e7e054ab8fa2536a2677f8734d\"",
LastModified: <Date Representation>
}
}
*/
});
Calling the uploadPartCopy operation
var params = {
Bucket: 'STRING_VALUE', /* required */
CopySource: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
PartNumber: 'NUMBER_VALUE', /* required */
UploadId: 'STRING_VALUE', /* required */
CopySourceIfMatch: 'STRING_VALUE',
CopySourceIfModifiedSince: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
CopySourceIfNoneMatch: 'STRING_VALUE',
CopySourceIfUnmodifiedSince: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
CopySourceRange: 'STRING_VALUE',
CopySourceSSECustomerAlgorithm: 'STRING_VALUE',
CopySourceSSECustomerKey: new Buffer('...') || 'STRING_VALUE' /* Strings will be Base-64 encoded on your behalf */,
CopySourceSSECustomerKeyMD5: 'STRING_VALUE',
RequestPayer: requester,
SSECustomerAlgorithm: 'STRING_VALUE',
SSECustomerKey: new Buffer('...') || 'STRING_VALUE' /* Strings will be Base-64 encoded on your behalf */,
SSECustomerKeyMD5: 'STRING_VALUE'
};
s3.uploadPartCopy(params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
(defaults to: {})
—
Bucket
— (String
)CopySource
— (String
)The name of the source bucket and key name of the source object, separated by a slash (/). Must be URL-encoded.
CopySourceIfMatch
— (String
)Copies the object if its entity tag (ETag) matches the specified tag.
CopySourceIfModifiedSince
— (Date
)Copies the object if it has been modified since the specified time.
CopySourceIfNoneMatch
— (String
)Copies the object if its entity tag (ETag) is different than the specified ETag.
CopySourceIfUnmodifiedSince
— (Date
)Copies the object if it hasn't been modified since the specified time.
CopySourceRange
— (String
)The range of bytes to copy from the source object. The range value must use the form bytes=first-last, where the first and last are the zero-based byte offsets to copy. For example, bytes=0-9 indicates that you want to copy the first ten bytes of the source. You can copy a range only if the source object is greater than 5 MB.
Key
— (String
)PartNumber
— (Integer
)Part number of part being copied. This is a positive integer between 1 and 10,000.
UploadId
— (String
)Upload ID identifying the multipart upload whose part is being copied.
SSECustomerAlgorithm
— (String
)Specifies the algorithm to use to when encrypting the object (e.g., AES256).
SSECustomerKey
— (Buffer, Typed Array, Blob, String
)Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header. This must be the same encryption key specified in the initiate multipart upload request.
SSECustomerKeyMD5
— (String
)Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
CopySourceSSECustomerAlgorithm
— (String
)Specifies the algorithm to use when decrypting the source object (e.g., AES256).
CopySourceSSECustomerKey
— (Buffer, Typed Array, Blob, String
)Specifies the customer-provided encryption key for Amazon S3 to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created.
CopySourceSSECustomerKeyMD5
— (String
)Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:CopySourceVersionId
— (String
)The version of the source object that was copied, if you have enabled versioning on the source bucket.
CopyPartResult
— (map
)ETag
— (String
)Entity tag of the object.
LastModified
— (Date
)Date and time at which the object was uploaded.
ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
SSECustomerAlgorithm
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
SSECustomerKeyMD5
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
SSEKMSKeyId
— (String
)If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
-
(AWS.Response)
—
Returns:
waitFor(state, params = {}, callback) ⇒ AWS.Request
Waits for a given S3 resource. The final callback or 'complete' event will be fired only when the resource is either in its final state or the waiter has timed out and stopped polling for the final state.
Examples:
Waiting for the bucketExists state
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.waitFor('bucketExists', params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
state
(String)
—
the resource state to wait for. Available states for this service are listed in "Waiter Resource States" below.
-
params
(map)
(defaults to: {})
—
a list of parameters for the given state. See each waiter resource state for required parameters.
Callback (callback):
-
function(err, data) { ... }
Callback containing error and data information. See the respective resource state for the expected error or data information.
If the waiter times out its requests, it will return a
ResourceNotReady
error.
Returns:
Waiter Resource States:
Waiter Resource Details
s3.waitFor('bucketExists', params = {}, [callback]) ⇒ AWS.Request
Waits for the bucketExists
state by periodically calling the underlying
S3.headBucket() operation every 5 seconds
(at most 20 times).
Examples:
Waiting for the bucketExists state
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.waitFor('bucketExists', params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
See Also:
s3.waitFor('bucketNotExists', params = {}, [callback]) ⇒ AWS.Request
Waits for the bucketNotExists
state by periodically calling the underlying
S3.headBucket() operation every 5 seconds
(at most 20 times).
Examples:
Waiting for the bucketNotExists state
var params = {
Bucket: 'STRING_VALUE' /* required */
};
s3.waitFor('bucketNotExists', params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
—
Bucket
— (String
)
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs.
-
(AWS.Response)
—
Returns:
See Also:
s3.waitFor('objectExists', params = {}, [callback]) ⇒ AWS.Request
Waits for the objectExists
state by periodically calling the underlying
S3.headObject() operation every 5 seconds
(at most 20 times).
Examples:
Waiting for the objectExists state
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
};
s3.waitFor('objectExists', params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
—
Bucket
— (String
)IfMatch
— (String
)Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
IfModifiedSince
— (Date
)Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
IfNoneMatch
— (String
)Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
IfUnmodifiedSince
— (Date
)Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
Key
— (String
)Range
— (String
)Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
VersionId
— (String
)VersionId used to reference a specific version of the object.
SSECustomerAlgorithm
— (String
)Specifies the algorithm to use to when encrypting the object (e.g., AES256).
SSECustomerKey
— (Buffer, Typed Array, Blob, String
)Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
SSECustomerKeyMD5
— (String
)Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
PartNumber
— (Integer
)Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a 'ranged' HEAD request for the part specified. Useful querying about the size of the part and the number of parts in this object.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:DeleteMarker
— (Boolean
)Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
AcceptRanges
— (String
)Expiration
— (String
)If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
Restore
— (String
)Provides information about object restoration operation and expiration time of the restored object copy.
LastModified
— (Date
)Last modified date of the object
ContentLength
— (Integer
)Size of the body in bytes.
ETag
— (String
)An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
MissingMeta
— (Integer
)This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
VersionId
— (String
)Version of the object.
CacheControl
— (String
)Specifies caching behavior along the request/reply chain.
ContentDisposition
— (String
)Specifies presentational information for the object.
ContentEncoding
— (String
)Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
ContentLanguage
— (String
)The language the content is in.
ContentType
— (String
)A standard MIME type describing the format of the object data.
Expires
— (Date
)The date and time at which the object is no longer cacheable.
WebsiteRedirectLocation
— (String
)If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
Metadata
— (map<String>
)A map of metadata to store with the object in S3.
SSECustomerAlgorithm
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
SSECustomerKeyMD5
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
SSEKMSKeyId
— (String
)If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
StorageClass
— (String
)Possible values include:
"STANDARD"
"REDUCED_REDUNDANCY"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"GLACIER"
"DEEP_ARCHIVE"
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
ReplicationStatus
— (String
)Possible values include:
"COMPLETE"
"PENDING"
"FAILED"
"REPLICA"
PartsCount
— (Integer
)The count of parts this object has.
ObjectLockMode
— (String
)The Object Lock mode currently in place for this object.
Possible values include:"GOVERNANCE"
"COMPLIANCE"
ObjectLockRetainUntilDate
— (Date
)The date and time when this object's Object Lock will expire.
ObjectLockLegalHoldStatus
— (String
)The Legal Hold status for the specified object.
Possible values include:"ON"
"OFF"
-
(AWS.Response)
—
Returns:
See Also:
s3.waitFor('objectNotExists', params = {}, [callback]) ⇒ AWS.Request
Waits for the objectNotExists
state by periodically calling the underlying
S3.headObject() operation every 5 seconds
(at most 20 times).
Examples:
Waiting for the objectNotExists state
var params = {
Bucket: 'STRING_VALUE', /* required */
Key: 'STRING_VALUE', /* required */
};
s3.waitFor('objectNotExists', params, function(err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response
});
Parameters:
-
params
(Object)
—
Bucket
— (String
)IfMatch
— (String
)Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
IfModifiedSince
— (Date
)Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
IfNoneMatch
— (String
)Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
IfUnmodifiedSince
— (Date
)Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
Key
— (String
)Range
— (String
)Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
VersionId
— (String
)VersionId used to reference a specific version of the object.
SSECustomerAlgorithm
— (String
)Specifies the algorithm to use to when encrypting the object (e.g., AES256).
SSECustomerKey
— (Buffer, Typed Array, Blob, String
)Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
SSECustomerKeyMD5
— (String
)Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
RequestPayer
— (String
)Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Possible values include:"requester"
PartNumber
— (Integer
)Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a 'ranged' HEAD request for the part specified. Useful querying about the size of the part and the number of parts in this object.
Callback (callback):
-
function(err, data) { ... }
Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.
Context (this):
-
(AWS.Response)
—
the response object containing error, data properties, and the original request object.
Parameters:
-
err
(Error)
—
the error object returned from the request. Set to
null
if the request is successful. -
data
(Object)
—
the de-serialized data returned from the request. Set to
null
if a request error occurs. Thedata
object has the following properties:DeleteMarker
— (Boolean
)Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
AcceptRanges
— (String
)Expiration
— (String
)If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
Restore
— (String
)Provides information about object restoration operation and expiration time of the restored object copy.
LastModified
— (Date
)Last modified date of the object
ContentLength
— (Integer
)Size of the body in bytes.
ETag
— (String
)An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
MissingMeta
— (Integer
)This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
VersionId
— (String
)Version of the object.
CacheControl
— (String
)Specifies caching behavior along the request/reply chain.
ContentDisposition
— (String
)Specifies presentational information for the object.
ContentEncoding
— (String
)Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
ContentLanguage
— (String
)The language the content is in.
ContentType
— (String
)A standard MIME type describing the format of the object data.
Expires
— (Date
)The date and time at which the object is no longer cacheable.
WebsiteRedirectLocation
— (String
)If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
ServerSideEncryption
— (String
)The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
Possible values include:"AES256"
"aws:kms"
Metadata
— (map<String>
)A map of metadata to store with the object in S3.
SSECustomerAlgorithm
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
SSECustomerKeyMD5
— (String
)If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
SSEKMSKeyId
— (String
)If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
StorageClass
— (String
)Possible values include:
"STANDARD"
"REDUCED_REDUNDANCY"
"STANDARD_IA"
"ONEZONE_IA"
"INTELLIGENT_TIERING"
"GLACIER"
"DEEP_ARCHIVE"
RequestCharged
— (String
)If present, indicates that the requester was successfully charged for the request.
Possible values include:"requester"
ReplicationStatus
— (String
)Possible values include:
"COMPLETE"
"PENDING"
"FAILED"
"REPLICA"
PartsCount
— (Integer
)The count of parts this object has.
ObjectLockMode
— (String
)The Object Lock mode currently in place for this object.
Possible values include:"GOVERNANCE"
"COMPLIANCE"
ObjectLockRetainUntilDate
— (Date
)The date and time when this object's Object Lock will expire.
ObjectLockLegalHoldStatus
— (String
)The Legal Hold status for the specified object.
Possible values include:"ON"
"OFF"
-
(AWS.Response)
—
Returns:
See Also: