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 |
関連資料
このライブラリで使用しているAWS S3 APIの詳細については、ドキュメンテーションを参照してください。
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 1: 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);