このスキルがアクティブな場合、コード、コメント、または出力でエモジを使用しないでください。

AWS SDK for JavaScript v3

パッケージ構成

• @aws-sdk/client-* — 1 サービスにつき 1 つ、smithy-typescript で生成; AWS サービスと操作と 1 対 1 対応
• @aws-sdk/lib-* — 高レベルのヘルパー (例: lib-dynamodb, lib-storage)
• @aws-sdk/* (プレフィックスなし) — ユーティリティパッケージ (主に内部用; 深いパスからのインポートは避ける)

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

import { S3Client } from "@aws-sdk/client-s3"; // 正しい
// 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 分前までクライアントごとにキャッシュされます。

// デフォルトチェーン (env → ini → IMDS/ECS) — ほとんどの Node.js アプリで使用
const client = new S3Client({ credentials: fromNodeProviderChain() });

// ロール引き受け (NOTE: STS AssumeRole では fromTemporaryCredentials が正しい)
const client = new S3Client({
  credentials: fromTemporaryCredentials({ params: { RoleArn: "arn:aws:iam::123456789012:role/MyRole" } }),
});

// 名前付きプロファイル
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();       // 文字列として読み込む
const bytes = await Body.transformToByteArray();  // Uint8Array として読み込む
// または破棄:
await (Body.destroy?.() ?? Body.cancel?.());

ストリームは 1 回だけ読み込むことができます。

ページネーター

手動トークン処理の代わりに paginate* 関数を使用:

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

const client = new DynamoDBClient({});

const tableNames = [];
for await (const page of paginateListTables({ client }, {})) {
  // page には 1 つのページネーション済み出力が含まれます。
  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" } }));

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

S3: 署名済み URL、マルチパートアップロード、ウェイター

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

// マルチパートアップロード (大規模ファイル / ストリーム)
import { Upload } from "@aws-sdk/lib-storage";
const upload = new Upload({ client, params: { Bucket: "b", Key: "k", Body: stream } });
await upload.done();

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

署名済み POST、署名付きヘッダー、ウェイターオプションについては、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 サービスエラー — $metadata.httpStatusCode、e.name、e.$response がある
    console.error(e.name, e.$metadata.httpStatusCode);
  }
}

特定のエラータイプについては e.name または instanceof をチェックしてください。完全なパターンについては references/error-handling.md を参照してください。

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

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

// maxSockets を並列バッチサイズに合わせて設定
const client = new S3Client({
  requestHandler: { httpsAgent: { maxSockets: 50 } },
  cacheMiddleware: true, // カスタムミドルウェアを使用している場合はスキップ
});

ストリーミングデッドロック警告: ソケット数が限られている場合、リクエストとストリームボディを個別に 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

AbortController

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,
});

// abortSignal が既に中止されている場合、リクエストは作成されません。
// レスポンスが返される前に abortSignal が中止された場合、リクエストは破棄されます。
abortController.abort();

// abortSignal が中止されているため、これは「AbortError」で失敗します。
await requestPromise;

Lambda ベストプラクティス

クライアントをハンドラー 外部 で初期化 (コンテナ再利用)、API 呼び出しを 内部 で実行。1 回限りの非同期セットアップについては、ハンドラー内で遅延初期化フラグを使用:

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

const client = new S3Client({}); // 外部 — 呼び出し間で再利用

let ready = false;
export const handler = async (event) => {
  if (!ready) { await prepare(); ready = true; } // ハンドラー内の遅延 1 回限りセットアップ
  // ... API 呼び出しはここ
};

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"; // サイドエフェクトのみ — エクスポートされた値は不要

完全な詳細と MRAP ARN 形式については、references/sigv4a.md を参照してください。