AWS S3 v2

このライブラリは、Amazon Simple Storage Service (Amazon S3)と通信する機能を提供する組み込みクラスです。

Library usage requirements
Type	Integrations
Name	AWS_S3_V2
Version	2020-11-04
Code size used	8.2KB
Resources used	HTTPS x 1, Timers x 1

Abstracts

Method()/Property	Summary
`new AWS_S3()`	`AWS_S3`インスタンスを生成します。

{AWS_S3} Instance

Method()/Property	Summary
`.createXAmzHeaders()`	AWS APIスタイルの `params` を `x-amz-*` ヘッダーに変換します。 `bucket` と `key` を無視します。
`.createHttpHeader()`	AWS Signature v4のドキュメントに従って、指定された引数の認証ヘッダーを作成します。
`.put()`	PUTリクエストを送信し、結果をコールバック関数に出力します。
`.get()`	GETリクエストを送信し、渡されたコールバックに結果を出力します。
`.abortRequest()`	現在進行中のリクエストを中止します。
`.errors`	無効なキー名を含む配列。無効な構成がコンストラクターに渡された場合にのみ存在します。

Details

`new AWS_S3(config)`

渡された設定でAWS_S3オブジェクトを初期化します。

Configuration

AWS_S3 オブジェクトをインスタンス化する場合、次のパラメータをユーザーが設定する必要があります。

Name	Type	Default	Summary
`region`	string	MANDATORY	バケットにアクセスするときに使用されるリージョン
`accessKeyId`	string	MANDATORY	AWS IAMのアクセスキーID
`secretKey`	string	MANDATORY	AWS IAMのシークレットアクセスキー
`bucket`	string	MANDATORY	操作するS3バケットの名前
`ca`	string	MANDATORY	S3対応のルートCA
`timeout`	number	90000	`AWS_S3`インスタンスのタイムアウト(ミリ秒) ver. 2020-07-20+

次のように、構成はJavaScriptオブジェクトである必要があります。

var config = {
    region: "<String>",
    accessKeyId: "<String>",
    secretKey: "<String>",
    bucket: "<String>",
    ca: "<String>"
};

設定が適用されると、インスタンスの作成時に AWS_S3 に渡すことができます。

var s3 = new AWS_S3(config);
if ('errors' in s3) {
    // TODO: handle errors
}

Setter Methods

AWS_S3 オブジェクトを作成した後、前述の設定のそれぞれは、対応するセッターによって変更され、 String タイプの値が渡されます。 accessKeyId と secretKey の値はAWS IAMから取得できます。

Setter	Summary
`.setRegion(value: string)`	この`AWS_S3`インスタンスのリージョンを設定します。
`.setBucket(value: string)`	この`AWS_S3`インスタンスのバケットを設定します。
`.setAccessKeyId(value: string)`	認証に使用されるこの`AWS_S3`インスタンスのアクセスキーIDを設定します。
`.setSecretKey(value: string)`	認証に使用されるこの`AWS_S3`インスタンスのシークレットアクセスキーを設定します。
`.setRootCA(value: string)`	AWSへの接続に使用されるこの`AWS_S3`インスタンスのルートCAを設定します。下記の例で確認できます。
`.setRequestTimeout(value: Number)`	この`AWS_S3`インスタンスのタイムアウトを設定します。 ver. 2020-07-20+

設定のセッターは、すべて成功した場合は、チェーンさせることもできます。メソッドチェーンのAWS_S3インスタンスではなく、無効な値が指定されると、各セッターはエラーを返します。

`.setConfig(config)`

setConfig メソッドは複数の設定オプションを同時に設定または変更するために使用でき、 key:value ペアの典型的なJavaScriptオブジェクトを引数として受け取ります。

s3.setConfig({
    region: "value",
    accessKeyId: "value",
    secretKey: "value",
    bucket: "value",
    ca: "value"
});

Instance Methods

`.createXAmzHeaders(params)`

渡された params から x-amz-* ヘッダーを作成します。

Name	Type	Default	Summary
`params`	object	MANDATORY	`x-amz-*` ヘッダーに変換するAWS APIの `params` オブジェクト。
return	object	-	API docsで `params` が存在する場合、`x-ams-*` ヘッダーに変換します。

`.createHttpHeader(host,path,method,bodyToHash,additionalHeaders)`

AWS Signature v4のドキュメントに従って、指定された引数の認証ヘッダーを作成します。
このメソッドは、直接HTTPオブジェクトを用いて通信する場合に活用できます。

Name	Type	Default	Summary
`host`	string	MANDATORY	HTTPホスト
`path`	string	MANDATORY	HTTPパス
`method`	string	MANDATORY	HTTPメソッド
`bodyToHash`	string	MANDATORY	HTTPボディ; BODYの代わりに `null` を渡すとき、UNSIGNED_PAYLOADを送ります。
`additionalHeaders`	object	MANDATORY	デジタル署名用の`x-amz-*`ヘッダーが入っているオブジェクト
return	object	-	`{ Authorization: [auth], x-amz-content-sha256: [contenthash], x-amz-date: [timestamp]}`

`.put(path,userHeaders,body,callback)`

PUTリクエストを送信し、結果をコールバック関数に返します。このメソッドは、AWS S3 APIを使用します: https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html

Name	Type	Default	Summary
`path`	string	MANDATORY	目的のリソースへのパス。ホストはいつも `[bucket].s3.amazonaws.com` になります。
`userHeaders`	object	MANDATORY	"Content-Length"ヘッダー(必須)と追加のHTTP/2または `x-amz-*` ヘッダーを持つオブジェクト。
`body`	function	MANDATORY	オブジェクトのコンテンツを取得するためのコールバック。データがなくなるまで4KB以下の [string/ArrayBuffer]チャンクでデータを返し、その後`null`を返す必要があります。
`callback(err, resp)`	function	MANDATORY	レスポンスを処理するためのユーザーのコールバック関数。エラーを `err`として渡し、レスポンスを`resp`として渡します。

`.get(path,callback)`

GETリクエストを送信し、渡されたコールバックに結果を出力します。このメソッドは、AWS S3 APIを使用します: https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html

Name	Type	Default	Summary
`path`	string	MANDATORY	目的のリソースへのパス。ホストは常に `[bucket].s3.amazonaws.com` です。
`callback(err, resp)`	function	MANDATORY	レスポンスを処理するためのユーザーのコールバック関数。エラーを `err`として渡し、レスポンスを`resp`として渡します。

`.abortRequest()`

現在実行中のリクエストを中止します。

Name	Type	Default	Summary
return	undefined	-	-

Response Object

このライブラリは、レスポンスと呼ばれるオブジェクトを使用して、AWSサーバーのレスポンスを処理します。レスポンスは常に次の形式になります。

{
    statusCode: <Number>,
    statusMessage: <String>,
    body: <ArrayBuffer> or <String>
}

statusCode と statusMessage の詳しくはデバイス(NEQTO Bridge | Spresense)によってHTTPsのドキュメントで見られます。 response はドキュメントにある .read() の結果です。

Errors

このライブラリでは、エラーは2つの方法で返されます。 Setter Methodsからの戻り値、および、 callback 関数の err に渡されるHTTPメソッドのエラーです。

HTTPリクエストの外部で発生したエラーは、次の形式を取ります。

{
    name: <String>,
    message: <String>
}

HTTPリクエストから発生したエラーは、次の形式を取ります。

{
    errCode: <Number>
}

Content-Length ヘッダーの欠落などの無効な設定を検出するエラーは、 message プロパティを持ちます。HTTPSレイヤーから発生したエラーには、このプロパティはありません。この方法で発生したエラーには、NEQTO BridgeとSpresenseの errCode パラメーターに関する詳細情報がneqto.jsのドキュメントにあります。

以下は、さまざまな形式のエラーを処理する方法の例です。

var invalidConfig = {
    badKey: "badValue"
};
var s3 = new AWS_S3(invalidConfig);
// s3 now contains an array of errors
if (Array.isArray(s3)) {
    //handle config errors
} else {
    //s3 is good in this block
    var callback = function (err, data) {
        if (err) {
            // handle errors
            JSON.stringify(err)
        } else {
            // handle data
        }
    }
    s3.get('/example.txt', callback);
}

Usage Examples

config オプションで使用できる CAの取得方法はこちら。

ルートCAがターゲットのS3エンドポイントに適切であることを確認してください。

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

Sample １: S3にオブジェクトを書き込む

// IMPORTED LIBRARIES
// - AWS_S3_V2

// Logging setup
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

// Set config
var config = {
    region: "<String>",
    accessKeyId: "<String>",
    secretKey: "<String>",
    bucket: "<String>",
    ca: awsS3Ca
};

var callback = function (err, data) {
    if (err) {
        print("Error!", JSON.stringify(err));
    } else {
        print(data.statusCode, data.statusMessage);
        print(data.body);
    }
}

var s3 = new AWS_S3(config);
if ('errors' in s3) {
    // TODO: handle errors
    throw 'Invalid configuration'
}

/**
 * Create a large buffer (representing data generated from sensors)
 * and send it to AWS S3 with a custom tag and ACL parameter.
 */

 var path = '/path/to/resource.txt';
 var dataSize = 12 * 1024;
 var params = {
     "Tagging": "example=tag", // Requires the s3:PutObjectTagging permission
     "ACL": "bucket-owner-full-control", // Requires the s3:PutObjectAcl permission
     "ContentLength": dataSize.toString()
 }

 var buffer = new ArrayBuffer(dataSize);
 var bufferView = new Uint8Array(buffer);
 for (var b = 0; b < bufferView.length; b++) {
     bufferView[b] = (b % 255); // Fill it with arbitrary data
 }

 var putObject = function(path, params, body, callback) {
     var headers = s3.createXAmzHeaders(params);
     var MAX_CHUNK_SIZE = 4 * 1024;
     var bodyIndex = 0;
     var getNextChunk = function() {
         var ret;
         if (bodyIndex >= dataSize) {
             ret = null;
         } else {
             ret = body.slice(bodyIndex, bodyIndex + MAX_CHUNK_SIZE);
         }
         if (ret) {
             bodyIndex += ret.length || ret.byteLength;
         }
         return ret;
     }
     s3.put(path, headers, getNextChunk, callback);
 }

 putObject(path, params, buffer, callback);

Sample 2: ストレージからS3にデータを書き込む

// IMPORTED LIBRARIES
// - AWS_S3_V2

// Logging setup
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

// Set config
var config = {
    region: "<String>",
    accessKeyId: "<String>",
    secretKey: "<String>",
    bucket: "<String>",
    ca: awsS3Ca
};

var callback = function (err, data) {
    if (err) {
        print("Error!", JSON.stringify(err));
    } else {
        print(data.statusCode, data.statusMessage);
        print(data.body);
    }
}

var s3 = new AWS_S3(config);
if ('errors' in s3) {
    // TODO: handle errors
    throw 'Invalid configuration'
}

/**
 * Store data on the filesystem, then send that stored data.
 */

var path = "/path/to/storage.txt";
var dataSize = 16384;
var params = {
    "ContentLength": dataSize.toString(),
}

var store = storage.open();
var head = "HEADER:";

// // Create a test data string and save it to memory
var s = "";
// Up to 4KB of data, to be compatible with put()
while(s.length < 1024) {
    s += "testdata";
}
for (var i = 0; i < 24; i++) {
    store.writeFrame(head, s);
}

// If there was an error during memory save, recover it.
if (!store.readFrame(head, 0)) {
    var ret = store.recoverFrame(head);
}

var putStringFromStorage = function (strStore) {
    var headers = s3.createXAmzHeaders(params);
    var getData;
    if (strStore) {
        if (strStore.getReadableSize() < dataSize) {
            return null;
        }
        if (head) {
            // Get total amount of data in frames with this head
            var frames = strStore.searchAllFrame(head, 0);
            if (frames < dataSize) { // not enough stored data
                return null;
            }
            // Get total number of frames with this head
            frames = strStore.searchAllFrame(head, 1);
            var frameIndex = -1;
            var frameDataCollectedSize = 0;
            var getData = function() {
                if (frameIndex++ < frames && frameDataCollectedSize < dataSize) {
                    var ret = strStore.searchFrame(head, frameIndex);
                    frameDataCollectedSize += ret.length;
                    return ret;
                } else {
                    return null;
                }
            }
        }
    }
    s3.put(path, headers, getData, callback);
}
putStringFromStorage(store);

Sample 3: S3にカスタムなコールバックでデータ書き込む

// IMPORTED LIBRARIES
// - AWS_S3_V2

// Logging setup
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

// Set config
var config = {
    region: "<String>",
    accessKeyId: "<String>",
    secretKey: "<String>",
    bucket: "<String>",
    ca: awsS3Ca
};

var callback = function (err, data) {
    if (err) {
        print("Error!", JSON.stringify(err));
    } else {
        print(data.statusCode, data.statusMessage);
        print(data.body);
    }
}

var s3 = new AWS_S3(config);
if ('errors' in s3) {
    // TODO: handle errors
    throw 'Invalid configuration'
}

/**
 * Send data to S3 using a custom getData method.
 */

 var path = "/path/to/custom.txt";
 var dataSize = 256;
 var params = {
     "Content-Length": dataSize.toString()
 }

 var send = false;
 var getData = function () { // Must return String, ArrayBuffer, or null.
     if (send) {
         return null;
     } else {
         send = true;
         var i = 0;
         var ret = "";
         while (i++ < dataSize) {
             ret += String.fromCharCode((i % 95) + 32); // ASCII table
         }
         return ret;
     }
 }

 s3.put(path, params, getData, callback);

上記に記載されている会社名、製品名は、各社の登録商標または商標です。

Updated: 2023-01-20

NEQTO Apps

ハードウェア仕様

ソフトウェア仕様

neqto.js

ハードウェア仕様

ソフトウェア仕様

neqto.js

ハードウェア仕様

ソフトウェア仕様

neqto.js

ソフトウェア仕様

neqto.js

UART

I2C

Utils

Integration

関連資料

Abstracts

{AWS_S3} Instance

Details

`new AWS_S3(config)`

Configuration

Setter Methods

`.setConfig(config)`

Instance Methods

`.createXAmzHeaders(params)`

`.createHttpHeader(host,path,method,bodyToHash,additionalHeaders)`

`.put(path,userHeaders,body,callback)`

`.get(path,callback)`

`.abortRequest()`

Response Object

Errors

Usage Examples

Sample １: S3にオブジェクトを書き込む

Sample 2: ストレージからS3にデータを書き込む

Sample 3: S3にカスタムなコールバックでデータ書き込む