Amazon SDK for JavaScript 是什么? - Amazon SDK for JavaScript
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

Amazon SDK for JavaScriptV3 API 参考指南详细描述了 Amazon SDK for JavaScript 版本 3 (V3) 的所有 API 操作。

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

Amazon SDK for JavaScript 是什么?

欢迎阅读《Amazon SDK for JavaScript 开发人员指南》。本指南提供有关设置和配置 Amazon SDK for JavaScript 的一般信息。它还会引导您完成使用 Amazon SDK for JavaScript 运行各种 Amazon 服务的示例和教程。

Amazon SDK for JavaScript v3 API 参考指南为 Amazon 服务提供了 JavaScript API。您可以使用 JavaScript API 构建适用于 Node.js 或浏览器的库或应用程序。


      JavaScript 环境、SDK 和 Amazon Web Services 之间的关系

SDK 主要版本的维护和支持

有关维护和支持 SDK 主要版本及其基础依赖关系的信息,请参阅 Amazon SDK 和工具参考指南中的以下内容:

版本 3 中的新增功能

SDK for JavaScript 版本 3 (V3) 包含以下新功能。

模块化软件包

用户现在可以为每项服务使用单独的软件包。

新的中间件堆栈

用户现在可以使用中间件堆栈来控制操作调用的生命周期。

此外,该 SDK 是用 TypeScript 编写的,具有许多优点,例如静态输入。

重要

本指南中 V3 的代码示例是用 ECMAScript 6 (ES6) 编写的。ES6 带来了新的语法和新功能,使您的代码更现代、更具可读性,并能做到更多的事情。要使用 ES6,您需要使用 Node.js 版本 13.x 或更高版本。要下载并安装最新版本的 Node.js,请参阅 Node.js 下载。有关更多信息,请参阅JavaScript ES6/CommonJS 语法

模块化软件包

SDK for JavaScript 版本 2 (V2) 要求您使用整个 Amazon SDK,如下所示。

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

如果您的应用程序使用许多 Amazon 服务,那么加载整个 SDK 不是问题。但是,如果您只需要使用少量 Amazon 服务,则意味着需要使用不需要或不使用的代码来增加应用程序的大小。

在 V3 中,您只能加载和使用所需的各项 Amazon 服务。以下示例显示了这一点,通过它您可以访问 Amazon DynamoDB (DynamoDB)。

import { DynamoDB } from "@aws-sdk/client-dynamodb";

您不仅可以加载和使用各项 Amazon 服务,还可以仅加载和使用所需的服务命令。以下示例显示了这一点,通过它您可以访问 DynamoDB 客户端和 ListTablesCommand 命令。

import { DynamoDBClient, ListTablesCommand } from "@aws-sdk/client-dynamodb";
重要

不应将子模块导入模块中。例如,以下代码可能会导致错误:

import { CognitoIdentity } from "@aws-sdk/client-cognito-identity/CognitoIdentity";

以下是正确的代码。

import { CognitoIdentity } from "@aws-sdk/client-cognito-identity";

比较代码大小

在版本 2 (V2) 中,列出您在 us-west-2 区域的所有 Amazon DynamoDB 表的简单代码示例可能如下所示。

var AWS = require("aws-sdk"); // Set the Region AWS.config.update({region: "us-west-2"}); // Create DynamoDB service object var ddb = new AWS.DynamoDB({ apiVersion: "2012-08-10" }); // Call DynamoDB to retrieve the list of tables ddb.listTables({ Limit:10 }, function(err, data) { if (err) { console.log("Error", err.code); } else { console.log("Tables names are ", data.TableNames); } });

V3 如下所示。

import { DynamoDBClient, ListTablesCommand } from "@aws-sdk/client-dynamodb"; (async function () { const dbclient = new DynamoDBClient({ region: 'us-west-2'}); try { const results = await dbclient.send(new ListTablesCommand); results.TableNames.forEach(function (item, index) { console.log(item); }); } catch (err) { console.error(err) } })();

aws-sdk 软件包会为您的应用程序增加大约 40 MB。将 var AWS = require("aws-sdk") 替换为 import {DynamoDB} from "@aws-sdk/client-dynamodb" 可将开销减少到大约 3 MB。将导入限制为仅 DynamoDB 客户端和 ListTablesCommand 命令,可将开销减少到 100 KB 以下。

// Load the DynamoDB client and ListTablesCommand command for Node.js import { DynamoDBClient, ListTablesCommand } from "@aws-sdk/client-dynamodb"; const dbclient = new DynamoDBClient({});

在 V3 中调用命令

您可以使用 V2 或 V3 命令在 V3 中执行操作。要使用 V3 命令,请导入命令和所需的 Amazon 服务包客户端,然后使用异步/等待模式通过 .send 方法运行命令。

要使用 V2 命令,您需要导入所需的 Amazon 服务包,然后使用回调或异步/等待模式直接在软件包中运行 V2 命令。

使用 V3 命令

V3 为每个 Amazon 服务包提供了一组命令,使您能够对该 Amazon 服务执行操作。安装 Amazon 服务后,您可以浏览项目中 node-modules/@aws-sdk/client-PACKAGE_NAME/commands folder. 的可用命令

您必须导入要使用的命令。例如,以下代码可加载 DynamoDB 服务和 CreateTableCommand 命令。

import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";

要以推荐的异步/等待模式调用这些命令,请使用以下语法。

CLIENT.send(new XXXCommand)

例如,以下示例使用推荐的异步/等待模式创建 DynamoDB 表。

import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb"; const dynamodb = new DynamoDB({region: 'us-west-2'}); var tableParams = { Table : TABLE_NAME }; (async function () => { try{ const data = await dynamodb.send(new CreateTableCommand(tableParams)); console.log("Success", data); } catch (err) { console.log("Error", err); } })();
使用 V2 命令

要在 SDK for JavaScript 中使用 V2 命令,您需要导入完整的 Amazon 服务包,如以下代码所示。

const { DynamoDB } = require('@aws-sdk/client-dynamodb');

要以推荐的异步/等待模式调用 V2 命令,请使用以下语法。

client.command(parameters)

以下示例使用 V2 createTable 命令,通过推荐的异步/等待模式创建 DynamoDB 表。

const {DynamoDB} = require('@aws-sdk/client-dynamodb'); const dymamoDB = new DynamoDB({region: 'us-west-2'}); var tableParams = { TableName : TABLE_NAME }; async function run() => { try { const data = await dymamoDB.createTable(tableParams); console.log("Success", data); } catch (err) { console.log("Error", err); } }; run();

以下示例使用 V2 createBucket 命令,通过回调模式创建 Amazon S3 存储桶。

const {S3} = require('@aws-sdk/client-s3'); const s3 = new S3({region: 'us-west-2'}); var bucketParams = { Bucket : BUCKET_NAME }; function run(){ s3.createBucket(bucketParams, function(err, data) { if (err) { console.log("Error", err); } else { console.log("Success", data.Location); } }) };

新的中间件堆栈

借助 SDK V2,您可以通过为请求附加事件侦听器,在请求生命周期的多个阶段修改请求。这种方法可能使调试请求生命周期中的错误变得困难。

在 V3 中,您可以使用新的中间件堆栈来控制操作调用的生命周期。这种方法有几个好处。堆栈中的每个中间件阶段都会在对请求对象进行任何更改后调用下一个中间件阶段。这也使调试堆栈中的问题变得更加容易,因为您可以准确地看到哪些被调用的中间件阶段导致了错误。

以下示例使用中间件向 Amazon DynamoDB 客户端(我们之前创建并演示了该客户端)添加自定义标头。第一个参数是一个接受 next 的函数,该函数指要调用的堆栈中的下一个中间件阶段,还有 context,这是一个包含有关正在调用的操作的一些信息的对象。该函数返回一个接受 args 的函数,这是一个包含传递给操作和请求的参数的对象。它使用 args 调用下一个中间件,然后返回结果。

dbclient.middlewareStack.add( (next, context) => args => { args.request.headers["Custom-Header"] = "value"; return next(args); }, { step: "build" } ); dbclient.send(new PutObjectCommand(params));

将 SDK 与 Node.js 结合使用

Node.js 是一个用于运行服务器端 JavaScript 应用程序的跨平台运行时系统。您可以在 Amazon Elastic Compute Cloud (Amazon EC2) 实例上设置 Node.js 以在服务器上运行。您还可以使用 Node.js 来编写按需 Amazon Lambda 函数。

使用 SDK for Node.js 与在 Web 浏览器中将其用于 JavaScript 的方式不同。区别在于,您加载 SDK 以及获取访问特定 Web 服务所需凭证的方法有所不同。如果在 Node.js 与浏览器之间使用特定 API 存在差别时,我们将对这些差别进行说明。

将 SDK 与 Amazon Cloud9 结合使用

您还可以使用在 Amazon Cloud9 IDE 中使用 SDK for JavaScript 开发 Node.js 应用程序。有关将 Amazon Cloud9 与 SDK for JavaScript 结合使用的更多信息,请参阅将 Amazon Cloud9 与 Amazon SDK for JavaScript 结合使用

将 SDK 与 Amazon Amplify 结合使用

对于基于浏览器的 Web、移动和混合应用程序,您也可以使用 GitHub 上的 Amazon Amplify 库。它扩展了 SDK for JavaScript,提供了一个声明性接口。

注意

Amplify 等框架可能无法提供与 SDK for JavaScript 相同的浏览器支持。有关详细信息,请查看框架文档。

将 SDK 与 Web 浏览器结合使用

所有主流 Web 浏览器支持 JavaScript 的执行。在 Web 浏览器中运行的 JavaScript 代码通常称为客户端 JavaScript

有关 Amazon SDK for JavaScript 支持的浏览器列表,请参阅支持的 Web 浏览器

在 Web 浏览器中使用 SDK for JavaScript 与在 Node.js 中使用它的方式不同。区别在于,您加载 SDK 以及获取访问特定 Web 服务所需凭证的方法有所不同。如果在 Node.js 与浏览器之间使用特定 API 存在差别时,我们将对这些差别进行说明。

在 V3 中使用浏览器

V3 允许您仅将所需的 SDK for JavaScript 文件捆绑和包含在浏览器中,从而减少开销。

要在 HTML 页面中使用 SDK for JavaScript V3,必须使用 Webpack 将所需的客户端模块和所有必需的 JavaScript 函数捆绑到一个 JavaScript 文件中,然后将其添加到 HTML 页面 <head> 的脚本标签中。例如:

<script src="./main.js"></script>
注意

有关 Webpack 的更多信息,请参阅使用 Webpack 捆绑应用程序

要使用 SDK for JavaScript V2,您需要添加一个指向 V2 SDK 最新版本的脚本标签。有关更多信息,请参阅《Amazon SDK for JavaScript 开发人员指南 v2》中的示例

常见使用案例

在浏览器脚本中使用 SDK for JavaScript 实现了多种颇具吸引力的使用案例。通过使用 SDK for JavaScript 访问各种 Web 服务,您可以在浏览器应用程序中构建一些东西,此处介绍了几个相关想法。

  • 构建 Amazon 服务的自定义控制台,在其中您可以跨区域和服务访问并组合功能,从而最好地满足您的组织或项目需求。

  • 使用 Amazon Cognito 以启用对您的浏览器应用程序和网站的经身份验证用户的访问,包括使用来自 Facebook 和其他提供商的第三方身份验证。

  • 使用 Amazon Kinesis 实时处理点击流或其他营销数据。

  • 为无服务器数据持久性使用 Amazon DynamoDB,例如针对网站访问者或应用程序用户的单独用户首选项。

  • 使用 Amazon Lambda 封装专有逻辑,您可以从浏览器脚本调用逻辑而无需下载和向用户泄露您的知识产权。

关于示例

您可以在 Amazon 代码示例存储库中浏览 SDK for JavaScript 示例。

资源

除了本指南外,还有以下适用于 SDK for JavaScript 开发人员的在线资源: