AWS S3 v2

This library is a built-in class that provides functions to communicate with Amazon Simple Storage Service (Amazon S3).

Library usage requirements
Type	Integrations
Name	AWS_S3_V2
Version	2.1.0
Code size used	10.2KB
Resources used	HTTPS x 1, Timers x 1

Abstracts

Methods()/Properties	Summary	Note
new AWS_S3()	Creates an AWS_S3 instance.

{AWS_S3} Instance

Method()/Property	Summary	Note
.createXAmzHeaders()	Creates HTTP headers from a parameter list with HTTP request parameter names in the AWS API style.
.createHttpHeader()	Creates an authentication header for the `AWS Signature v4` specification.
.put()	Sends data to the S3 bucket with a PUT request.
.get()	Gets data from the S3 bucket with a GET request.
.abortRequest()	Aborts the currently ongoing HTTP request.
.errors	Array of {Error} objects containing invalid key names (strings) Generated when an invalid parameter is detected in the constructor or .setConfig().
.CONST.VERSION	Version (string)	v2.1.0+

Details

new AWS_S3([config])

Creates an AWS_S3 instance.

Name	Type	M/O	Description	Note
config	Object	optional	Configuration Refer to config for details.
return	{AWS_S3}	-	{AWS_S3} : Generated {AWS_S3}	If invalid parameters are detected, .errors will be generated.

config

Name	Type	M/O	Description	Note
region	string	mandatory	Region to be used when accessing the S3 bucket
accessKeyId	string	mandatory	IAM access key ID
secretKey	string	mandatory	IAM secret access key
bucket	string	mandatory	S3 bucket name
ca	string	mandatory	Root CA certificate for AWS S3 Specify a string in PEM format. Use `\n` for line feed code.
httpTimeout	number	optional	HTTP request timeout value [s] If `0`, the timeout function is disabled. The default value is `0`.	v2.1.0+
timeout	number	-	This parameter is ignored.	Unused

Set the Configuration (config) when creating an AWS_S3 instance.
If an invalid parameter is detected, an array of {Error} objects containing the invalid key name is generated as the .errors property. If the parameters are successful, the .errors property will be deleted.

var s3 = new AWS_S3({
    region: <value>,
    accessKeyId: <value>,
    secretKey: <value>,
    bucket: <value>,
    ca: <value>
});
if('errors' in s3) {
    //TODO: Handle errors
}

{Error}

Name	Type	Description	Note
.name	string	Invalid key name
.message	string	Error Messages

.setConfig(config)

Set the Configuration (config) after the AWS_S3 instance is created.
If an invalid parameter is detected, an array of {Error} objects containing the invalid key name is generated as the .errors property. If the parameters are successful, the .errors property will be deleted.

var s3 = new AWS_S3();
s3.setConfig({
    region: <value>,
    accessKeyId: <value>,
    secretKey: <value>,
    bucket: <value>,
    ca: <value>
});
if('errors' in s3) {
    //TODO: Handle errors
}

Setter Methods

After the AWS_S3 instance is created, Configuration (config) can be set individually using the following setter methods.
If successful, the own instance is returned. If an invalid parameter is detected, {Error} is returned.

Setter Method	Description	Note
.setRegion(value)	Sets the `region`.
.setAccessKeyId(value)	Sets the `accessKeyId`.
.setSecretKey(value)	Sets the `secretKey`.
.setBucket(value)	Sets the `bucket`.
.setRootCA(value)	Sets the `ca`.
.setHttpTimeout(value)	Sets the `httpTimeout`.	v2.1.0+
.setRequestTimeout(value)	Sets the `timeout`.	Unused

.createXAmzHeaders(params)

Creates HTTP headers from a parameter list with HTTP request parameter names in the AWS API style.

The following request parameters are supported by this method.

AWS API - PutObject
AWS API - GetObject (v2.1.0+)

If any other request parameter name is specified, it will be inherited by the HTTP headers generated without conversion.
Note that bucket and key cannot be used as request parameter names. They will be ignored.

Name	Type	M/O	Description	Note
params	object	mandatory	Parameter list
return	object	-	HTTP header

The following is an example of usage:

var params = {
    //<RequestPatameterName>: <value> 
    "Tagging": "example=tag",
    "ACL": "bucket-owner-full-control",
    "ContentLength": 256
};

//Request parameter names are converted to HTTP headers
var headers = s3.createXAmzHeaders(params);

print(JSON.stringify(headers));
//{"x-amz-tagging":"example=tag","x-amz-acl":"bucket-owner-full-control","Content-Length":256}

.createHttpHeader(host,path,method[,bodyToHash[,additionalHeaders]])

Creates an authentication header for the AWS Signature v4 specification.
This method can be utilized when programming directly with the HTTPS object.

Name	Type	M/O	Description
host	string	mandatory	HTTP host
path	string	mandatory	HTTP path
method	string	mandatory	HTTP method
bodyToHash	string	optional	HTTP body Specify when applying the `Signed payload` option. If not specified (default), the `Unsigned payload` option will be applied.
additionalHeaders	object	optional	Additional `x-amz-` headers `x-amz-` headers can be additionally specified.
return	object	-	Authorization Header `{ Authorization: <auth>, x-amz-content-sha256: <contenthash>, x-amz-date: <timestamp>}`

.put(path,userHeaders,getBody,callback[,sockTo])

Sends data to the S3 bucket with a PUT request.

The host will be ${conig.bucket}.s3.amazonaws.com.
The authentication header is generated in this method and the Unsigned payload option is applied.

Name	Type	M/O	Description	Note
path	string	mandatory	Specify the path to the target resource.
userHeaders	object	mandatory	Specify HTTP request headers (`HTTP/1.1` and `x-amz-*` headers). "Content-Length" must be included.
getBody	function	mandatory	Execute callback processing at the timing when this method will accept the data (`body`) to be sent. Returns data in `string` or `ArrayBuffer` chunks of 4KB or less until there is no more data, and finally returns `null`.
callback(err, resp)	function	mandatory	Execute callback processing when this method is completed. Notify the processing result using the argument of the callback function. err: {HttpReqError}, null resp: {HttpResponse}, null If an error occurs in the HTTP request, `err` is set; if an HTTP response can be received, `resp` is set.
sockTo	number	optional	Specify the HTTP session timeout value [ms]. This parameter is the `sockTo` setting value of the `https.request()` method. For details, refer to the HTTPS object specification.	v2.1.0+
return	undefined	-

.get(path,callback[,isBin[,sockTo]])

Gets data from the S3 bucket with a GET request.

The host will be ${conig.bucket}.s3.amazonaws.com.
The authentication header is generated in this method and the Unsigned payload option is applied.

Name	Type	M/O	Description	Note
path	string	mandatory	Specify the path to the target resource.
callback(err, resp)	function	mandatory	Execute callback processing when an HTTP response event occurs. err: {HttpReqError}, null resp: {HttpResponse}, null If an error occurs in the HTTP request, `err` is set and the process ends. If an HTTP response could be received, `resp` is set. HTTP response data is split and notified in multiple callbacks. The end of processing can be determined by the HTTP response notification completion flag.
isBin	boolean	optional	Specify the type of HTTP response data (`resp`). true: ArrayBuffer false: string The default value is `false`.	v2.1.0+
sockTo	number	optional	Specify the HTTP session timeout value [ms]. This parameter is the `sockTo` setting value of the `https.request()` method. For details, refer to the HTTPS object specification.	v2.1.0+
return	undefined	-

.abortRequest()

Aborts the currently ongoing HTTP request.

Name	Type	M/O	Description	Note
return	undefined	-

{HttpReqError}

Name	Type	Description	Note
.errCode	number	The error code of the HTTPS request For details, refer to the error code table of the HTTPS object.

{HttpResponse}

Name	Type	Description	Note
.statusCode	number	The status code of the HTTP response
.statusMessage	string	The status message of the HTTP response
.body	string, null	HTTP response data (`Response-Body`) It may be `null` (no attached data) depending on the HTTP response content and the timing of HTTP reception.
.endFlag	boolean	HTTP response notification completion flag In the case of the .put() method, this flag will always be `true` as it is a batch notification. In the case of the .get() method, the HTTP response data is split and notified in multiple callbacks. Continue retrieving response data until this flag becomes `true`. true: Notification completed (End of processing) false: Not completed. Wait for next callback notification.	v2.1.0+

Usage Examples

The following common code is used in all sample code:

Make sure that the root CA certificate is appropriate for the S3 endpoint in advance.
For information on how to obtain a CA certificate, please refer to here.

log.setLevel(0,2); //-1:NONE 0:ERROR 1:WARNING 2:DEBUG 3:TRACE, 0:DISABLE 1:LOG 2:CONSOLE 3:BOTH
log.printLevel(2); //0:DISABLE 1:LOG 2:CONSOLE 3:BOTH

var rootCa = '-----BEGIN CERTIFICATE-----\n...<CA>...\n-----END CERTIFICATE-----';

//TODO: Configuration
var s3 = new AWS_S3({
    region: <value>,
    accessKeyId: <value>,
    secretKey: <value>,
    bucket: <value>,
    ca: rootCa
});
if('errors' in s3) {
    //TODO: Handle errors
    throw new Error("Invalid configuration");
}

Sample 1

Send data to an S3 bucket.

var path = "/path/to/sample.txt";
var body = "sample text to send to S3";
var headers = s3.createXAmzHeaders({
    "ContentLength": body.length.toString()
});

var busy;
var getBody = function() {
    var temp = body;
    body = null;
    return temp;
};
var callback = function(err, resp) {
    if(err) {
        print("Error!", err.errCode);
    } else {
        print("Response:", resp.body);
        print("Status:", resp.statusCode, resp.statusMessage);
    }
    busy = false;
};

busy = true;
s3.put(path, headers, getBody, callback);
while(busy);
print("Done");

Sample 2

Add custom tags and ACL parameters and send data to an S3 bucket.

var path = "/path/to/sample.txt";
var body = "sample text to send to S3";
var headers = s3.createXAmzHeaders({
    "Tagging": "example=tag", //Requires the s3:PutObjectTagging permission
    "ACL": "bucket-owner-full-control", //Requires the s3:PutObjectAcl permission
    "ContentLength": body.length.toString()
});

var busy;
var getBody = function() {
    var temp = body;
    body = null;
    return temp;
};
var callback = function(err, resp) {
    if(err) {
        print("Error!", err.errCode);
    } else {
        print("Response:", resp.body);
        print("Status:", resp.statusCode, resp.statusMessage);
    }
    busy = false;
};

busy = true;
s3.put(path, headers, getBody, callback);
while(busy);
print("Done");

Sample 3

Send data in chunks to an S3 bucket.

var path = "/path/to/sample.txt";
var body = "";
while(body.length < 1024*2) body += "0123456789ABCDEF"; //sample text
var headers = s3.createXAmzHeaders({
    "ContentLength": body.length.toString()
});

var busy;
var chunkSize = 1024; //4KB or less
var index = 0;
var getBody = function() {
    var chunk = body.substring(index, index + chunkSize);
    if(chunk) {
        index = index + chunkSize;
        return chunk;
    }
    return null;
};
var callback = function(err, resp) {
    if(err) {
        print("Error!", err.errCode);
    } else {
        print("Response:", resp.body);
        print("Status:", resp.statusCode, resp.statusMessage);
    }
    busy = false;
};

busy = true;
s3.put(path, headers, getBody, callback);
while(busy);
print("Done");

Sample 4

Retrieve data from an S3 bucket.

var path = "/path/to/sample.txt";

var busy;
var callback = function(err, resp) {
    if(err) {
        print("Error!", err.errCode);
        busy = false;
    } else {
        print("Response:", resp.body);
        if(resp.endFlag) {
            print("Status:", resp.statusCode, resp.statusMessage);
            busy = false;
        }
    }
};

busy = true;
s3.get(path, callback);
while(busy);
print("Done");

The company names and product names mentioned above are registered trademarks or trademarks of their respective companies.

Updated: 2024-03-26

NEQTO Apps

Hardware Specifications

Software Specifications

neqto.js

Hardware Specifications

Software Specifications

neqto.js

Hardware Specifications

Software Specifications

neqto.js

Software Specifications

neqto.js

UART

I2C

Utils

Integration

Related Documents

Abstracts

{AWS_S3} Instance

Details

new AWS_S3([config])

config

{Error}

.setConfig(config)

Setter Methods

.createXAmzHeaders(params)

.createHttpHeader(host,path,method[,bodyToHash[,additionalHeaders]])

.put(path,userHeaders,getBody,callback[,sockTo])

.get(path,callback[,isBin[,sockTo]])

.abortRequest()

{HttpReqError}

{HttpResponse}

Usage Examples

Sample 1

Sample 2

Sample 3

Sample 4