Class: AWS.S3

Inherits:
AWS.Service show all
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.

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 collapse

Property Summary collapse

Properties inherited from AWS.Service

apiVersions

Method Summary collapse

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.
  • 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 to true.

  • 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.
    • 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.
    • 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.

Property Details

endpointAWS.Endpoint (readwrite)

Returns an Endpoint object representing the endpoint URL for service requests.

Returns:

  • (AWS.Endpoint)

    an Endpoint object representing the endpoint URL for service requests.

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.

Examples:

Calling the abortMultipartUpload operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Key: 'STRING_VALUE', /* required */
  UploadId: 'STRING_VALUE' /* required */
};
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)

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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

addLegalHold(params = {}, callback) ⇒ AWS.Request

Add a legal hold on an object. The legal hold identifiers are stored in the object metadata along with the timestamp of when they are POSTed to the object. The presence of any legal hold identifiers prevents the modification or deletion of the object data, even if the retention period has expired. The presence of a retention period header is required, otherwise a 400 error is returned.

Examples:

Calling the addLegalHold operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Key: 'STRING_VALUE', /* required */
  RetentionLegalHoldId: 'STRING_VALUE' /* required */
};
s3.addLegalHold(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)
    • RetentionLegalHoldId — (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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

completeMultipartUpload(params = {}, callback) ⇒ AWS.Request

Completes a multipart upload by assembling previously uploaded parts.

Examples:

Calling the completeMultipartUpload operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Key: 'STRING_VALUE', /* required */
  UploadId: 'STRING_VALUE', /* required */
  MultipartUpload: {
    Parts: [
      {
        ETag: 'STRING_VALUE',
        PartNumber: 0
      },
      /* more items */
    ]
  },
  RetentionExpirationDate: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
  RetentionLegalHoldId: 'STRING_VALUE',
  RetentionPeriod: 0
};
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.
    • RetentionExpirationDate — (Date) Date on which it will be legal to delete or modify the object. You can only specify this or the Retention-Period header. If both are specified a 400 error will be returned. If neither is specified the bucket's DefaultRetention period will be used. This header should be used to calculate a retention period in seconds and then stored in that manner.
    • RetentionLegalHoldId — (String) A single legal hold to apply to the object. A legal hold is a character long string of max length 64. The object cannot be overwritten or deleted until all legal holds associated with the object are removed.
    • RetentionPeriod — (Integer) Retention period to store on the object in seconds. If this field and Retention-Expiration-Date are specified a 400 error is returned. If neither is specified the bucket's DefaultRetention period will be used. 0 is a legal value assuming the bucket's minimum retention period is also 0.
    • UploadId — (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. The data 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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

copyObject(params = {}, callback) ⇒ AWS.Request

Creates a copy of an object that is already stored in Amazon S3.

Examples:

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: Buffer.from('...') || '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: {
    someKey: 'STRING_VALUE',
    /* anotherKey: ... */
  },
  MetadataDirective: 'COPY | REPLACE',
  RetentionDirective: 'COPY | REPLACE',
  RetentionExpirationDate: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
  RetentionLegalHoldId: 'STRING_VALUE',
  RetentionPeriod: 0,
  SSECustomerAlgorithm: 'STRING_VALUE',
  SSECustomerKey: Buffer.from('...') || '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',
  VersionId: '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"
    • RetentionDirective — (String) This header controls how the Protection state of the source object is copied to the destination object.If copied, the retention period and all legal holds are copied onto the new object. The legal hold date's is set to the date of the copy. Possible values include:
      • "COPY"
      • "REPLACE"
    • RetentionExpirationDate — (Date) Date on which it will be legal to delete or modify the object. You can only specify this or the Retention-Period header. If both are specified a 400 error will be returned. If neither is specified the bucket's DefaultRetention period will be used. This header should be used to calculate a retention period in seconds and then stored in that manner.
    • RetentionLegalHoldId — (String) A single legal hold to apply to the object. A legal hold is a Y character long string. The object cannot be overwritten or deleted until all legal holds associated with the object are removed.
    • RetentionPeriod — (Integer) Retention period to store on the object in seconds. If this field and Retention-Expiration-Date are specified a 400 error is returned. If neither is specified the bucket's DefaultRetention period will be used. 0 is a legal value assuming the bucket's minimum retention period is also 0.
    • 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"
    • 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 IBM COS to use in encrypting data. This value is used to store the object and then it is discarded; IBM 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. IBM COS uses this header for a message integrity check to ensure the encryption key was transmitted without error.
    • SSEKMSKeyId — (String) Applies only to Amazon S3. 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 IBM COS 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. IBM COS uses this header for a message integrity check to ensure the encryption key was transmitted without error.

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. The data 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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

createBucket(params, callback) ⇒ AWS.Request

Creates a new bucket.

Examples:

Calling the createBucket operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  ACL: 'private | public-read | public-read-write | authenticated-read',
  CreateBucketConfiguration: {
    LocationConstraint: 'us-standard | us-vault | us-cold | us-flex | us-east-standard | us-east-vault | us-east-cold | us-east-flex | us-south-standard | us-south-vault | us-south-cold | us-south-flex | eu-standard | eu-vault | eu-cold | eu-flex | eu-gb-standard | eu-gb-vault | eu-gb-cold | eu-gb-flex | eu-de-standard | eu-de-vault | eu-de-cold | eu-de-flex | ap-standard | ap-vault | ap-cold | ap-flex | ams03-standard | ams03-vault | ams03-cold | ams03-flex | che01-standard | che01-vault | che01-cold | che01-flex | mel01-standard | mel01-vault | mel01-cold | mel01-flex | osl01-standard | osl01-vault | osl01-cold | osl01-flex | sao01-standard | sao01-vault | sao01-cold | sao01-flex | tor01-standard | tor01-vault | tor01-cold | tor01-flex'
  },
  GrantFullControl: 'STRING_VALUE',
  GrantRead: 'STRING_VALUE',
  GrantReadACP: 'STRING_VALUE',
  GrantWrite: 'STRING_VALUE',
  GrantWriteACP: 'STRING_VALUE',
  IBMSSEKPCustomerRootKeyCrn: 'STRING_VALUE',
  IBMSSEKPEncryptionAlgorithm: 'STRING_VALUE',
  IBMServiceInstanceId: 'STRING_VALUE'
};
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 will be created in US Standard. Possible values include:
        • "us-standard"
        • "us-vault"
        • "us-cold"
        • "us-flex"
        • "us-east-standard"
        • "us-east-vault"
        • "us-east-cold"
        • "us-east-flex"
        • "us-south-standard"
        • "us-south-vault"
        • "us-south-cold"
        • "us-south-flex"
        • "eu-standard"
        • "eu-vault"
        • "eu-cold"
        • "eu-flex"
        • "eu-gb-standard"
        • "eu-gb-vault"
        • "eu-gb-cold"
        • "eu-gb-flex"
        • "eu-de-standard"
        • "eu-de-vault"
        • "eu-de-cold"
        • "eu-de-flex"
        • "ap-standard"
        • "ap-vault"
        • "ap-cold"
        • "ap-flex"
        • "ams03-standard"
        • "ams03-vault"
        • "ams03-cold"
        • "ams03-flex"
        • "che01-standard"
        • "che01-vault"
        • "che01-cold"
        • "che01-flex"
        • "mel01-standard"
        • "mel01-vault"
        • "mel01-cold"
        • "mel01-flex"
        • "osl01-standard"
        • "osl01-vault"
        • "osl01-cold"
        • "osl01-flex"
        • "sao01-standard"
        • "sao01-vault"
        • "sao01-cold"
        • "sao01-flex"
        • "tor01-standard"
        • "tor01-vault"
        • "tor01-cold"
        • "tor01-flex"
    • 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.
    • IBMServiceInstanceId — (String) The storage account who will be the owner of the bucket.
    • IBMSSEKPEncryptionAlgorithm — (String)
    • IBMSSEKPCustomerRootKeyCrn — (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. The data object has the following properties:

      • Location — (String)

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

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, IBM COS frees up the parts storage and stops charging you for the parts storage.

Examples:

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: {
    someKey: 'STRING_VALUE',
    /* anotherKey: ... */
  },
  SSECustomerAlgorithm: 'STRING_VALUE',
  SSECustomerKey: Buffer.from('...') || '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'
};
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"
    • 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; IBM 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. IBM COS 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

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. The data 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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

createPresignedPost(params, callback) ⇒ void

Note:

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.

Note:

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 for a given operation name.

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)

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.

Examples:

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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

deleteBucketCors(params = {}, callback) ⇒ AWS.Request

Deletes the cors configuration information set for the bucket.

Examples:

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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

deleteBucketLifecycle(params = {}, callback) ⇒ AWS.Request

Deletes the lifecycle configuration from the bucket.

Examples:

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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

deleteBucketTagging(params = {}, callback) ⇒ AWS.Request

Deletes the tags from the bucket.

Examples:

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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

deleteLegalHold(params = {}, callback) ⇒ AWS.Request

Remove Legal hold on an object. The legal hold identifiers are stored in the object metadata along with the timestamp of when they are POSTed to the object. The presence of any legal hold identifiers prevents the modification or deletion of the object data, even if the retention period has expired. The presence of a retention period header is required, otherwise a 400 error is returned.

Examples:

Calling the deleteLegalHold operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Key: 'STRING_VALUE', /* required */
  RetentionLegalHoldId: 'STRING_VALUE' /* required */
};
s3.deleteLegalHold(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)
    • RetentionLegalHoldId — (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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

deleteObject(params = {}, callback) ⇒ AWS.Request

If object versioning is not enabled, deletes an object. If versioning is enabled, 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, IBM COS does not remove any objects.

Examples:

Calling the deleteObject operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Key: 'STRING_VALUE', /* required */
  MFA: 'STRING_VALUE',
  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.

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. The data object has the following properties:

      • DeleteMarker — (Boolean) If versioning is enabled, specifies whether the versioned object that was permanently deleted was (true) or was not (false) a delete marker.
      • VersionId — (String) If versioning is enabled, returns the version ID of the delete marker created as a result of the DELETE operation.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

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.

Examples:

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
  },
  MFA: 'STRING_VALUE'
};
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)
      • Objectsrequired — (Array<map>)
        • Keyrequired — (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.

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. The data object has the following properties:

      • Deleted — (Array<map>)
        • Key — (String)
        • VersionId — (String)
        • DeleteMarker — (Boolean)
        • DeleteMarkerVersionId — (String)
      • Errors — (Array<map>)
        • Key — (String)
        • VersionId — (String)
        • Code — (String)
        • Message — (String)

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

extendObjectRetention(params = {}, callback) ⇒ AWS.Request

This implementation of the POST operation uses the extendRetention sub-resource to extend the retention period of a protected object in a protected vault.

Examples:

Calling the extendObjectRetention operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Key: 'STRING_VALUE', /* required */
  AdditionalRetentionPeriod: 0,
  ExtendRetentionFromCurrentTime: 0,
  NewRetentionExpirationDate: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
  NewRetentionPeriod: 0
};
s3.extendObjectRetention(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)
    • AdditionalRetentionPeriod — (Integer)
    • ExtendRetentionFromCurrentTime — (Integer) Retention Period in seconds for the object. The Retention will be enforced from the current time until current time + the value in this header. This header will only be supported for objects that are currently stored with an indefinite retention period (-1). This value has to be within the ranges defined for the bucket.
    • NewRetentionExpirationDate — (Date)
    • NewRetentionPeriod — (Integer) Retention period, in seconds, to use for the object in place of the existing retention period stored for the object. If this value is less than the existing value stored for the object, a 400 error will be returned. If this field and Additional-Retention-Period and/or New-Retention-Expiration-Date are specified, a 400 error will be returned. If none of the Request Headers are specified, a 400 error will be returned.

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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

getBucketAcl(params = {}, callback) ⇒ AWS.Request

Gets the access control policy for the bucket.

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. The data 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.
          • Typerequired — (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"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

getBucketCors(params = {}, callback) ⇒ AWS.Request

Returns the cors configuration for the bucket.

Examples:

Calling the getBucketCors operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  MirrorDestination: 'STRING_VALUE'
};
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)
    • MirrorDestination — (String) Mirror source for object reads.

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. The data object has the following properties:

      • CORSRules — (Array<map>)
        • AllowedHeaders — (Array<String>) Specifies which headers are allowed in a pre-flight OPTIONS request.
        • AllowedMethodsrequired — (Array<String>) Identifies HTTP methods that the domain/origin specified in the rule is allowed to execute.
        • AllowedOriginsrequired — (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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

getBucketLifecycle(params = {}, callback) ⇒ AWS.Request

No longer used, see the GetBucketLifecycleConfiguration operation.

Examples:

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. The data 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.
        • Statusrequired — (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.
          • TemporaryCopyStorageClass — (String) This header is only included if an object is in the RestoreInProgress or Restored states. This header will indicate the storage class to which the restored copy of the data will be billed. Possible values include:
            • "GLACIER"
            • "STANDARD"
          • StorageClass — (String) The class of storage used to store the object. Possible values include:
            • "GLACIER"
            • "STANDARD"
        • 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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

getBucketLifecycleConfiguration(params = {}, callback) ⇒ AWS.Request

Returns the lifecycle configuration information set on the bucket.

Examples:

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. The data object has the following properties:

      • Rules — (Array<map>) Currently only one Rule allowed.
        • 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.
        • IDrequired — (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 deprecated; use Filter instead.
        • Filterrequired — (map) The Filter is used to identify objects that a Lifecycle Rule applies to. Currently not supported.
          • Prefix — (String) Empty prefix allowed only.
        • Statusrequired — (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>) Currently only one Transition allowed, also Date and Days fields are mutually exclusive.
          • 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.
          • TemporaryCopyStorageClass — (String) This header is only included if an object is in the RestoreInProgress or Restored states. This header will indicate the storage class to which the restored copy of the data will be billed. Possible values include:
            • "GLACIER"
            • "STANDARD"
          • StorageClass — (String) The class of storage used to store the object. Possible values include:
            • "GLACIER"
            • "STANDARD"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

getBucketLocation(params = {}, callback) ⇒ AWS.Request

Returns the region the bucket resides in.

Examples:

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. The data object has the following properties:

      • LocationConstraint — (String) Possible values include:
        • "us-standard"
        • "us-vault"
        • "us-cold"
        • "us-flex"
        • "us-east-standard"
        • "us-east-vault"
        • "us-east-cold"
        • "us-east-flex"
        • "us-south-standard"
        • "us-south-vault"
        • "us-south-cold"
        • "us-south-flex"
        • "eu-standard"
        • "eu-vault"
        • "eu-cold"
        • "eu-flex"
        • "eu-gb-standard"
        • "eu-gb-vault"
        • "eu-gb-cold"
        • "eu-gb-flex"
        • "eu-de-standard"
        • "eu-de-vault"
        • "eu-de-cold"
        • "eu-de-flex"
        • "ap-standard"
        • "ap-vault"
        • "ap-cold"
        • "ap-flex"
        • "ams03-standard"
        • "ams03-vault"
        • "ams03-cold"
        • "ams03-flex"
        • "che01-standard"
        • "che01-vault"
        • "che01-cold"
        • "che01-flex"
        • "mel01-standard"
        • "mel01-vault"
        • "mel01-cold"
        • "mel01-flex"
        • "osl01-standard"
        • "osl01-vault"
        • "osl01-cold"
        • "osl01-flex"
        • "sao01-standard"
        • "sao01-vault"
        • "sao01-cold"
        • "sao01-flex"
        • "tor01-standard"
        • "tor01-vault"
        • "tor01-cold"
        • "tor01-flex"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

getBucketProtectionConfiguration(params = {}, callback) ⇒ AWS.Request

Returns the protection configuration of a bucket.

Examples:

Calling the getBucketProtectionConfiguration operation

var params = {
  Bucket: 'STRING_VALUE' /* required */
};
s3.getBucketProtectionConfiguration(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. The data object has the following properties:

      • Status — (String) Retention status of a bucket. Possible values include:
        • "Retention"
      • MinimumRetention — (map) Minimum retention period for an object, if a PUT of an object specifies a shorter retention period the PUT object will fail.
        • Daysrequired — (Integer)
      • DefaultRetention — (map) Default retention period for an object, if a PUT of an object does not specify a retention period this value will be converted to seconds and used.
        • Daysrequired — (Integer)
      • MaximumRetention — (map) Maximum retention period for an object, if a PUT of an object specifies a longer retention period the PUT object will fail.
        • Daysrequired — (Integer)
      • EnablePermanentRetention — (Boolean) Enable permanent retention for an object.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

getBucketTagging(params = {}, callback) ⇒ AWS.Request

Returns the tag set associated with the bucket.

Examples:

Calling the getBucketTagging operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  MirrorDestination: 'STRING_VALUE'
};
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)

    • MirrorDestination — (String) Mirror source for object reads.

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. The data object has the following properties:

      • TagSet — (Array<map>)

        • Keyrequired — (String) Name of the tag.
        • Valuerequired — (String) Value of the tag.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

getBucketVersioning(params = {}, callback) ⇒ AWS.Request

Returns the versioning state of a bucket.

Examples:

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. The data 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"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

getObject(params = {}, callback) ⇒ AWS.Request

Retrieves objects from IBM COS.

Examples:

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,
  MirrorDestination: 'STRING_VALUE',
  PartNumber: 0,
  Range: 'STRING_VALUE',
  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: Buffer.from('...') || '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)
    • MirrorDestination — (String) Mirror source for object reads.
    • 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; IBM 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. IBM COS uses this header for a message integrity check to ensure the encryption key was transmitted without error.
    • 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. The data object has the following properties:

      • Body — (Buffer, Typed Array, Blob, String, 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
      • 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.
      • 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.
      • RetentionExpirationDate — (Date) Date on which it will be legal to delete or modify the object. You can only specify this or the Retention-Period header. If both are specified a 400 error will be returned. If neither is specified the bucket's DefaultRetention period will be used. This header should be used to calculate a retention period in seconds and then stored in that manner.
      • RetentionLegalHoldCount — (Integer) Returns the count of legal holds on the object. If there are no legal holds, the header is not returned
      • RetentionPeriod — (Integer) Retention period to store on the object in seconds. If this field and Retention-Expiration-Date are specified a 400 error is returned. If neither is specified the bucket's DefaultRetention period will be used. 0 is a legal value assuming the bucket's minimum retention period is also 0.
      • RetentionPeriodSource — (String) The source of the retention period stored for the object Possible values include:
        • "Bucket"
        • "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.
      • StorageClass — (String) Possible values include:
        • "STANDARD"
        • "REDUCED_REDUNDANCY"
        • "STANDARD_IA"
      • PartsCount — (Integer) The count of parts this object has.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

getObjectAcl(params = {}, callback) ⇒ AWS.Request

Returns the access control list (ACL) of an object.

Examples:

Calling the getObjectAcl operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Key: 'STRING_VALUE', /* required */
  MirrorDestination: 'STRING_VALUE',
  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)
    • MirrorDestination — (String) Mirror source for object reads.
    • 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. The data 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.
          • Typerequired — (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"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

getSignedUrl(operation, params, callback) ⇒ String?

Note:

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.

Note:

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

Note:

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.

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.

getSignedUrlPromise() ⇒ Promise

Note:

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

Returns a 'thenable' promise that will be resolved with a pre-signed URL for a given operation name.

Two callbacks can be provided to the then method on the returned promise. The first callback will be called if the promise is fulfilled, and the second callback will be called if the promise is rejected.

Examples:

Pre-signing a getObject operation

var params = {Bucket: 'bucket', Key: 'key'};
var promise = s3.getSignedUrlPromise('getObject', params);
promise.then(function(url) {
  console.log('The URL is', url);
}, function(err) { ... });

Pre-signing a putObject operation with a specific payload

var params = {Bucket: 'bucket', Key: 'key', Body: 'body'};
var promise = s3.getSignedUrlPromise('putObject', params);
promise.then(function(url) {
  console.log('The URL is', url);
}, function(err) { ... });

Passing in a 1-minute expiry time for a pre-signed URL

var params = {Bucket: 'bucket', Key: 'key', Expires: 60};
var promise = s3.getSignedUrlPromise('getObject', params);
promise.then(function(url) {
  console.log('The URL is', url);
}, function(err) { ... });

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.

Callbacks:

  • function(url) { ... }

    Called if the promise is fulfilled.

    Parameters:

    • url (String)

      the signed url

  • function(err) { ... }

    Called if the promise is rejected.

    Parameters:

    • err (Error)

      if an error occurred, this value will be filled

Returns:

  • (Promise)

    A promise that represents the state of the refresh call.

headBucket(params = {}, callback) ⇒ AWS.Request

This operation is useful to determine if a bucket exists and you have permission to access it.

Examples:

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. The data object has the following properties:

      • IBMSSEKPEnabled — (Boolean)
      • IBMSSEKPCustomerRootKeyCrn — (String)

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

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.

Examples:

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,
  MirrorDestination: 'STRING_VALUE',
  PartNumber: 0,
  Range: 'STRING_VALUE',
  SSECustomerAlgorithm: 'STRING_VALUE',
  SSECustomerKey: Buffer.from('...') || '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)
    • MirrorDestination — (String) Mirror source for object reads.
    • 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; IBM 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. IBM COS uses this header for a message integrity check to ensure the encryption key was transmitted without error.
    • 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. The data 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
      • 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.
      • 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.
      • RetentionExpirationDate — (Date) Date on which it will be legal to delete or modify the object. You can only specify this or the Retention-Period header. If both are specified a 400 error will be returned. If neither is specified the bucket's DefaultRetention period will be used. This header should be used to calculate a retention period in seconds and then stored in that manner.
      • RetentionLegalHoldCount — (Integer) Returns the count of legal holds on the object. If there are no legal holds, the header is not returned
      • RetentionPeriod — (Integer) Retention period to store on the object in seconds. If this field and Retention-Expiration-Date are specified a 400 error is returned. If neither is specified the bucket's DefaultRetention period will be used. 0 is a legal value assuming the bucket's minimum retention period is also 0.
      • RetentionPeriodSource — (String) The source of the retention period stored for the object Possible values include:
        • "Bucket"
        • "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.
      • StorageClass — (String) Possible values include:
        • "STANDARD"
        • "REDUCED_REDUNDANCY"
        • "STANDARD_IA"
      • PartsCount — (Integer) The count of parts this object has.
      • Transition — (map) Provides information of the transition storage class and time of transition.
        • 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.
        • TemporaryCopyStorageClass — (String) This header is only included if an object is in the RestoreInProgress or Restored states. This header will indicate the storage class to which the restored copy of the data will be billed. Possible values include:
          • "GLACIER"
          • "STANDARD"
        • StorageClass — (String) The class of storage used to store the object. Possible values include:
          • "GLACIER"
          • "STANDARD"
      • TemporaryCopyStorageClass — (String) This header is only included if an object is in the RestoreInProgress or Restored states. This header will indicate the storage class to which the restored copy of the data will be billed. Possible values include:
        • "STANDARD"
        • "GLACIER"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

Waiter Resource States:

listBuckets(params = {}, callback) ⇒ AWS.Request

Returns a list of all buckets owned by the authenticated sender of the request.

Examples:

Calling the listBuckets operation

var params = {
  IBMServiceInstanceId: 'STRING_VALUE'
};
s3.listBuckets(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: {})
    • IBMServiceInstanceId — (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. The data object has the following properties:

      • Buckets — (Array<map>)
        • Name — (String) The name of the bucket.
        • CreationDate — (Date) Date the bucket was created.
        • LocationConstraint — (String) Possible values include:
          • "us-standard"
          • "us-vault"
          • "us-cold"
          • "us-flex"
          • "us-east-standard"
          • "us-east-vault"
          • "us-east-cold"
          • "us-east-flex"
          • "us-south-standard"
          • "us-south-vault"
          • "us-south-cold"
          • "us-south-flex"
          • "eu-standard"
          • "eu-vault"
          • "eu-cold"
          • "eu-flex"
          • "eu-gb-standard"
          • "eu-gb-vault"
          • "eu-gb-cold"
          • "eu-gb-flex"
          • "eu-de-standard"
          • "eu-de-vault"
          • "eu-de-cold"
          • "eu-de-flex"
          • "ap-standard"
          • "ap-vault"
          • "ap-cold"
          • "ap-flex"
          • "ams03-standard"
          • "ams03-vault"
          • "ams03-cold"
          • "ams03-flex"
          • "che01-standard"
          • "che01-vault"
          • "che01-cold"
          • "che01-flex"
          • "mel01-standard"
          • "mel01-vault"
          • "mel01-cold"
          • "mel01-flex"
          • "osl01-standard"
          • "osl01-vault"
          • "osl01-cold"
          • "osl01-flex"
          • "sao01-standard"
          • "sao01-vault"
          • "sao01-cold"
          • "sao01-flex"
          • "tor01-standard"
          • "tor01-vault"
          • "tor01-cold"
          • "tor01-flex"
      • Owner — (map)
        • DisplayName — (String)
        • ID — (String)

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

listBucketsExtended(params = {}, callback) ⇒ AWS.Request

Returns a list of all buckets owned by the authenticated sender of the request, along with the LocationConstraint describing the region that the bucket resides in and the bucket's storage tier.

Examples:

Calling the listBucketsExtended operation

var params = {
  IBMServiceInstanceId: 'STRING_VALUE',
  Marker: 'STRING_VALUE',
  MaxKeys: 0,
  Prefix: 'STRING_VALUE'
};
s3.listBucketsExtended(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: {})
    • IBMServiceInstanceId — (String)
    • 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.

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. The data object has the following properties:

      • IsTruncated — (Boolean)
      • Marker — (String)
      • Buckets — (Array<map>)
        • Name — (String) The name of the bucket.
        • CreationDate — (Date) Date the bucket was created.
        • LocationConstraint — (String) Possible values include:
          • "us-standard"
          • "us-vault"
          • "us-cold"
          • "us-flex"
          • "us-east-standard"
          • "us-east-vault"
          • "us-east-cold"
          • "us-east-flex"
          • "us-south-standard"
          • "us-south-vault"
          • "us-south-cold"
          • "us-south-flex"
          • "eu-standard"
          • "eu-vault"
          • "eu-cold"
          • "eu-flex"
          • "eu-gb-standard"
          • "eu-gb-vault"
          • "eu-gb-cold"
          • "eu-gb-flex"
          • "eu-de-standard"
          • "eu-de-vault"
          • "eu-de-cold"
          • "eu-de-flex"
          • "ap-standard"
          • "ap-vault"
          • "ap-cold"
          • "ap-flex"
          • "ams03-standard"
          • "ams03-vault"
          • "ams03-cold"
          • "ams03-flex"
          • "che01-standard"
          • "che01-vault"
          • "che01-cold"
          • "che01-flex"
          • "mel01-standard"
          • "mel01-vault"
          • "mel01-cold"
          • "mel01-flex"
          • "osl01-standard"
          • "osl01-vault"
          • "osl01-cold"
          • "osl01-flex"
          • "sao01-standard"
          • "sao01-vault"
          • "sao01-cold"
          • "sao01-flex"
          • "tor01-standard"
          • "tor01-vault"
          • "tor01-cold"
          • "tor01-flex"
      • Owner — (map)
        • DisplayName — (String)
        • ID — (String)

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

listLegalHolds(params = {}, callback) ⇒ AWS.Request

Returns a list of legal holds on an object

Examples:

Calling the listLegalHolds operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Key: 'STRING_VALUE', /* required */
  MirrorDestination: 'STRING_VALUE'
};
s3.listLegalHolds(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)
    • MirrorDestination — (String) Mirror source for object reads.

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. The data object has the following properties:

      • CreateTime — (Date)
      • LegalHolds — (Array<map>)
        • Date — (Date)
        • ID — (String)
      • RetentionPeriod — (Integer) Retention period to store on the object in seconds. The object can be neither overwritten nor deleted until the amount of time specified in the retention period has elapsed. If this field and Retention-Expiration-Date are specified a 400 error is returned. If neither is specified the bucket's DefaultRetention period will be used. 0 is a legal value assuming the bucket's minimum retention period is also 0.
      • RetentionPeriodExpirationDate — (Date)

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

listMultipartUploads(params = {}, callback) ⇒ AWS.Request

This operation lists in-progress multipart uploads.

Examples:

Calling the listMultipartUploads operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Delimiter: 'STRING_VALUE',
  EncodingType: 'url',
  KeyMarker: 'STRING_VALUE',
  MaxUploads: 0,
  MirrorDestination: 'STRING_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 IBM COS 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 IBM COS 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.
    • MirrorDestination — (String) Mirror source for object reads.
    • 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. The data 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"
        • 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 IBM COS to encode object keys in the response. Possible values include:
        • "url"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

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.

Examples:

Calling the listObjects operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Delimiter: 'STRING_VALUE',
  EncodingType: 'url',
  Marker: 'STRING_VALUE',
  MaxKeys: 0,
  MirrorDestination: 'STRING_VALUE',
  Prefix: 'STRING_VALUE'
};
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 IBM COS 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 IBM COS 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.
    • MirrorDestination — (String) Mirror source for object reads.
    • Prefix — (String) Limits the response to keys that begin with the specified 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. The data object has the following properties:

      • IBMSSEKPEnabled — (Boolean)
      • IBMSSEKPCustomerRootKeyCrn — (String)
      • IsTruncated — (Boolean) A flag that indicates whether or not IBM COS 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. IBM COS 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"
        • 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 IBM COS to encode object keys in the response. Possible values include:
        • "url"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

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.

Examples:

Calling the listObjectsV2 operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  ContinuationToken: 'STRING_VALUE',
  Delimiter: 'STRING_VALUE',
  EncodingType: 'url',
  FetchOwner: true || false,
  MaxKeys: 0,
  Prefix: 'STRING_VALUE',
  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

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. The data 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"
        • 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

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

listObjectVersions(params = {}, callback) ⇒ AWS.Request

Returns metadata about all of the versions of objects in a bucket.

Examples:

Calling the listObjectVersions operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Delimiter: 'STRING_VALUE',
  EncodingType: 'url',
  KeyMarker: 'STRING_VALUE',
  MaxKeys: 0,
  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 IBM COS 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 IBM COS 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. The data 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"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

listParts(params = {}, callback) ⇒ AWS.Request

Lists the parts that have been uploaded for a specific multipart upload.

Examples:

Calling the listParts operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Key: 'STRING_VALUE', /* required */
  UploadId: 'STRING_VALUE', /* required */
  MaxParts: 0,
  MirrorDestination: 'STRING_VALUE',
  PartNumberMarker: 0
};
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.
    • MirrorDestination — (String) Mirror source for object reads.
    • 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.

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. The data 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 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"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

putBucketAcl(params = {}, callback) ⇒ AWS.Request

Sets the permissions on a bucket using access control lists (ACL).

Examples:

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.
          • Typerequired — (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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

putBucketCors(params = {}, callback) ⇒ AWS.Request

Sets the cors configuration for a bucket.

Examples:

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: 0
      },
      /* 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)
      • CORSRulesrequired — (Array<map>)
        • AllowedHeaders — (Array<String>) Specifies which headers are allowed in a pre-flight OPTIONS request.
        • AllowedMethodsrequired — (Array<String>) Identifies HTTP methods that the domain/origin specified in the rule is allowed to execute.
        • AllowedOriginsrequired — (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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

putBucketLifecycle(params = {}, callback) ⇒ AWS.Request

No longer used, see the PutBucketLifecycleConfiguration operation.

Examples:

Calling the putBucketLifecycle operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  ContentMD5: 'STRING_VALUE',
  LifecycleConfiguration: {
    Rules: [ /* required */
      {
        Filter: { /* required */
          Prefix: 'STRING_VALUE'
        },
        ID: 'STRING_VALUE', /* required */
        Status: 'Enabled | Disabled', /* required */
        Expiration: {
          Date: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
          Days: 0,
          ExpiredObjectDeleteMarker: true || false
        },
        Prefix: 'STRING_VALUE',
        Transitions: [
          {
            Date: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
            Days: 0,
            StorageClass: 'GLACIER | STANDARD',
            TemporaryCopyStorageClass: 'GLACIER | STANDARD'
          },
          /* more items */
        ]
      },
      /* 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)

      • Rulesrequired — (Array<map>) Currently only one Rule allowed.
        • 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.
        • IDrequired — (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 deprecated; use Filter instead.
        • Filterrequired — (map) The Filter is used to identify objects that a Lifecycle Rule applies to. Currently not supported.
          • Prefix — (String) Empty prefix allowed only.
        • Statusrequired — (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>) Currently only one Transition allowed, also Date and Days fields are mutually exclusive.
          • 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.
          • TemporaryCopyStorageClass — (String) This header is only included if an object is in the RestoreInProgress or Restored states. This header will indicate the storage class to which the restored copy of the data will be billed. Possible values include:
            • "GLACIER"
            • "STANDARD"
          • StorageClass — (String) The class of storage used to store the object. Possible values include:
            • "GLACIER"
            • "STANDARD"

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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

putBucketLifecycleConfiguration(params = {}, callback) ⇒ AWS.Request

Sets lifecycle configuration for your bucket. If a lifecycle configuration exists, it replaces it.

Examples:

Calling the putBucketLifecycleConfiguration operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  LifecycleConfiguration: {
    Rules: [ /* required */
      {
        Filter: { /* required */
          Prefix: 'STRING_VALUE'
        },
        ID: 'STRING_VALUE', /* required */
        Status: 'Enabled | Disabled', /* required */
        Expiration: {
          Date: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
          Days: 0,
          ExpiredObjectDeleteMarker: true || false
        },
        Prefix: 'STRING_VALUE',
        Transitions: [
          {
            Date: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
            Days: 0,
            StorageClass: 'GLACIER | STANDARD',
            TemporaryCopyStorageClass: 'GLACIER | STANDARD'
          },
          /* 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)
      • Rulesrequired — (Array<map>) Currently only one Rule allowed.
        • 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.
        • IDrequired — (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 deprecated; use Filter instead.
        • Filterrequired — (map) The Filter is used to identify objects that a Lifecycle Rule applies to. Currently not supported.
          • Prefix — (String) Empty prefix allowed only.
        • Statusrequired — (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>) Currently only one Transition allowed, also Date and Days fields are mutually exclusive.
          • 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.
          • TemporaryCopyStorageClass — (String) This header is only included if an object is in the RestoreInProgress or Restored states. This header will indicate the storage class to which the restored copy of the data will be billed. Possible values include:
            • "GLACIER"
            • "STANDARD"
          • StorageClass — (String) The class of storage used to store the object. Possible values include:
            • "GLACIER"
            • "STANDARD"

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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

putBucketProtectionConfiguration(params = {}, callback) ⇒ AWS.Request

Sets the protection configuration of an existing bucket.

Examples:

Calling the putBucketProtectionConfiguration operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  ProtectionConfiguration: { /* required */
    DefaultRetention: {
      Days: 0 /* required */
    },
    EnablePermanentRetention: true || false,
    MaximumRetention: {
      Days: 0 /* required */
    },
    MinimumRetention: {
      Days: 0 /* required */
    },
    Status: 'Retention'
  }
};
s3.putBucketProtectionConfiguration(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)
    • ProtectionConfiguration — (map) Container for setting retention settings.
      • Status — (String) Retention status of a bucket. Possible values include:
        • "Retention"
      • MinimumRetention — (map) Minimum retention period for an object, if a PUT of an object specifies a shorter retention period the PUT object will fail.
        • Daysrequired — (Integer)
      • DefaultRetention — (map) Default retention period for an object, if a PUT of an object does not specify a retention period this value will be converted to seconds and used.
        • Daysrequired — (Integer)
      • MaximumRetention — (map) Maximum retention period for an object, if a PUT of an object specifies a longer retention period the PUT object will fail.
        • Daysrequired — (Integer)
      • EnablePermanentRetention — (Boolean) Enable permanent retention for 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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

putBucketTagging(params = {}, callback) ⇒ AWS.Request

Sets the tags for a bucket.

Examples:

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)

      • TagSetrequired — (Array<map>)

        • Keyrequired — (String) Name of the tag.
        • Valuerequired — (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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

putBucketVersioning(params = {}, callback) ⇒ AWS.Request

Sets the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner.

Examples:

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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

putObject(params = {}, callback) ⇒ AWS.Request

Adds an object to a bucket.

Examples:

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: Buffer.from('...') || 'STRING_VALUE' || streamObject,
  CacheControl: 'STRING_VALUE',
  ContentDisposition: 'STRING_VALUE',
  ContentEncoding: 'STRING_VALUE',
  ContentLanguage: 'STRING_VALUE',
  ContentLength: 0,
  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: {
    someKey: 'STRING_VALUE',
    /* anotherKey: ... */
  },
  RetentionExpirationDate: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789,
  RetentionLegalHoldId: 'STRING_VALUE',
  RetentionPeriod: 0,
  SSECustomerAlgorithm: 'STRING_VALUE',
  SSECustomerKey: Buffer.from('...') || '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'
};
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.
    • 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.
    • RetentionExpirationDate — (Date) Date on which it will be legal to delete or modify the object. You can only specify this or the Retention-Period header. If both are specified a 400 error will be returned. If neither is specified the bucket's DefaultRetention period will be used. This header should be used to calculate a retention period in seconds and then stored in that manner.
    • RetentionLegalHoldId — (String) A single legal hold to apply to the object. A legal hold is a Y character long string. The object cannot be overwritten or deleted until all legal holds associated with the object are removed.
    • RetentionPeriod — (Integer) Retention period to store on the object in seconds. If this field and Retention-Expiration-Date are specified a 400 error is returned. If neither is specified the bucket's DefaultRetention period will be used. 0 is a legal value assuming the bucket's minimum retention period is also 0.
    • 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"
    • 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; IBM 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. IBM COS 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

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. The data 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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

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

Examples:

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',
  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.
          • Typerequired — (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)
    • 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. The data object has the following properties:

      • RequestCharged — (String) If present, indicates that the requester was successfully charged for the request. Possible values include:
        • "requester"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

restoreObject(params = {}, callback) ⇒ AWS.Request

Restores an archived copy of an object back into Amazon S3

Examples:

Calling the restoreObject operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Key: 'STRING_VALUE', /* required */
  RestoreRequest: {
    Days: 0, /* required */
    GlacierJobParameters: {
      Tier: 'Standard | Bulk | Expedited' /* required */
    }
  },
  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)
      • Daysrequired — (Integer) Lifetime of the active copy in days
      • GlacierJobParameters — (map) Glacier related parameters pertaining to this job. Do not use with restores that specify OutputLocation.
        • Tierrequired — (String) Glacier retrieval tier at which the restore will be processed. Possible values include:
          • "Standard"
          • "Bulk"
          • "Expedited"

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. The data object has the following properties:

      • RequestCharged — (String) If present, indicates that the requester was successfully charged for the request. Possible values include:
        • "requester"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

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.
    • 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.
    • RetentionExpirationDate — (Date) Date on which it will be legal to delete or modify the object. You can only specify this or the Retention-Period header. If both are specified a 400 error will be returned. If neither is specified the bucket's DefaultRetention period will be used. This header should be used to calculate a retention period in seconds and then stored in that manner.
    • RetentionLegalHoldId — (String) A single legal hold to apply to the object. A legal hold is a Y character long string. The object cannot be overwritten or deleted until all legal holds associated with the object are removed.
    • RetentionPeriod — (Integer) Retention period to store on the object in seconds. If this field and Retention-Expiration-Date are specified a 400 error is returned. If neither is specified the bucket's DefaultRetention period will be used. 0 is a legal value assuming the bucket's minimum retention period is also 0.
    • 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"
    • 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; IBM 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. IBM COS 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

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: * Location (String) the URL of the uploaded object * ETag (String) the ETag of the uploaded object * Bucket (String) the bucket to which the object was uploaded * Key (String) the key to which the object was uploaded

    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, IBM COS frees up the parts storage and stops charging you for the parts storage.

Examples:

Calling the uploadPart operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  Key: 'STRING_VALUE', /* required */
  PartNumber: 0, /* required */
  UploadId: 'STRING_VALUE', /* required */
  Body: Buffer.from('...') || 'STRING_VALUE' || streamObject,
  ContentLength: 0,
  ContentMD5: 'STRING_VALUE',
  SSECustomerAlgorithm: 'STRING_VALUE',
  SSECustomerKey: Buffer.from('...') || '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; IBM 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. IBM COS uses this header for a message integrity check to ensure the encryption key was transmitted without error.

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. The data 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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

uploadPartCopy(params = {}, callback) ⇒ AWS.Request

Uploads a part by copying data from an existing object as data source.

Examples:

Calling the uploadPartCopy operation

var params = {
  Bucket: 'STRING_VALUE', /* required */
  CopySource: 'STRING_VALUE', /* required */
  Key: 'STRING_VALUE', /* required */
  PartNumber: 0, /* 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: Buffer.from('...') || 'STRING_VALUE' /* Strings will be Base-64 encoded on your behalf */,
  CopySourceSSECustomerKeyMD5: 'STRING_VALUE',
  SSECustomerAlgorithm: 'STRING_VALUE',
  SSECustomerKey: Buffer.from('...') || '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 GB.
    • 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; IBM 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. IBM COS 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. IBM COS uses this header for a message integrity check to ensure the encryption key was transmitted without error.

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. The data 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.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

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:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

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. The data object has the following properties:

      • IBMSSEKPEnabled — (Boolean)
      • IBMSSEKPCustomerRootKeyCrn — (String)

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

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. The data object has the following properties:

      • IBMSSEKPEnabled — (Boolean)
      • IBMSSEKPCustomerRootKeyCrn — (String)

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

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)
    • MirrorDestination — (String) Mirror source for object reads.
    • 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; IBM 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. IBM COS uses this header for a message integrity check to ensure the encryption key was transmitted without error.
    • 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. The data 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
      • 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.
      • 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.
      • RetentionExpirationDate — (Date) Date on which it will be legal to delete or modify the object. You can only specify this or the Retention-Period header. If both are specified a 400 error will be returned. If neither is specified the bucket's DefaultRetention period will be used. This header should be used to calculate a retention period in seconds and then stored in that manner.
      • RetentionLegalHoldCount — (Integer) Returns the count of legal holds on the object. If there are no legal holds, the header is not returned
      • RetentionPeriod — (Integer) Retention period to store on the object in seconds. If this field and Retention-Expiration-Date are specified a 400 error is returned. If neither is specified the bucket's DefaultRetention period will be used. 0 is a legal value assuming the bucket's minimum retention period is also 0.
      • RetentionPeriodSource — (String) The source of the retention period stored for the object Possible values include:
        • "Bucket"
        • "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.
      • StorageClass — (String) Possible values include:
        • "STANDARD"
        • "REDUCED_REDUNDANCY"
        • "STANDARD_IA"
      • PartsCount — (Integer) The count of parts this object has.
      • Transition — (map) Provides information of the transition storage class and time of transition.
        • 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.
        • TemporaryCopyStorageClass — (String) This header is only included if an object is in the RestoreInProgress or Restored states. This header will indicate the storage class to which the restored copy of the data will be billed. Possible values include:
          • "GLACIER"
          • "STANDARD"
        • StorageClass — (String) The class of storage used to store the object. Possible values include:
          • "GLACIER"
          • "STANDARD"
      • TemporaryCopyStorageClass — (String) This header is only included if an object is in the RestoreInProgress or Restored states. This header will indicate the storage class to which the restored copy of the data will be billed. Possible values include:
        • "STANDARD"
        • "GLACIER"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

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)
    • MirrorDestination — (String) Mirror source for object reads.
    • 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; IBM 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. IBM COS uses this header for a message integrity check to ensure the encryption key was transmitted without error.
    • 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. The data 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
      • 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.
      • 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.
      • RetentionExpirationDate — (Date) Date on which it will be legal to delete or modify the object. You can only specify this or the Retention-Period header. If both are specified a 400 error will be returned. If neither is specified the bucket's DefaultRetention period will be used. This header should be used to calculate a retention period in seconds and then stored in that manner.
      • RetentionLegalHoldCount — (Integer) Returns the count of legal holds on the object. If there are no legal holds, the header is not returned
      • RetentionPeriod — (Integer) Retention period to store on the object in seconds. If this field and Retention-Expiration-Date are specified a 400 error is returned. If neither is specified the bucket's DefaultRetention period will be used. 0 is a legal value assuming the bucket's minimum retention period is also 0.
      • RetentionPeriodSource — (String) The source of the retention period stored for the object Possible values include:
        • "Bucket"
        • "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.
      • StorageClass — (String) Possible values include:
        • "STANDARD"
        • "REDUCED_REDUNDANCY"
        • "STANDARD_IA"
      • PartsCount — (Integer) The count of parts this object has.
      • Transition — (map) Provides information of the transition storage class and time of transition.
        • 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.
        • TemporaryCopyStorageClass — (String) This header is only included if an object is in the RestoreInProgress or Restored states. This header will indicate the storage class to which the restored copy of the data will be billed. Possible values include:
          • "GLACIER"
          • "STANDARD"
        • StorageClass — (String) The class of storage used to store the object. Possible values include:
          • "GLACIER"
          • "STANDARD"
      • TemporaryCopyStorageClass — (String) This header is only included if an object is in the RestoreInProgress or Restored states. This header will indicate the storage class to which the restored copy of the data will be billed. Possible values include:
        • "STANDARD"
        • "GLACIER"

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

See Also: