AWS SDK for JavaScript v2 のサポート終了が間近に迫っていることが発表されています。AWS SDK for JavaScript v3 に移行することをお勧めします。日付、その他の詳細、移行方法については、リンク先の発表内容を参照してください。

AWS SDK for JavaScript v2 のサポート終了が間近に迫っていることが発表されています。AWS SDK for JavaScript v3 に移行することをお勧めします。日付、その他の詳細、移行方法については、リンク先の発表内容を参照してください。

サービスオブジェクトの作成と呼び出し

JavaScript API は、利用可能なほとんどの AWS のサービスをサポートしています。JavaScript API の各サービスクラスは、そのサービス内のすべての API 呼び出しへのアクセスを提供します。JavaScript API のサービスクラス、オペレーション、およびパラメータの詳細については、「API リファレンス」を参照してください。

Node.js で SDK を使用する場合、require を使用して SDK パッケージをアプリケーションに追加します。これにより、現在のすべてのサービスがサポートされます。

var AWS = require('aws-sdk');

ブラウザの JavaScript で SDK を使用する場合、AWS がホストする SDK パッケージを使用して、SDK パッケージをブラウザスクリプトにロードします。SDK パッケージをロードするには、次の <script> 要素を追加します。

<script src="https://sdk.amazonaws.com/js/aws-sdk-SDK_VERSION_NUMBER.min.js"></script>

最新の SDK_VERSION_NUMBER を確認するには、AWS SDK for JavaScriptAPI リファレンスガイドで SDK for JavaScript の API リファレンスを参照してください。

デフォルトのホスティングされた SDK パッケージは、利用可能な AWS のサービスのサブセットをサポートしています。ブラウザ用のホスティングされた SDK パッケージのデフォルトサービスリストについては、API リファレンスの「サポートされるサービス」を参照してください。CORS セキュリティチェックが無効になっている場合は、SDK を他のサービスで使用することができます。この場合、カスタムバージョンの SDK を構築して、必要な追加のサービスを含めることができます。SDK のカスタムバージョン構築の詳細については、「ブラウザ用 SDK の構築」を参照してください。

個々のサービスを要求する

前述のように SDK for JavaScript を要求すると、コードに SDK 全体が含まれます。または、コードで使用される個々のサービスのみを要求するように選択できます。Amazon S3 サービスオブジェクトの作成に使用される以下のコードを検討してください。

// Import the AWS SDK
var AWS = require('aws-sdk');

// Set credentials and Region
// This can also be done directly on the service client
AWS.config.update({region: 'us-west-1', credentials: {YOUR_CREDENTIALS}});

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

前の例では、require 関数は SDK 全体を指定します。Amazon S3 サービスに必要な SDK の部分だけが含まれている場合、ネットワーク上で転送するコードの量、およびコードのメモリオーバーヘッドはかなり少なくなります。個々のサービスを要求するには、すべて小文字のサービスコンストラクタを含めて、示されているように require 関数を呼び出します。

require('aws-sdk/clients/SERVICE');

SDK の Amazon S3 部分のみが含まれている場合、前の Amazon S3 サービスオブジェクトを作成するためのコードは次のようになります。

// Import the Amazon S3 service client
var S3 = require('aws-sdk/clients/s3');
 
// Set credentials and Region
var s3 = new S3({
    apiVersion: '2006-03-01',
    region: 'us-west-1', 
    credentials: {YOUR_CREDENTIALS}
  });

すべてのサービスをアタッチしなくても、グローバル AWS の名前空間にアクセスできます。

require('aws-sdk/global');

この手法は、同じ設定を複数の個々のサービスに適用する場合に便利です (たとえば、すべてのサービスに同じ認証情報を提供するなど)。個々のサービスを要求することで、Node.js でのロード時間とメモリ消費量が削減されます。個々のサービスの要求を Browserify や webpack などのバンドルツールと一緒に実行すると、SDK は完全なサイズの数分の 1 になります。これは、IoT デバイスや Lambda 関数など、メモリやディスク容量に制約のある環境で役立ちます。

サービスオブジェクトの作成

JavaScript API を介してサービス機能にアクセスするには、まず サービスオブジェクトを作成します。このサービスオブジェクトを通じて、基盤となるクライアントクラスが提供する一連の機能にアクセスします。通常、各サービスにつき 1 つのクライアントクラスが用意されています。ただし、一部のサービスでは、複数のクライアントクラス間でサービス機能へのアクセスを分割しています。

機能を使用するには、その機能へのアクセスを提供するクラスのインスタンスを作成する必要があります。次の例は、AWS.DynamoDB クライアントクラスからの DynamoDB 用のサービスオブジェクトの作成を示しています。

var dynamodb = new AWS.DynamoDB({apiVersion: '2012-08-10'});

デフォルトで、サービスオブジェクトにはグローバル設定が構成されます。この設定は、SDK の設定にも使用されます。ただし、そのサービスオブジェクトに固有のランタイム設定データを使用してサービスオブジェクトを設定することができます。グローバル設定を適用した後に、サービス固有の設定データが適用されます。

次の例では、Amazon EC2 サービスオブジェクトが特定のリージョンの設定で作成されますが、それ以外の場合にはグローバル設定が使用されます。

var ec2 = new AWS.EC2({region: 'us-west-2', apiVersion: '2014-10-01'});

個々のサービスオブジェクトに適用されるサービス固有の設定をサポートすることに加えて、指定されたクラスの、新しく作成されたすべてのサービスオブジェクトに対してサービス固有の設定を適用することもできます。例えば、Amazon EC2 クラスから作成されたすべてのサービスオブジェクトが米国西部 (オレゴン)(us-west-2) リージョンを使用するように設定するには、AWS.config グローバル設定オブジェクトに以下を追加します。

AWS.config.ec2 = {region: 'us-west-2', apiVersion: '2016-04-01'};

サービスオブジェクトの API バージョンのロック

オブジェクト作成時に apiVersion オプションを指定することで、サービスオブジェクトを特定のサービスの API バージョンにロックすることができます。次の例では、特定の API バージョンにロックされている DynamoDB サービスオブジェクトが作成されます。

var dynamodb = new AWS.DynamoDB({apiVersion: '2011-12-05'});

サービスオブジェクトの API バージョンのロックに関する詳細については、「API バージョンのロック」を参照してください。

サービスオブジェクトパラメータの指定

サービスオブジェクトのメソッドを呼び出す場合、API の必要に応じて JSON でパラメータを渡します。例えば、Amazon S3 では、指定されたバケットとキーのオブジェクトを取得するために、getObject メソッドに以下のパラメータを渡します。JSON パラメータを渡す詳細については、「JSON の使用」を参照してください。

s3.getObject({Bucket: 'bucketName', Key: 'keyName'});

Amazon S3 パラメータの詳細については、API リファレンスの「Class: AWS.S3」を参照してください。

さらに、サービスオブジェクト作成時に、params パラメータを使用して個々のパラメータに値をバインドすることができます。サービスオブジェクトの params パラメータの値は、サービスオブジェクトによって定義された 1 つ以上のパラメータ値を指定するマップです。次の例は、Amazon S3 サービスオブジェクトの Bucket パラメータが amzn-s3-demo-bucket という名前のバケットにバインドされていることを示しています。

var s3bucket = new AWS.S3({params: {Bucket: 'amzn-s3-demo-bucket'}, apiVersion: '2006-03-01' });

サービスオブジェクトをバケットにバインドすることで、s3bucket サービスオブジェクトは amzn-s3-demo-bucket パラメータ値をデフォルト値として扱い、以降のオペレーションで指定する必要がなくなります。パラメータ値が適用できないオペレーションにオブジェクトを使用すると、バインドされたパラメータ値はすべて無視されます。新しい値を指定してサービスオブジェクトを呼び出すときに、このバインドされたパラメータをオーバーライドできます。

var s3bucket = new AWS.S3({ params: {Bucket: 'amzn-s3-demo-bucket'}, apiVersion: '2006-03-01' });
s3bucket.getObject({Key: 'keyName'});
// ...
s3bucket.getObject({Bucket: 'amzn-s3-demo-bucket3', Key: 'keyOtherName'});

各メソッドで利用可能なパラメータに関する詳細は、API リファレンスにあります。