AWS SDK for JavaScript v3でapiVersionはもう指定しなくていい

Mar 12, 2021

この記事は、構成と文章の整理にAIを使っています。
あくまで読みやすくするための補助で、内容そのものをAIにすべて任せて書いているわけではありませんが、ところどころ相談しながら整えています。

v2のコードを見ていると new AWS.S3({ apiVersion: '2006-03-01' }) みたいな書き方がよく出てくる。v3に移行するときにこれも持っていくべきか迷ったので確認した。

結論

v3では apiVersion を指定する意味はない。消していい。

どのAPIバージョンを使うかは、@aws-sdk/client-s3 などのnpmパッケージのバージョンで決まる。固定したいならパッケージのバージョンを固定する。

v2はひとつのSDKの中に複数のAPIバージョンの定義を持っていて、apiVersion でどれを使うか選べた。

// v2
const s3 = new AWS.S3({ apiVersion: '2006-03-01' });

公式のv2ドキュメントでも、サービスオブジェクト生成時に apiVersion を渡す例が普通に載っている。サービス側のAPIが更新されても、自分のコードが想定しているバージョンに固定しておける、というのが目的だった。

グローバル設定の AWS.config.apiVersion に 'latest' を指定したり、apiVersions でサービスごとにまとめて指定したりもできた。

v3はサービスのモデル定義（Smithy）からコード生成されていて、1つのクライアントパッケージは1つのAPIバージョンだけに対応している。複数バージョンを切り替える仕組みそのものがない。

ただしややこしいのが、v3のクライアント設定は apiVersion を受け付けてしまうこと。

// v3：エラーにはならないが、効果もない
const lambda = new LambdaClient({
  region: 'ap-northeast-1',
  apiVersion: '2015-03-31',
});

これはv3のGitHubでもissue（#1869）として上がっていて、「v3は複数APIバージョンをサポートしないのに apiVersion を受け付けるのは紛らわしいので、設定から消すべき」という内容だった。そのissueが今どう扱われているか（型から消えたのか）は未確認。

なお、AWS公式のv2→v3移行ガイド（クライアントコンストラクタのオプション対応表）には apiVersion の項目自体が載っていない。「Deprecated」と明記されているわけではなく、そもそも移行対象として扱われていない、という状態。

v3では、使うAPIの定義はパッケージに含まれている。なので固定したいならいつも通り package.json とlockファイルで管理する。

{
  "dependencies": {
    "@aws-sdk/client-s3": "3.xxx.0"
  }
}

v3は @aws-sdk/client-* がサービスごとに別パッケージになっているので、クライアント同士でバージョンがずれると、内部で使っている @smithy/* パッケージが重複して入ることがある。バージョンを揃えておいたほうが無難。