aws-sdk-js-v3-usage

このスキルが有効な間は、コード、コメント、出力に絵文字を使用しないでください。

AWS SDK for JavaScript v3

パッケージ構成

• @aws-sdk/client-* — サービスごとに1つあり、smithy-typescriptによって生成されます。AWS のサービスおよびオペレーションと1対1で対応します
• @aws-sdk/lib-* — より高レベルのヘルパー（例：lib-dynamodb、lib-storage）
• @aws-sdk/*（プレフィックスなし）— ユーティリティパッケージ（主に内部用です。深いパスからインポートしないでください）

常にパッケージのルートからインポートしてください。

import { S3Client } from "@aws-sdk/client-s3"; // correct
// NOT: import { S3Client } from "@aws-sdk/client-s3/dist-cjs/S3Client"

2種類のクライアントスタイル

ベアボーン（推奨 — バンドルサイズが小さくなります）。

import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
const client = new S3Client({ region: "us-east-1" });
const output = await client.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));

集約型（v2スタイルですが、v2ではありません。バンドルサイズは大きくなります）。

import { S3 } from "@aws-sdk/client-s3";
const client = new S3({ region: "us-east-1" });
const output = await client.getObject({ Bucket: "b", Key: "k" });

クライアントの設定

v3にはグローバル設定がありません。各クライアントに設定を渡してください。regionは常に必須です。明示的に設定するか、AWS_REGION環境変数で指定してください。

const config = { region: "us-east-1", maxAttempts: 5 };
const s3 = new S3Client(config);
const dynamo = new DynamoDBClient(config);

インスタンス化後にclient.configを読み取ったり変更したりしないでください — 解決済みの形式であり（例：regionは非同期関数になります）、そのままでは使えない場合があります。references/effective-practices.mdを参照してください。

HTTP ハンドラー（@smithy/node-http-handlerのNodeHttpHandler）、リトライ戦略、エンドポイントの詳細、ロギング、FIPS、デュアルスタック、プロトコルの選択、S3固有のオプションについては、references/clients.mdを参照してください。

認証情報

すべてのプロバイダーは@aws-sdk/credential-providersから利用できます。認証情報は遅延読み込みされ、有効期限の約5分前までクライアントごとにキャッシュされます。

// Default chain (env → ini → IMDS/ECS) — use in most Node.js apps
const client = new S3Client({ credentials: fromNodeProviderChain() });

// Assume role (NOTE: fromTemporaryCredentials is correct for STS AssumeRole)
const client = new S3Client({
  credentials: fromTemporaryCredentials({ params: { RoleArn: "arn:aws:iam::123456789012:role/MyRole" } }),
});

// Named profile
const client = new S3Client({ profile: "my-profile" });

複数リージョンのクライアント間で認証情報とソケットプールを共有します。

const east = new S3Client({ region: "us-east-1" });
const { credentials, requestHandler } = east.config;
const west = new S3Client({ region: "us-west-2", credentials, requestHandler });

すべてのプロバイダー（Cognito、SSO、ウェブアイデンティティ、カスタムチェーン、STSのリージョン優先順位）については、references/credentials.mdを参照してください。

ストリーム（例：S3 GetObject Body）

ストリーミングレスポンスは必ず読み取るか破棄してください — 読み取られていないストリームはソケットを開いたままにするため、ソケットが枯渇します。

const { Body } = await client.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));
const str = await Body.transformToString();       // read as string
const bytes = await Body.transformToByteArray();  // read as Uint8Array
// or discard:
await (Body.destroy?.() ?? Body.cancel?.());

ストリームは一度しか読み取れません。

ページネーター

トークンを手動で扱う代わりに、paginate*関数を使用してください。

import { DynamoDBClient, paginateListTables } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({});

const tableNames = [];
for await (const page of paginateListTables({ client }, {})) {
  // page contains a single paginated output.
  tableNames.push(...page.TableNames);
}

DynamoDB DocumentClient

@aws-sdk/lib-dynamodbを使用すると、AttributeValuesではなくネイティブなJS型を扱えます。

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand, PutCommand } from "@aws-sdk/lib-dynamodb";

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}));
await client.send(new PutCommand({ TableName: "T", Item: { id: "1", name: "Alice" } }));
const { Item } = await client.send(new GetCommand({ TableName: "T", Key: { id: "1" } }));

マーシャリングオプション、大きな数値（NumberValue）、ページネーション、集約型クライアントについては、references/dynamodb.mdを参照してください。

S3：署名付きURL、マルチパートアップロード、Waiter

// Presigned GET URL
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
const url = await getSignedUrl(client, new GetObjectCommand({ Bucket: "b", Key: "k" }), { expiresIn: 3600 });

// Multipart upload (large files / streams)
import { Upload } from "@aws-sdk/lib-storage";
const upload = new Upload({ client, params: { Bucket: "b", Key: "k", Body: stream } });
await upload.done();

// Waiters
import { waitUntilObjectExists } from "@aws-sdk/client-s3";
await waitUntilObjectExists({ client, maxWaitTime: 120 }, { Bucket: "b", Key: "k" });

署名付きPOST、署名付きヘッダー、Waiterのオプションについては、references/s3.mdを参照してください。

エラー処理

import { S3ServiceException } from "@aws-sdk/client-s3";

try {
  await client.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));
} catch (e) {
  if (e?.$metadata) {
    // SDK service error — has $metadata.httpStatusCode, e.name, e.$response
    console.error(e.name, e.$metadata.httpStatusCode);
  }
}

特定のエラー型を確認するには、e.nameまたはinstanceofを使用してください。すべてのパターンについては、references/error-handling.mdを参照してください。

jsv3でのランタイム検証、デフォルト以外の形式へのシリアライズ、またはスキーマとは何かについての質問は、references/schemas.mdを参照してください。

パフォーマンス：並列ワークロード

// Configure maxSockets to match your parallel batch size
const client = new S3Client({
  requestHandler: { httpsAgent: { maxSockets: 50 } },
  cacheMiddleware: true, // skip if using custom middleware
});

ストリーミングのデッドロックに関する警告：ソケット数が限られている場合、リクエストとストリーム本文を別々にawaitしないでください。連結して処理してください。references/performance.mdを参照してください。

ミドルウェア

クライアントのすべてのコマンドにカスタムロジックを追加します。

client.middlewareStack.add(
  (next, context) => async (args) => {
    console.log(context.commandName, args.input);
    const result = await next(args);
    return result;
  },
  { name: "MyMiddleware", step: "build", override: true }
);

ステップの順序：initialize → serialize → build → finalizeRequest → deserialize

Abort Controller

const { AbortController } = require("@aws-sdk/abort-controller");
const { S3Client, CreateBucketCommand } = require("@aws-sdk/client-s3");

const abortController = new AbortController();
const client = new S3Client(clientParams);

const requestPromise = client.send(new CreateBucketCommand(commandParams), {
  abortSignal: abortController.signal,
});

// The request will not be created if abortSignal is already aborted.
// The request will be destroyed if abortSignal is aborted before response is returned.
abortController.abort();

// This will fail with "AbortError" as abortSignal is aborted.
await requestPromise;

Lambda のベストプラクティス

クライアントはハンドラーの外部で初期化し（コンテナーを再利用）、API 呼び出しは内部で行います。一度だけ実行する非同期セットアップには、ハンドラー内で遅延初期化フラグを使用してください。

import { S3Client } from "@aws-sdk/client-s3";

const client = new S3Client({}); // outside — reused across invocations

let ready = false;
export const handler = async (event) => {
  if (!ready) { await prepare(); ready = true; } // lazy one-time setup inside handler
  // ... API calls here
};

Lambda レイヤーとバージョニングについては、references/lambda.mdを参照してください。

Node.js のバージョン要件

• v3.968.0+ には Node.js >= 20 が必要です
• v3.723.0+ には Node.js >= 18 が必要です

TypeScript

レスポンスのフィールドは、デフォルトでT | undefinedとして型付けされます。@smithy/typesのAssertiveClientを使うと| undefinedを削除できます。また、NodeJsClient／BrowserClientを使うと、ストリーミング blob の型を絞り込めます。references/typescript.mdを参照してください。

SigV4a（S3 マルチリージョンアクセスポイント）

S3 MRAPおよび一部の機能にはSigV4aが必要です。次のいずれか1つだけをインストールし、副作用インポートする必要があります。

• @aws-sdk/signature-v4-crt — Node.jsのみ。パフォーマンスに優れています
• @aws-sdk/signature-v4a — Node.jsとブラウザーに対応。純粋なJSです

import "@aws-sdk/signature-v4a"; // side-effect only — no exported values needed

詳細およびMRAP ARN形式については、references/sigv4a.mdを参照してください。