AWS S3 v2

このライブラリは、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()	AWS_S3インスタンスを生成します。

{AWS_S3} Instance

Method()/Property	Summary	Note
.createXAmzHeaders()	AWS APIスタイルのHTTPリクエストパラメータ名を用いたパラメータリストからHTTPヘッダを生成します。
.createHttpHeader()	`AWS Signature v4`仕様の認証ヘッダを生成します。
.put()	PUTリクエストでS3バケットにデータを送信します。
.get()	GETリクエストでS3バケットからデータを取得します。
.abortRequest()	現在進行中のHTTPリクエストを中止します。
.errors	無効なキー名(文字列)を含む{Error}オブジェクトの配列コンストラクタまたは.setConfig()で無効なパラメータが検出された場合に生成されます。
.CONST.VERSION	バージョン(文字列)	v2.1.0+

Details

new AWS_S3([config])

AWS_S3インスタンスを生成します。

Name	Type	M/O	Description	Note
config	Object	optional	コンフィグレーション詳細はconfigを参照してください。
return	{AWS_S3}	-	{AWS_S3} : 生成された{AWS_S3}	無効なパラメータが検出された場合、.errorsが生成されます。

config

Name	Type	M/O	Description	Note
region	string	mandatory	S3バケットにアクセスする際に使用するリージョン
accessKeyId	string	mandatory	IAMアクセスキーID
secretKey	string	mandatory	IAMシークレットアクセスキー
bucket	string	mandatory	S3バケット名
ca	string	mandatory	AWS S3のルートCA証明書 PEM形式の文字列を指定します。改行コードには`\n`を使用します。
httpTimeout	number	optional	HTTPリクエストのタイムアウト値[秒] `0`の場合、タイムアウト機能無効となります。デフォルト値は`0`となります。	v2.1.0+
timeout	number	-	本パラメータは無視されます。	未使用

AWS_S3インスタンス生成時に、コンフィグレーション(config)を設定します。
無効なパラメータが検出された場合、無効なキー名を含む{Error}オブジェクトの配列が.errorsプロパティとして生成されます。パラメータが正常であった場合、.errorsプロパティは削除されます。

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	無効なキーの名前
.message	string	エラーメッセージ

.setConfig(config)

AWS_S3インスタンス生成後に、コンフィグレーション(config)を設定します。
無効なパラメータが検出された場合、無効なキー名を含む{Error}オブジェクトの配列が.errorsプロパティとして生成されます。パラメータが正常であった場合、.errorsプロパティは削除されます。

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

AWS_S3インスタンス生成後に、下記セッターメソッドを使用して個別にコンフィグレーション(config)を設定可能です。
成功した場合、自身のインスタンスが返却されます。無効なパラメータが検出された場合は、{Error}が返却されます。

Setter Method	Description	Note
.setRegion(value)	`region`を設定します。
.setAccessKeyId(value)	`accessKeyId`を設定します。
.setSecretKey(value)	`secretKey`を設定します。
.setBucket(value)	`bucket`を設定します。
.setRootCA(value)	`ca`を設定します。
.setHttpTimeout(value)	`httpTimeout`を設定します。	v2.1.0+
.setRequestTimeout(value)	`timeout`を設定します。	未使用

.createXAmzHeaders(params)

AWS APIスタイルのHTTPリクエストパラメータ名を用いたパラメータリストからHTTPヘッダを生成します。

本メソッドがサポートしているリクエストパラメータは下記となります。

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

それ以外のリクエストパラメータ名が指定された場合は、無変換のまま生成されるHTTPヘッダに継承されます。
尚、bucketおよびkeyはリクエストパラメータ名として使用できません。それらは無視されます。

Name	Type	M/O	Description	Note
params	object	mandatory	パラメータリスト
return	object	-	HTTPヘッダ

下記は使用例となります。

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]])

AWS Signature v4仕様の認証ヘッダを生成します。
このメソッドは、直接HTTPSオブジェクトを用いてプログラミングする場合に活用できます。

Name	Type	M/O	Description
host	string	mandatory	HTTPホスト
path	string	mandatory	HTTPパス
method	string	mandatory	HTTPメソッド
bodyToHash	string	optional	HTTPボディ `Signed payload`オプションを適用する場合に指定します。指定がない場合(デフォルト)は、`Unsigned payload`オプションが適用されます。
additionalHeaders	object	optional	追加`x-amz-`ヘッダ `x-amz-`ヘッダを追加指定可能です。
return	object	-	認証ヘッダ `{ Authorization: <auth>, x-amz-content-sha256: <contenthash>, x-amz-date: <timestamp>}`

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

PUTリクエストでS3バケットにデータを送信します。

ホストは${conig.bucket}.s3.amazonaws.comとなります。
尚、認証ヘッダは本メソッド内で生成され、Unsigned payloadオプションが適用されます。

Name	Type	M/O	Description	Note
path	string	mandatory	ターゲットリソースへのパスを指定します。
userHeaders	object	mandatory	HTTPリクエストヘッダ(`HTTP/1.1`および`x-amz-*`ヘッダ)を指定します。「Content-Length」を含める必要があります。
getBody	function	mandatory	送信データ(`body`)引き取り時にコールバック処理を実行します。データがなくなるまで、4KB以下の`string`もしくは`ArrayBuffer`チャンクでデータを渡し、最後に`null`を渡します。
callback(err, resp)	function	mandatory	処理完了時にコールバック処理を実行します。コールバック関数の引数で処理結果を通知します。 err: {HttpReqError}, null resp: {HttpResponse}, null HTTPリクエストでエラーが発生した場合は`err`、HTTPレスポンスが受信できた場合は`resp`が設定されます。
sockTo	number	optional	HTTPセッションのタイムアウト値[ms]を指定します。本パラメータは`https.request()`メソッドの`sockTo`設定値となります。詳しくはHTTPSオブジェクト仕様を参照してください。	v2.1.0+
return	undefined	-

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

GETリクエストでS3バケットからデータを取得します。

ホストは${conig.bucket}.s3.amazonaws.comとなります。
尚、認証ヘッダは本メソッド内で生成され、Unsigned payloadオプションが適用されます。

Name	Type	M/O	Description	Note
path	string	mandatory	ターゲットリソースへのパスを指定します。
callback(err, resp)	function	mandatory	HTTPレスポンスイベント発生時にコールバック処理を実行します。 err: {HttpReqError}, null resp: {HttpResponse}, null HTTPリクエストでエラーが発生した場合は`err`が設定され、処理終了となります。HTTPレスポンスが受信できた場合は`resp`が設定されます。HTTPレスポンスデータは、複数回のコールバックで分割通知されます。処理終了はHTTPレスポンス通知完了フラグで判断します。
isBin	boolean	optional	HTTPレスポンスデータ(`resp`)の型を指定します。 true: ArrayBuffer false: string デフォルト値は`false`となります。	v2.1.0+
sockTo	number	optional	HTTPセッションのタイムアウト値[ms]を指定します。本パラメータは`https.request()`メソッドの`sockTo`設定値となります。詳しくはHTTPSオブジェクト仕様を参照してください。	v2.1.0+
return	undefined	-

.abortRequest()

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

Name	Type	M/O	Description	Note
return	undefined	-

{HttpReqError}

Name	Type	Description	Note
.errCode	number	HTTPSリクエストのエラーコード詳しくはHTTPSオブジェクトのエラーコード表を参照してください。

{HttpResponse}

Name	Type	Description	Note
.statusCode	number	HTTPレスポンスのステータスコード
.statusMessage	string	HTTPレスポンスのステータスメッセージ
.body	string, null	HTTPレスポンスデータ (`Response-Body`) HTTPレスポンス内容やHTTP受信タイミングによって、`null`(添付データなし)となる場合があります。
.endFlag	boolean	HTTPレスポンス通知完了フラグ .put()メソッド場合、一括通知となるため、本フラグは常に`true`となります。 .get()メソッドの場合、HTTPレスポンスデータは、複数回のコールバックで分割通知されます。本フラグが`true`となるまで、レスポンスデータの取り込みを行います。 true: 通知完了(処理終了) false: 未完了。次のコールバックを待ちます。	v2.1.0+

Usage Examples

すべてのサンプルコードにおいて、以下の共通コードを使用します。

ルートCA証明書がS3エンドポイントに対して適切であることを事前に確認してください。
CA証明書の取得方法については、こちらを参考にしてください。

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

S3バケットにデータを送信します。

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

カスタムタグとACLパラメータを加えて、S3バケットにデータを送信します。

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

S3バケットにデータを分割送信します。

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

S3バケットからデータを取得します。

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");

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

Updated: 2024-03-26

NEQTO Apps

ハードウェア仕様

ソフトウェア仕様

neqto.js

ハードウェア仕様

ソフトウェア仕様

neqto.js

ハードウェア仕様

ソフトウェア仕様

neqto.js

ソフトウェア仕様

neqto.js

UART

I2C

Utils

Integration

関連資料

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