创建和调用服务对象 - 适用于 JavaScript 的 AWS SDK

我们已宣布即将终止对 适用于 JavaScript 的 AWS SDK v2 的支持。建议您迁移到 适用于 JavaScript 的 AWS SDK v3。有关日期、其他详细信息以及如何迁移的信息,请参阅链接的公告。

创建和调用服务对象

JavaScript API 支持大多数可用的 AWS 服务。JavaScript API 中的各个服务类提供了对其服务中各个 API 调用的访问。有关 JavaScript API 中服务类、操作和参数的更多信息,请参阅 API 参考

在 Node.js 中使用开发工具包时,您使用 require 将开发工具包添加到应用程序,这为所有当前服务提供支持。

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

在将 SDK 与浏览器 JavaScript 结合使用时,您使用 AWS 托管的 SDK 包,将 SDK 包加载到浏览器脚本。要加载开发工具包,请添加以下 <script> 元素:

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

要查找当前的 SDK_VERSION_NUMBER,请参阅 适用于 JavaScript 的 AWS SDK API Reference Guide 中适用于 SDK for JavaScript 的 API 参考。

默认的托管 SDK 包提供对可用 AWS 服务中部分服务的支持。有关浏览器的托管开发工具包中默认服务的列表,请参阅 API 参考中的支持的服务。如果已经禁用了 CORS 安全检查,则可以将开发工具包用于其他服务。在这种情况下,您可以生成自定义版本的开发工具包以包含所需的其他服务。有关生成自定义版本的开发工具包的更多信息,请参阅为浏览器构建 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 函数指定整个开发工具包。如果只包含 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 等捆绑工具完成后,要求单个服务会生成只有完整大小一部分的开发工具包。对于内存或磁盘空间有限的环境,例如 IoT 设备或在 Lambda 函数中,这会很有帮助。

创建服务对象

要通过 JavaScript API 访问服务功能,您需要先创建服务对象,通过该服务对象来访问由底层客户端类提供的一组功能。通常而言,为每个服务提供有一个客户端类;但是,一些服务会在多个客户端类中划分对其功能的访问。

要使用某个功能,您必须创建提供对该功能访问的类的实例。以下示例演示了从 AWS.DynamoDB 客户端类为 DynamoDB 创建服务对象。

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

默认情况下,服务对象配置了同样用于配置开发工具包的全局设置。但是,您可以使用运行时配置数据来配置服务对象,使其特定于该服务对象。服务特定的配置数据在应用了全局配置设置之后应用。

以下示例中的 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 参数的值是一个映射,指定由服务对象定义的一个或多个参数值。以下示例显示 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 参考中可以找到各个方法的可用参数的详细信息。