[AWS SDK for JavaScript V3 API リファレンスガイド](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)では、 AWS SDK for JavaScript バージョン3 (V3) のすべての API オペレーションについて詳しく説明します。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# のバージョン 2.x から 3.x への移行 AWS SDK for JavaScript
AWS SDK for JavaScript バージョン 3 はバージョン 2 の大幅な書き換えです。このセクションでは、2 つのバージョンの相違点と、SDK for JavaScript のバージョン 2 からバージョン 3 に移行する方法について説明します。
## codemod を使用してコードを SDK for JavaScript v3 に移行する
AWS SDK for JavaScript バージョン 3 (v3) には、認証情報、Amazon S3 マルチパートアップロード、DynamoDB ドキュメントクライアント、ウェーターなど、クライアント設定とユーティリティ用のモダナイズされたインターフェイスが付属しています。v2 で何が変更されたか、および各変更の v3 に相当するものについては、[AWS SDK for JavaScript GitHub リポジトリの移行ガイド](https://github.com/aws/aws-sdk-js-v3/blob/main/UPGRADING.md)を参照してください。
v3 AWS SDK for JavaScript を最大限に活用するには、以下で説明する codemod スクリプトを使用することをお勧めします。
### codemod を使用して既存の v2 コードを移行する
[aws-sdk-js-codemod](https://www.npmjs.com/package/aws-sdk-js-codemod) の codemod スクリプトのコレクションは、既存の AWS SDK for JavaScript (v2) アプリケーションを v3 APIs を使用するように移行するのに役立ちます。次のように変換を実行できます。
```
$ npx aws-sdk-js-codemod -t v2-to-v3 PATH...
```
例えば、v2 から Amazon DynamoDB クライアントを作成し、`listTables` オペレーションを呼び出す次のコードがあるとします。
```
// example.ts
import AWS from "aws-sdk";
const region = "us-west-2";
const client = new AWS.DynamoDB({ region });
await client.listTables({}).promise()
.then(console.log)
.catch(console.error);
```
`example.ts` に対する `v2-to-v3` 変換は次のように実行できます。
```
$ npx aws-sdk-js-codemod -t v2-to-v3 example.ts
```
次のように、DynamoDB インポートを v3 に変換し、v3 クライアントを作成して、`listTables` オペレーションを呼び出します。
```
// example.ts
import { DynamoDB } from "@aws-sdk/client-dynamodb";
const region = "us-west-2";
const client = new DynamoDB({ region });
await client.listTables({})
.then(console.log)
.catch(console.error);
```
一般的なユースケースの変換を実装しました。コードが正しく変換されない場合は、入力コードの例と確認された/期待される出力コードを含む[バグレポート](https://github.com/awslabs/aws-sdk-js-codemod/issues/new?assignees=&labels=bug%2Ctriage&template=bug_report.yml&title=%5BBug%3F%5D%3A+)または[機能リクエスト](https://github.com/awslabs/aws-sdk-js-codemod/issues/new?assignees=&labels=enhancement&template=feature_request.yml&title=%5BFeature%5D%3A+)を作成してください。特定のユースケースが[既存の問題](https://github.com/awslabs/aws-sdk-js-codemod/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)ですでに報告されている場合は、賛成票を投じて支持を示してください。
## バージョン 3 の新機能とは
SDK for JavaScript (v3) のバージョン3 には、以下の新機能が含まれています。
モジュール化されたパッケージ
ユーザーは、サービスごとに個別のパッケージを使用できます。
新しいミドルウェアスタック
ユーザーはミドルウェアスタックを使用して、オペレーション呼び出しのライフサイクルを制御できます。
さらに、SDKはTypeScriptで記述されており、静的型付けなどの多くの利点があります。
**重要**
このガイドの v3 のコード例は、ECMAScript 6 (ES6) で記述されています。ES6 は、コードをよりモダンで読みやすくし、より多くのことをおこなうための新しい構文と新機能を提供します。ES6 では Node.js バージョン 13.x 以降を使用する必要があります。Node.js の最新バージョンをダウンロードしてインストールするには、[Node.js downloads.](https://nodejs.org/en/download/)を参照してください。詳細については、「[JavaScript ES6/CommonJS 構文](sdk-example-javascript-syntax.md)」を参照してください。
## モジュール化されたパッケージ
SDK for JavaScript (v2) のバージョン 2 では、次のように AWS SDK 全体を使用する必要があります。
```
var AWS = require("aws-sdk");
```
アプリケーションが多くの AWS サービスを使用している場合、SDK 全体をロードすることは問題ではありません。ただし、少数のサービスのみを使用する必要がある場合は AWS 、不要または使用しないコードでアプリケーションのサイズを増やすことを意味します。
v3 では、必要な個々の AWS サービスをロードして使用できます。これを次の例に示します。これにより、Amazon DynamoDB（DynamoDB）にアクセスできます。
```
import { DynamoDB } from "@aws-sdk/client-dynamodb";
```
個々の AWS サービスをロードして使用できるだけでなく、必要なサービスコマンドのみをロードして使用することもできます。これを次の例でDynamoDB クライアントと`ListTablesCommand`コマンドにアクセスできることを示しています。
```
import {
DynamoDBClient,
ListTablesCommand
} from "@aws-sdk/client-dynamodb";
```
**重要**
サブモジュールをモジュールにインポートしないでください。例えば、次のコードはエラーになる可能性があります。
```
import { CognitoIdentity } from "@aws-sdk/client-cognito-identity/CognitoIdentity";
```
正しいコードは、次のとおりです。
```
import { CognitoIdentity } from "@aws-sdk/client-cognito-identity";
```
### コードサイズの比較
バージョン 2 (v2) では、`us-west-2` リージョン内のすべての Amazon DynamoDB テーブルを一覧表示する簡単なコード例は次のようになります。
```
var AWS = require("aws-sdk");
// Set the Region
AWS.config.update({ region: "us-west-2" });
// Create DynamoDB service object
var ddb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
// Call DynamoDB to retrieve the list of tables
ddb.listTables({ Limit: 10 }, function (err, data) {
if (err) {
console.log("Error", err.code);
} else {
console.log("Tables names are ", data.TableNames);
}
});
```
v3 では次のようになります。
```
import {
DynamoDBClient,
ListTablesCommand
} from "@aws-sdk/client-dynamodb";
const dbclient = new DynamoDBClient({ region: "us-west-2" });
try {
const results = await dbclient.send(new ListTablesCommand);
for (const item of results.TableNames) {
console.log(item);
}
} catch (err) {
console.error(err)
}
```
`aws-sdk`のパッケージは、アプリケーションに約40MBを追加します。`var AWS = require("aws-sdk")`を`import {DynamoDB} from "@aws-sdk/client-dynamodb"`に置き換えることで、そのオーバーヘッドを約 3 MB に削減します。インポートを DynamoDB クライアントと`ListTablesCommand`のコマンドだけに限定することで、オーバーヘッドを 100 KB 以下に削減します。
```
// Load the DynamoDB client and ListTablesCommand command for Node.js
import {
DynamoDBClient,
ListTablesCommand
} from "@aws-sdk/client-dynamodb";
const dbclient = new DynamoDBClient({});
```
### v3 でのコマンドの呼び出し
v2 または v3 コマンドを使用して v3 でオペレーションを実行できます。v3 コマンドを使用するには、コマンドと必要な AWS サービスパッケージクライアントをインポートし、非同期/待機パターンを使用して `.send`メソッドを使用して コマンドを実行します。
v2 コマンドを使用するには、必要な AWS サービスパッケージをインポートし、コールバックまたは非同期/待機パターンを使用してパッケージ内で v2 コマンドを直接実行します。
#### v3 コマンドの使用
v3 には、 AWS サービスパッケージごとに一連のコマンドが用意されており、その AWS サービスのオペレーションを実行できます。 AWS のサービスをインストールした後、`node-modules/@aws-sdk/client-PACKAGE_NAME/commands folder.`のプロジェクトで利用可能なコマンドを参照できます。
使用したいコマンドをインポートする必要があります。例えば、次のコードは DynamoDB サービスおよび`CreateTableCommand`のコマンドをロードします。
```
import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
```
これらのコマンドを推奨の非同期/待機パターンで呼び出すには、次の構文を使用します。
```
CLIENT.send(new XXXCommand);
```
例えば、次の例では、推奨される非同期/待機 パターンを使用して DynamoDB テーブルを作成します。
```
import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const dynamodb = new DynamoDB({ region: "us-west-2" });
const tableParams = {
TableName: TABLE_NAME
};
try {
const data = await dynamodb.send(new CreateTableCommand(tableParams));
console.log("Success", data);
} catch (err) {
console.log("Error", err);
};
```
#### v2 コマンドの使用
SDK for JavaScript で v2 コマンドを使用するには、次のコードに示すように、完全な AWS サービスパッケージをインポートします。
```
const { DynamoDB } = require('@aws-sdk/client-dynamodb');
```
推奨される非同期/待機パターンで v2 コマンドを呼び出すには、次の構文を使用します。
```
client.command(parameters);
```
次の例では v2 の `createTable` コマンドで、推奨される非同期/待機パターンを使用して DynamoDB テーブルを作成します。
```
const { DynamoDB } = require('@aws-sdk/client-dynamodb');
const dynamoDB = new DynamoDB({ region: 'us-west-2' });
var tableParams = {
TableName: TABLE_NAME
};
async function run() => {
try {
const data = await dynamoDB.createTable(tableParams);
console.log("Success", data);
}
catch (err) {
console.log("Error", err);
}
};
run();
```
次の例では v2 の `createBucket` コマンドで、コールバックパターンを使用して Amazon S3 バケットを作成します。
```
const { S3 } = require('@aws-sdk/client-s3');
const s3 = new S3({ region: 'us-west-2' });
var bucketParams = {
Bucket : BUCKET_NAME
};
function run() {
s3.createBucket(bucketParams, function (err, data) {
if (err) {
console.log("Error", err);
} else {
console.log("Success", data.Location);
}
})
};
run();
```
## 新しいミドルウェアスタック
SDK の v2 では、イベントリスナーをリクエストに添付することで、ライフサイクルの複数のステージを介してリクエストを変更できるようになりました。このアプローチでは、リクエストのライフサイクル中に問題が発生したことをデバッグすることが困難になる可能性があります。
v3 では、新しいミドルウェアスタックを使用して、オペレーション呼び出しのライフサイクルを制御できます。このアプローチには、いくつかの利点があります。スタック内の各ミドルウェアステージは、リクエストオブジェクトに変更を加えた後、次のミドルウェアステージを呼び出します。また、エラーに至るまでのミドルウェアステージが呼び出されたかを正確に確認できるため、スタック内の問題のデバッグがはるかに簡単になります。
次の例では、ミドルウェアを使用して (先ほど作成して示した) Amazon DynamoDB クライアントにカスタムヘッダーを追加します。最初の引数は呼び出すスタックの次のミドルウエアステージである`next`を受け入れる関数と、呼び出され操作に関する情報を含むオブジェクトである`context`を受け入れる関数です。この関数は、操作とリクエストに渡されるパラメータを含むオブジェクトの`args`を受け入れる関数を返します。次のミドルウェアを`args`で呼び出した結果を返します
```
dbclient.middlewareStack.add(
(next, context) => args => {
args.request.headers["Custom-Header"] = "value";
return next(args);
},
{
name: "my-middleware",
override: true,
step: "build"
}
);
dbclient.send(new PutObjectCommand(params));
```
# AWS SDK for JavaScript v2 と v3 の相違点
このセクションでは、AWS SDK for JavaScript v2 から v3 への重要な変更点をまとめています。v3 は v2 をモジュール化して再構築しているため、v2 と v3 ではいくつかの基本概念が異なります。これらの変更点については、[ブログ記事](https://aws.amazon.com/blogs/developer/category/developer-tools/aws-sdk-for-javascript-in-node-js/)で確認できます。次のブログ記事を読むことで、必要な知識を短時間で習得できます。
+ [Modular packages in AWS SDK for JavaScript](https://aws.amazon.com/blogs/developer/modular-packages-in-aws-sdk-for-javascript/)
+ [Introducing Middleware Stack in Modular AWS SDK for JavaScript](https://aws.amazon.com/blogs/developer/middleware-stack-modular-aws-sdk-js/)
AWS SDK for JavaScript v2 から v3 へのインターフェイスの変更の概要を以下に示します。目標は、既に使い慣れている v2 の API と同等の機能を v3 で簡単に見つけられるようにすることです。
**Topics**
+ [
# クライアントコンストラクタ
](migrate-client-constructors.md)
+ [
# 認証情報プロバイダー
](migrate-credential-providers.md)
+ [
# Amazon S3 に関する考慮事項
](migrate-s3.md)
+ [
# DynamoDB ドキュメントクライアント
](migrate-dynamodb-doc-client.md)
+ [
# ウェイターと署名機能
](migrate-waiters-signers.md)
+ [
# 特定のサービスクライアントに関する注意事項
](migrate-service-client-notes.md)
# クライアントコンストラクタ
このリストは [v2 設定パラメータ](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html)によってインデックス化されています。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#computeChecksums-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#computeChecksums-property)
+ **v2**: サービスが対応している場合に、ペイロード本文の MD5 チェックサムを計算するかどうか (現在 S3 でのみサポートされています)。
+ **v3**: S3 の該当するコマンド (PutObject、PutBucketCors など) は、リクエストペイロードの MD5 チェックサムを自動的に計算します。コマンドの `ChecksumAlgorithm` パラメータで別のチェックサムアルゴリズムを指定して、異なるチェックサムアルゴリズムを使用することもできます。詳細については、[S3 の機能に関する発表](https://aws.amazon.com/blogs/aws/new-additional-checksum-algorithms-for-amazon-s3/)を参照してください。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#convertResponseTypes-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#convertResponseTypes-property)
+ **v2**: レスポンスデータを解析するときに型が変換されるかどうか。
+ **v3**: **廃止**。このオプションは、JSON レスポンスのタイムスタンプや base64 バイナリなどの型を変換しないため、型安全ではないと見なされます。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#correctClockSkew-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#correctClockSkew-property)
+ **v2**: クライアントのクロックスキューが原因で失敗したクロックスキュー修正リクエストと再試行リクエストを適用するかどうか。
+ **v3**: **廃止**。SDK は*常に*クロックスキュー修正を適用します。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#systemClockOffset-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#systemClockOffset-property)
+ **v2**: すべての署名時刻に適用するミリ秒単位のオフセット値。
+ **v3**: 変更なし。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#credentials-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#credentials-property)
+ **v2**: リクエストに署名するための AWS 認証情報。
+ **v3**: 変更なし。また、認証情報を返す非同期関数を指定することもできます。関数が `expiration (Date)` を返す場合、有効期限の日時が近づくと関数が再度呼び出されます。[v3 API リファレンスの `AwsAuthInputConfig` 認証情報](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-signing/Interface/AwsAuthInputConfig/)の説明を参照してください。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointCacheSize-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointCacheSize-property)
+ **v2**: エンドポイント検出オペレーションで検出されたエンドポイントを保存するグローバルキャッシュのサイズ。
+ **v3**: 変更なし。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointDiscoveryEnabled-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointDiscoveryEnabled-property)
+ **v2**: サービスによって指定されたエンドポイントを使用してオペレーションを動的に呼び出すかどうか。
+ **v3**: 変更なし。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#hostPrefixEnabled-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#hostPrefixEnabled-property)
+ **v2**: リクエストパラメータをホスト名のプレフィックスにマーシャリングするかどうか。
+ **v3**: **廃止**。SDK は、必要に応じて*常に*ホスト名プレフィックスを挿入します。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#httpOptions-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#httpOptions-property)
低レベルの HTTP リクエストに渡す一連のオプション。これらのオプションは v3 では異なる方法で集計されます。新しい `requestHandler` を指定することで設定できます。Node.js ランタイムで http オプションを設定する例を次に示します。詳細については、[v3 API リファレンスのNodeHttpHandler](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/)の説明を参照してください。
すべての v3 リクエストはデフォルトで HTTPS を使用します。カスタム httpsAgent のみを指定する必要があります。
```
const { Agent } = require("https");
const { Agent: HttpAgent } = require("http");
const { NodeHttpHandler } = require("@smithy/node-http-handler");
const dynamodbClient = new DynamoDBClient({
requestHandler: new NodeHttpHandler({
httpsAgent: new Agent({
/*params*/
}),
connectionTimeout: /*number in milliseconds*/,
socketTimeout: /*number in milliseconds*/
}),
});
```
http を使用するカスタムエンドポイントを渡す場合は、httpAgent を指定する必要があります。
```
const { Agent } = require("http");
const { NodeHttpHandler } = require("@smithy/node-http-handler");
const dynamodbClient = new DynamoDBClient({
requestHandler: new NodeHttpHandler({
httpAgent: new Agent({
/*params*/
}),
}),
endpoint: "http://example.com",
});
```
クライアントがブラウザで実行されている場合、別のオプションセットを使用できます。詳細については、[v3 API リファレンスのFetchHttpHandler](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-fetch-http-handler/)の説明を参照してください。
```
const { FetchHttpHandler } = require("@smithy/fetch-http-handler");
const dynamodbClient = new DynamoDBClient({
requestHandler: new FetchHttpHandler({
requestTimeout: /* number in milliseconds */
}),
});
```
`httpOptions` の各オプションを以下に示します。
+ `proxy`
+ **v2**: リクエストをプロキシ経由で送信するための URL。
+ **v3**: [Node.js のプロキシの設定](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-configuring-proxies.html)に従って、 エージェントでプロキシを設定できます。
+ `agent`
+ **v2**: HTTP リクエストを実行するエージェントオブジェクト。接続プーリング用に使用されます。
+ **v3**: 上記の例に示すように、`httpAgent` または `httpsAgent` を設定できます。
+ `connectTimeout`
+ **v2**: `connectTimeout` ミリ秒以内にサーバーとの接続を確立できなかった場合、ソケットをタイムアウトするよう設定します。
+ **v3**: `connectionTimeout` は [`NodeHttpHandler` オプション](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/)で使用できます。
+ `timeout`
+ **v2**: リクエストが自動的に終了するまでにかかるミリ秒数。
+ **v3**: `socketTimeout` は [`NodeHttpHandler` オプション](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-node-http-handler/)で使用できます。
+ `xhrAsync`
+ **v2**: SDK が非同期 HTTP リクエストを送信するかどうか。
+ **v3**: **廃止**。リクエストは*常に*非同期です。
+ `xhrWithCredentials`
+ **v2**: XMLHttpRequest オブジェクトの「withCredentials」プロパティを設定します。
+ **v3**: 利用できません。SDK は[デフォルトのフェッチ設定](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)を継承します。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#logger-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#logger-property)
+ **v2**: リクエストに関する情報をログに記録するために、`.write()` (ストリームなど) または `.log()` (コンソールオブジェクトなど) に応答するオブジェクト。
+ **v3**: 変更なし。v3 では、より詳細なログを利用できます。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRedirects-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRedirects-property)
+ **v2**: サービスリクエストで従うリダイレクトの最大回数。
+ **v3**: **廃止**。SDK は、意図しないクロスリージョンリクエストを回避するために、リダイレクトに従い*ません*。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRetries-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRetries-property)
+ **v2**: サービスリクエストに対して実行する再試行の最大回数。
+ **v3**: `maxAttempts` に変更されました。詳細については、[v3 API リファレンスの RetryInputConfig](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-middleware-retry/Interface/RetryInputConfig/) の説明を参照してください。`maxAttempts` は `maxRetries + 1` である必要があります。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#paramValidation-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#paramValidation-property)
+ **v2**: リクエストを送信する前に、入力パラメータをオペレーションの説明に対して検証するかどうか。
+ **v3**: **廃止**。SDK は、実行時にクライアント側で検証を*行いません*。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#region-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#region-property)
+ **v2**: サービスリクエストの送信先のリージョン。
+ **v3**: 変更なし。また、リージョン文字列を返す非同期関数を指定することもできます。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#retryDelayOptions-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#retryDelayOptions-property)
+ **v2**: 再試行可能なエラーが発生した際に再試行までの遅延を設定するための一連のオプション。
+ **v3**: **廃止**。SDK は、`retryStrategy` クライアントコンストラクタオプションを使用して、より柔軟な再試行戦略をサポートします。詳細については、「[v3 API リファレンス](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-util-retry/)」を参照してください。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3BucketEndpoint-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3BucketEndpoint-property)
+ **v2**: 指定されたエンドポイントが個々のバケットを対象としているかどうか (ルート API エンドポイントを対象としている場合は失敗)。
+ **v3**: `bucketEndpoint` に変更されました。詳細については、[v3 API リファレンスのbucketEndpoint](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-bucket-endpoint/Interface/BucketEndpointInputConfig/)の説明を参照してください。`true` に設定し、リクエストパラメータで `Bucket` リクエストエンドポイントを指定すると、元のエンドポイントは上書きされることに注意してください。v2 では、クライアントコンストラクタのリクエストエンドポイントが `Bucket` リクエストパラメータを上書きします。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3DisableBodySigning-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3DisableBodySigning-property)
+ **v2**: 署名バージョン v4 の使用時に、S3 本文署名を無効にするかどうか。
+ **v3**: `applyChecksum` に名前が変更されました。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3ForcePathStyle-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3ForcePathStyle-property)
+ **v2**: S3 オブジェクトのパススタイルの URL を強制するかどうか。
+ **v3**: `forcePathStyle` に名前が変更されました。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UseArnRegion-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UseArnRegion-property)
+ **v2**: リクエストされたリソースの ARN から推測されたリージョンでリクエストリージョンを上書きするかどうか。
+ **v3**: `useArnRegion` に名前が変更されました。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UsEast1RegionalEndpoint-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UsEast1RegionalEndpoint-property)
+ **v2**: region が「us-east-1」に設定されている場合、s3 リクエストをグローバルエンドポイントに送信するか、「us-east-1」リージョンエンドポイントに送信するか。
+ **v3**: **廃止**。リージョンが `us-east-1` に設定されている場合、S3 クライアントは常にリージョンエンドポイントを使用します。リージョンを `aws-global` に設定することで、S3 グローバルエンドポイントにリクエストを送信できます。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureCache-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureCache-property)
+ **v2**: リクエストに使用するする署名 (API の設定を上書き) がキャッシュされるかどうか。
+ **v3**: **廃止**。SDK *は常に*ハッシュされた署名キーをキャッシュします。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureVersion-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureVersion-property)
+ **v2**: リクエストに使用する署名のバージョン (API の設定を上書き)。
+ **v3**: **廃止**。v2 SDK でサポートされている署名 V2 は によって廃止されました AWS。 v3 は署名 v4 *のみ*をサポートしています。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#sslEnabled-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#sslEnabled-property)
+ **v2**: SSL がリクエストに対して有効になっているかどうか。
+ **v3**: `tls` に名前が変更されました。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#stsRegionalEndpoints-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#stsRegionalEndpoints-property)
+ **v2**: sts リクエストをグローバルエンドポイントに送信するか、リージョンエンドポイントに送信するか。
+ **v3**: **廃止**。STS クライアントは、特定のリージョンに設定されている場合、*常に*リージョンエンドポイントを使用します。リージョンを `aws-global` に設定することで、STS グローバルエンドポイントにリクエストを送信できます。
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#useAccelerateEndpoint-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#useAccelerateEndpoint-property)
+ **v2**: S3 サービスで Accelerate エンドポイントを使用するかどうか。
+ **v3**: 変更なし。
# 認証情報プロバイダー
v2 は、SDK for JavaScript は、選択できる認証情報プロバイダーのリストと、Node.js でデフォルトで利用可能な認証情報プロバイダーチェーンを提供します。これにより、最も一般的なすべてのプロバイダーから AWS 認証情報の読み込みが試行されます。SDK for JavaScript v3 では、認証情報プロバイダーのインターフェイスが簡素化され、カスタム認証情報プロバイダーの利用と作成が容易になりました。新しい認証情報プロバイダーチェーンに加えて、SDK for JavaScript v3 でも、v2 と同等の機能を提供することを目的として、認証情報プロバイダーのリストが用意されています。
v2 のすべての認証情報プロバイダーと、それに相当する v3 の認証情報プロバイダーは次のとおりです。
## デフォルトの認証情報プロバイダー
デフォルトの認証情報プロバイダーは、明示的に指定*しない場合*に SDK for JavaScript が AWS 認証情報を解決する方法です。
+ **v2**: Node.js の [CredentialProviderChain](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CredentialProviderChain.html) は、ソースからの認証情報を次の順序で解決します。
+ [環境変数](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-environment.html)
+ [共有された認証情報ファイル](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-shared.html)
+ [ECS コンテナ認証情報](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html)
+ [外部プロセスの生成](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html)
+ [指定されたファイルからの OIDC トークン](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html)
+ [Amazon EC2 インスタンスメタデータ](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) -
上記の認証情報プロバイダーの 1 つが AWS 認証情報の解決に失敗した場合、有効な認証情報が解決されるまでチェーンは次のプロバイダーにフォールバックし、すべてのプロバイダーが失敗するとチェーンはエラーをスローします。
ブラウザおよび React Native ランタイムでは、認証情報チェーンは空であるため、認証情報を明示的に設定する必要があります。
+ **v3**: [defaultProvider](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers#fromnodejsproviderchain-1)。認証情報のソースとフォールバック順序は v3 でも*変更されません*。また、[AWS IAM アイデンティティセンター 認証情報](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html)もサポートしています。
## 一時認証情報
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/ChainableTemporaryCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/ChainableTemporaryCredentials.html) は `AWS.STS` から取得した一時的な認証情報を表します。追加のパラメータがない場合、認証情報は `AWS.STS.getSessionToken()` オペレーションから取得されます。IAM ロールが指定されている場合、`AWS.STS.assumeRole()` オペレーションは代わりにロールの認証情報を取得するために使用されます。`AWS.ChainableTemporaryCredentials` は masterCredentials や認証情報の更新の処理方法が `AWS.TemporaryCredentials` とは異なります。`AWS.ChainableTemporaryCredentials` は、STS 認証情報のチェーンをサポートするためにユーザーが渡した masterCredentials を使用して期限切れの認証情報を更新します。ただし、`AWS.TemporaryCredentials` はインスタンス化の際に masterCredentials を再帰的に解決するため、中間の一時的な認証情報を必要とする、認証情報の更新機能は除外されます。
元の [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TemporaryCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TemporaryCredentials.html) は v2 で `ChainableTemporaryCredentials` に置き換えられ、**非推奨**になりました。
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtemporarycredentials](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtemporarycredentials)。`@aws-sdk/credential-providers` パッケージから `fromTemporaryCredentials()` を呼び出すことができます。例を示します。
```
import { FooClient } from "@aws-sdk/client-foo";
import { fromTemporaryCredentials } from "@aws-sdk/credential-providers"; // ES6 import
// const { FooClient } = require("@aws-sdk/client-foo");
// const { fromTemporaryCredentials } = require("@aws-sdk/credential-providers"); // CommonJS import
const sourceCredentials = {
// A credential can be a credential object or an async function that returns a credential object
};
const client = new FooClient({
credentials: fromTemporaryCredentials({
masterCredentials: sourceCredentials,
params: { RoleArn },
}),
});
```
## Amazon Cognito ID の認証情報
通常ブラウザで使用される Amazon Cognito ID サービスから認証情報を読み込みます。
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html) Amazon Cognito ID サービスを使用して STS ウェブ ID フェデレーションから取得した認証情報を表します。
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) [`@aws/credential-providers` パッケージ](https://www.npmjs.com/package/@aws-sdk/credential-providers)には 2 つの認証情報プロバイダー関数が用意されています。1 つ目の [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) はアイデンティティ ID を受け取り、`cognitoIdentity:GetCredentialsForIdentity` を呼び出し、もう 1 つの [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html) は アイデンティティプール ID を受け取り、最初の呼び出しで `cognitoIdentity:GetId` を呼び出した後、`fromCognitoIdentity` を呼び出します。2 回目以降の呼び出しでは GetId は再び呼び出されません。
このプロバイダーは、「[Amazon Cognito デベロッパーガイド](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html)」で説明されている「簡易フロー」を実装します。`cognito:GetOpenIdToken` を呼び出した後、`sts:AssumeRoleWithWebIdentity` を呼び出す「クラシックフロー」は*サポートされていません*。必要な場合は、「[機能リクエスト](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=)」でお知らせください。
```
// fromCognitoIdentityPool example
import { fromCognitoIdentityPool } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromCognitoIdentityPool } = require("@aws-sdk/credential-providers"); // CommonJS import
const client = new FooClient({
region: "us-east-1",
credentials: fromCognitoIdentityPool({
clientConfig: cognitoIdentityClientConfig, // Optional
identityPoolId: "us-east-1:1699ebc0-7900-4099-b910-2df94f52a030",
customRoleArn: "arn:aws:iam::1234567890:role/MYAPP-CognitoIdentity", // Optional
logins: {
// Optional
"graph.facebook.com": "FBTOKEN",
"www.amazon.com": "AMAZONTOKEN",
"api.twitter.com": "TWITTERTOKEN",
},
}),
});
```
```
// fromCognitoIdentity example
import { fromCognitoIdentity } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromCognitoIdentity } = require("@aws-sdk/credential-provider-cognito-identity"); // CommonJS import
const client = new FooClient({
region: "us-east-1",
credentials: fromCognitoIdentity({
clientConfig: cognitoIdentityClientConfig, // Optional
identityId: "us-east-1:128d0a74-c82f-4553-916d-90053e4a8b0f",
customRoleArn: "arn:aws:iam::1234567890:role/MYAPP-CognitoIdentity", // Optional
logins: {
// Optional
"graph.facebook.com": "FBTOKEN",
"www.amazon.com": "AMAZONTOKEN",
"api.twitter.com": "TWITTERTOKEN",
},
}),
});
```
## Amazon EC2 メタデータ (IMDS) 認証情報
Amazon EC2 インスタンスのメタデータサービスから受信した認証情報を表します。
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html)
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata)。Amazon EC2 インスタンスメタデータサービスから認証情報を取得する認証情報プロバイダーを作成します。
```
import { fromInstanceMetadata } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromInstanceMetadata } = require("@aws-sdk/credential-providers"); // CommonJS import
const client = new FooClient({
credentials: fromInstanceMetadata({
maxRetries: 3, // Optional
timeout: 0, // Optional
}),
});
```
## Amazon ECS 認証情報
指定された URL から受信した認証情報を表します。このプロバイダーは、`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` または `AWS_CONTAINER_CREDENTIALS_FULL_URI` の環境変数で指定された URI から一時的な認証情報をリクエストします。
+ **v2**: `ECSCredentials` または [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RemoteCredentials.html)
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata)。Amazon ECS コンテナメタデータサービスから認証情報を取得する認証情報プロバイダーを作成します。
```
import { fromContainerMetadata } from "@aws-sdk/credential-providers"; // ES6 import
const client = new FooClient({
credentials: fromContainerMetadata({
maxRetries: 3, // Optional
timeout: 0, // Optional
}),
});
```
## ファイルシステムの認証情報
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/FileSystemCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/FileSystemCredentials.html)。ディスク上の JSON ファイルからの認証情報を表します。
+ **v3**: **廃止**。JSON ファイルを明示的に読み取り、クライアントに提供します。必要な場合は、「[機能リクエスト](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=)」でお知らせください。
## SAML 認証情報プロバイダー
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SAMLCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SAMLCredentials.html) SAML サポートから取得した認証情報を表します。
+ **v3**: **利用できません**。必要な場合は、「[機能リクエスト](https://github.com/aws/aws-sdk-js-v3/issues/new?assignees=&labels=feature-request&template=---feature-request.md&title=)」でお知らせください。
## 共有された認証情報ファイルの認証情報
共有された認証情報ファイルから認証情報を読み取ります (デフォルトは `~/.aws/credentials` または `AWS_SHARED_CREDENTIALS_FILE` 環境変数で定義)。このファイルは、さまざまな AWS SDKsとツールでサポートされています。詳細については、[共有設定および認証情報ファイルのドキュメント](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html)を参照してください。
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SharedIniFileCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SharedIniFileCredentials.html)
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_credential_providers.html)
```
import { fromIni } from "@aws-sdk/credential-providers";
// const { fromIni } from("@aws-sdk/credential-providers");
const client = new FooClient({
credentials: fromIni({
configFilepath: "~/.aws/config", // Optional
filepath: "~/.aws/credentials", // Optional
mfaCodeProvider: async (mfaSerial) => {
// implement a pop-up asking for MFA code
return "some_code";
}, // Optional
profile: "default", // Optional
clientConfig: { region }, // Optional
}),
});
```
## ウェブ ID 認証情報
ディスク上のファイルから OIDC トークンを使用して認証情報を取得します。Amazon EKS で一般的に使用されます。
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/TokenFileWebIdentityCredentials.html)
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtokenfile](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromtokenfile)
```
import { fromTokenFile } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromTokenFile } from("@aws-sdk/credential-providers"); // CommonJS import
const client = new FooClient({
credentials: fromTokenFile({
// Optional. If skipped, read from `AWS_ROLE_ARN` environmental variable
roleArn: "arn:xxxx",
// Optional. If skipped, read from `AWS_ROLE_SESSION_NAME` environmental variable
roleSessionName: "session:a",
// Optional. STS client config to make the assume role request.
clientConfig: { region },
}),
});
```
## ウェブ ID フェデレーション認証情報
STS ウェブ ID フェデレーションサポートから認証情報を取得します。
+ **v2**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/WebIdentityCredentials.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/WebIdentityCredentials.html)
+ **v3**: [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromwebtoken](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromwebtoken)
```
import { fromWebToken } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromWebToken } from("@aws-sdk/credential-providers"); // CommonJS import
const client = new FooClient({
credentials: fromWebToken({
// Optional. If skipped, read from `AWS_ROLE_ARN` environmental variable
roleArn: "arn:xxxx",
// Optional. If skipped, read from `AWS_ROLE_SESSION_NAME` environmental variable
roleSessionName: "session:a",
// Optional. STS client config to make the assume role request.
clientConfig: { region },
}),
});
```
# Amazon S3 に関する考慮事項
## Amazon S3 マルチパートアップロード
v2 では、Amazon S3 クライアントには、[Amazon S3 が提供するマルチパートアップロード機能](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html)を使用した、ラージオブジェクトのアップロードをサポートする [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#upload-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#upload-property) オペレーションが含まれています。
v3 では、[https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-storage](https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-storage) パッケージを使用できます。これは、v2 の `upload()` オペレーションで提供されるすべての機能をサポートし、Node.js ランタイムとブラウザランタイムの両方をサポートします。
## Amazon S3 の署名付き URL
v2 では、Amazon S3 クライアントには、ユーザーが Amazon S3 からオブジェクトをアップロードまたはダウンロードするために使用できる URL を生成する [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrl-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrl-property) および [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrlPromise-property](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrlPromise-property) オペレーションが含まれています。
v3 では、[https://github.com/aws/aws-sdk-js-v3/tree/main/packages/s3-request-presigner](https://github.com/aws/aws-sdk-js-v3/tree/main/packages/s3-request-presigner) パッケージを使用できます。このパッケージには、`getSignedUrl()` オペレーションと ` getSignedUrlPromise()` オペレーションの両方の関数が含まれています。この[ブログ記事](https://aws.amazon.com/blogs/developer/generate-presigned-url-modular-aws-sdk-javascript/)では、このパッケージの詳細について説明します。
## Amazon S3 リージョンリダイレクト
誤ったリージョンが Amazon S3 クライアントに渡され、後続の ` PermanentRedirect` (ステータス 301) エラーがスローされた場合、v3 の Amazon S3 クライアントはリージョンリダイレクト (v2 の旧 Amazon S3 グローバルクライアント) をサポートします。クライアント設定で [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-sdk-s3/Interface/S3InputConfig/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-middleware-sdk-s3/Interface/S3InputConfig/) フラグを使用することで、Amazon S3 クライアントにリージョンリダイレクトに従うように指定し、そのグローバルクライアントとしての機能をサポートできます。
**注記**
この機能は、ステータスが 301 の `PermanentRedirect` エラーを受信すると、失敗したリクエストが修正されたリージョンで再試行されるため、レイテンシーが増加する可能性があることに注意してください。この機能は、バケットのリージョンが事前にわからない場合にのみ使用してください。
## Amazon S3 ストリーミングとバッファされたレスポンス
v3 SDK では、サイズが大きくなる可能性のあるレスポンスのバッファを避けることを優先します。これは、v2 では `Buffer` を返したが、v3 では `Stream` を返す Amazon S3 `GetObject` オペレーションでよく発生します。
Node.js では、ソケットを解放して新しいトラフィックへの接続を開いたままにするために、ストリームを消費するか、クライアントやそのリクエストハンドラーをガベージコレクションの対象にする必要があります。
```
// v2
const get = await s3.getObject({ ... }).promise(); // this buffers consumes the stream already.
```
```
// v3, consume the stream to free the socket
const get = await s3.getObject({ ... }); // object .Body has unconsumed stream
const str = await get.Body.transformToString(); // consumes the stream
// other ways to consume the stream include writing it to a file,
// passing it to another consumer like an upload, or buffering to
// a string or byte array.
```
詳細については、[ソケットの枯渇](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md#request-handler-requesthandler)に関するセクションを参照してください。
# DynamoDB ドキュメントクライアント
## v3 での DynamoDB ドキュメントクライアントの基本的な使用法
+ v2 では、[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html) クラスを使用することで、配列、数値、オブジェクトなどのネイティブ JavaScript 型を使用して DynamoDB API を呼び出すことができます。このように、DynamoDB ドキュメントクライアントは、属性値の概念を抽象化することによって Amazon DynamoDB での項目の操作を簡単にします。
+ v3 では、同等の [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_lib_dynamodb.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_lib_dynamodb.html) クライアントを使用できます。これは v3 SDK の通常のサービスクライアントに似ていますが、コンストラクタに基本的な DynamoDB クライアントが必要になる点が異なります。
例:
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; // ES6 import
// const { DynamoDBClient } = require("@aws-sdk/client-dynamodb"); // CommonJS import
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb"; // ES6 import
// const { DynamoDBDocumentClient, PutCommand } = require("@aws-sdk/lib-dynamodb"); // CommonJS import
// Bare-bones DynamoDB Client
const client = new DynamoDBClient({});
// Bare-bones document client
const ddbDocClient = DynamoDBDocumentClient.from(client); // client is DynamoDB client
await ddbDocClient.send(
new PutCommand({
TableName,
Item: {
id: "1",
content: "content from DynamoDBDocumentClient",
},
})
);
```
## マーシャリング時の `Undefined` の値
+ v2 では、オブジェクトの `undefined` 値は、DynamoDB へのマーシャリングプロセス中に自動的に省略されていました。
+ v3 では、`@aws-sdk/lib-dynamodb` のデフォルトのマーシャリング動作が変更され、`undefined` 値を持つオブジェクトは省略されなくなりました。v2 の機能に合わせて、開発者は DynamoDB ドキュメントクライアントの `marshallOptions` で明示的に `removeUndefinedValues` を `true` に設定する必要があります。
例:
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({});
// The DynamoDBDocumentClient is configured to handle undefined values properly
const ddbDocClient = DynamoDBDocumentClient.from(client, {
marshallOptions: {
removeUndefinedValues: true
}
});
await ddbDocClient.send(
new PutCommand({
TableName,
Item: {
id: "123",
content: undefined // This value will be automatically omitted.
array: [1, undefined], // The undefined value will be automatically omitted.
map: { key: undefined }, // The "key" will be automatically omitted.
set: new Set([1, undefined]), // The undefined value will be automatically omitted.
};
})
);
```
[パッケージのREADME](https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-dynamodb/README.md) には、その他の例と設定が示されています。
# ウェイターと署名機能
このページでは、AWS SDK for JavaScript v3 でのウェイターと署名機能の使用について説明します。
## ウェイター
v2 では、すべてのウェイターがサービスクライアントクラスにバインドされるため、クライアントが待機する対象の状態をウェーターの入力で指定する必要があります。例えば、新しく作成されたバケットの準備が整うまで [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#bucketExists-waiter](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#bucketExists-waiter) を呼び出して待機する必要があります。
v3 では、アプリケーションにウェイターが必要ない場合はウェイターをインポートする必要はありません。さらに、特定の状態を待機するために必要なウェイターのみをインポートできます。これによりて、バンドルのサイズを減らし、パフォーマンスを向上させることができます。作成後にバケットの準備ができるまで待機する例を次に示します。
```
import { S3Client, CreateBucketCommand, waitUntilBucketExists } from "@aws-sdk/client-s3"; // ES6 import
// const { S3Client, CreateBucketCommand, waitUntilBucketExists } = require("@aws-sdk/client-s3"); // CommonJS import
const Bucket = "BUCKET_NAME";
const client = new S3Client({ region: "REGION" });
const command = new CreateBucketCommand({ Bucket });
await client.send(command);
await waitUntilBucketExists({ client, maxWaitTime: 60 }, { Bucket });
```
ウェイターの設定方法の詳細は、[AWS SDK for JavaScript v3 のウェイターに関するブログ記事](https://aws.amazon.com/blogs/developer/waiters-in-modular-aws-sdk-for-javascript/)で確認できます。
## Amazon CloudFront の署名機能
v2 では、[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CloudFront/Signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CloudFront/Signer.html) を使用して、制限された Amazon CloudFront ディストリビューションにアクセスするリクエストに署名できます。
v3 では、[https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_cloudfront_signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_cloudfront_signer.html) パッケージに同じユーティリティが用意されています。
## Amazon RDS の署名機能
v2 では、[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDS/Signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDS/Signer.html) を使用して、Amazon RDS データベース用の認証トークンを生成できます。
v3 では、[https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_rds_signer.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_rds_signer.html) パッケージで同様のユーティリティクラスが利用できます。
## Amazon Polly の署名機能
v2 では、[https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html) を使用して、Amazon Polly サービスによって合成された音声への署名付き URL を生成できます。
v3 では、[https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_polly_request_presigner.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_polly_request_presigner.html) パッケージで同様のユーティリティ関数が利用できます。
# 特定のサービスクライアントに関する注意事項
## AWS Lambda
Lambda 呼び出しのレスポンスタイプは v2 と v3 で異なります。
```
// v2
import { Lambda } from "@aws-sdk/client-lambda";
import AWS from "aws-sdk";
const lambda = new AWS.Lambda({ REGION });
const invoke = await lambda.invoke({
FunctionName: "echo",
Payload: JSON.stringify({ message: "hello" }),
}).promise();
// in v2, Lambda::invoke::Payload is automatically converted to string via a
// specific code customization.
const payloadIsString = typeof invoke.Payload === "string";
console.log("Invoke response payload type is string:", payloadIsString);
const payloadObject = JSON.parse(invoke.Payload);
console.log("Invoke response object", payloadObject);
```
```
// v3
const lambda = new Lambda({ REGION });
const invoke = await lambda.invoke({
FunctionName: "echo",
Payload: JSON.stringify({ message: "hello" }),
});
// in v3, Lambda::invoke::Payload is not automatically converted to a string.
// This is to reduce the number of customizations that create inconsistent behaviors.
const payloadIsByteArray = invoke.Payload instanceof Uint8Array;
console.log("Invoke response payload type is Uint8Array:", payloadIsByteArray);
// To maintain the old functionality, only one additional method call is needed:
// v3 adds a method to the Uint8Array called transformToString.
const payloadObject = JSON.parse(invoke.Payload.transformToString());
console.log("Invoke response object", payloadObject);
```
## Amazon SQS
### MD5 チェックサム
メッセージ本文の MD5 チェックサムの計算をスキップするには、設定オブジェクトで `md5` を *false* に設定します。これを設定しない場合、SDK はデフォルトでメッセージを送信するためのチェックサムを計算し、受信したメッセージのチェックサムを検証します。
```
// Example: Skip MD5 checksum in Amazon SQS
import { SQS } from "@aws-sdk/client-sqs";
new SQS({
md5: false // note: only available in v3.547.0 and higher
});
```
これを入力パラメータとする Amazon SQS オペレーションでカスタム `QueueUrl` を使用する場合、v2 では、Amazon SQS クライアントのデフォルトエンドポイントを上書きするカスタム `QueueUrl` を指定できました。
### マルチリージョンメッセージ
v3 では、リージョンごとに 1 つのクライアントを使用する必要があります。AWS リージョンはクライアントレベルで初期化され、リクエスト間で変更されることはありません。
```
import { SQS } from "@aws-sdk/client-sqs";
const sqsClients = {
"us-east-1": new SQS({ region: "us-east-1" }),
"us-west-2": new SQS({ region: "us-west-2" }),
};
const queues = [
{ region: "us-east-1", url: "https://sqs.us-east-1.amazonaws.com/{AWS_ACCOUNT}/MyQueue" },
{ region: "us-west-2", url: "https://sqs.us-west-2.amazonaws.com/{AWS_ACCOUNT}/MyOtherQueue" },
];
for (const { region, url } of queues) {
const params = {
MessageBody: "Hello",
QueueUrl: url,
};
await sqsClients[region].sendMessage(params);
}
```
### カスタムエンドポイント
v3 では、カスタムエンドポイント、つまりデフォルトのパブリック Amazon SQS エンドポイントとは異なるエンドポイントを使用する場合は、常に Amazon SQS クライアントと ` QueueUrl` フィールドでエンドポイントを設定する必要があります。
```
import { SQS } from "@aws-sdk/client-sqs";
const sqs = new SQS({
// client endpoint should be specified in v3 when not the default public SQS endpoint for your region.
// This is required for versions <= v3.506.0
// This is optional but recommended for versions >= v3.507.0 (a warning will be emitted)
endpoint: "https://my-custom-endpoint:8000/",
});
await sqs.sendMessage({
QueueUrl: "https://my-custom-endpoint:8000/1234567/MyQueue",
Message: "hello",
});
```
カスタムエンドポイントを使用していない場合は、クライアントで `endpoint` を設定する必要はありません。
```
import { SQS } from "@aws-sdk/client-sqs";
const sqs = new SQS({
region: "us-west-2",
});
await sqs.sendMessage({
QueueUrl: "https://sqs.us-west-2.amazonaws.com/1234567/MyQueue",
Message: "hello",
});
```
# 補足ドキュメント
次の表に、AWS SDK for JavaScript (v3) の使用と理解に役立つ補足ドキュメントへのリンクを示します。
****
| 名前 | メモ |
| --- | --- |
| [SDK クライアント](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md) | SDK クライアントの初期化と、よく使用される設定可能なコンストラクタパラメータに関する情報。 |
| [アップグレードに関する注意事項 (2.x から 3.x)](https://github.com/aws/aws-sdk-js-v3/blob/main/UPGRADING.md) | AWS SDK for JavaScript (v2) からのアップグレードに関する情報。 |
| [AWS Lambda Node.js ランタイムでの AWS SDK for JavaScript (v3) の使用](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/AWS_LAMBDA.md) | AWS SDK for JavaScript (v3) を使用して AWS Lambda 内で作業するためのベストプラクティス。 |
| [パフォーマンス](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/performance/README.md) | AWS SDK チームが SDK のパフォーマンスを最適化するために行った取り組みと、効率的に動作させるための SDK の設定方法に関する情報。 |
| [TypeScript](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/TYPESCRIPT.md) | AWS SDK for JavaScript (v3) に関連する TypeScript のヒントとよくある質問。 |
| [エラー処理](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/ERROR_HANDLING.md) | AWS SDK for JavaScript (v3) に関連するエラーに対処するためのヒント。 |
| [効果的なプラクティス](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/EFFECTIVE_PRACTICES.md) | AWS SDK for JavaScript (v3) の使用に関する一般的な推奨事項。 |