适用于 JavaScript 的 Amazon SDK v2 已终止支持。建议您迁移到 [适用于 JavaScript 的 Amazon SDK v3](https://docs.amazonaws.cn//sdk-for-javascript/v3/developer-guide/)。有关更多详情和如何迁移的信息，请参阅本[公告](https://www.amazonaws.cn/blogs//developer/announcing-end-of-support-for-aws-sdk-for-javascript-v2/)。

# 适用于 JavaScript 的 Amazon SDK 入门
开始使用新的浏览器脚本入门[此文本已忽略](https://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/getting-started-browser.html)

浏览器脚本入门经过了重新编写，简化了示例以及访问 Amazon Polly 服务来发送文本和返回可在浏览器中播放的合成语音的过程。有关新内容，请参阅[浏览器脚本入门](https://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/getting-started-browser.html)。

适用于 JavaScript 的 Amazon SDK提供了在浏览器脚本或 Node.js 中对 Web 服务的访问。本部分有两个入门练习，向您演示如何在这两个 JavaScript 环境中使用 SDK for JavaScript。

**Topics**
+ [

# 浏览器脚本入门
](getting-started-browser.md)
+ [

# Node.js 入门
](getting-started-nodejs.md)

# 浏览器脚本入门


![\[JavaScript code example that applies to browser execution\]](http://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/images/browsericon.png)

**此浏览器脚本示例向您演示：**
+ 如何使用 Amazon Cognito Identity 通过浏览器脚本访问 Amazon 服务。
+ 如何使用 Amazon Polly 将文本转换为合成语音。
+ 如何使用预签名程序对象创建预签名 URL。

## 情景


Amazon Polly 云服务可以将文本转化为逼真的语音。可以使用 Amazon Polly 开发能提高参与度和可用性的应用程序。Amazon Polly 支持多种语言，并包含各种逼真的语音。有关 Amazon Polly 的更多信息，请参阅《[Amazon Polly Developer Guide**](https://docs.amazonaws.cn/polly/latest/dg/)》。

本示例演示如何设置和运行简单的浏览器脚本，该脚本获取您输入的文本、将文本发送到 Amazon Polly，然后返回文本的合成音频 URL 供您播放。浏览器脚本使用 Amazon Cognito Identity 提供访问 Amazon 服务所需的凭证。您将看到在浏览器脚本中加载和使用 SDK for JavaScript 的基本模式。

**注意**  
在此示例中，合成语音的播放需要在支持 HTML 5 音频的浏览器中运行。

![\[浏览器脚本如何与 Amazon Cognito Identity 和 Amazon Polly 服务交互的示意图\]](http://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/images/images_bjs/browserscenario.png)


浏览器脚本使用 SDK for JavaScript，通过以下 API 来对文本执行合成：
+ [https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html) 构造函数
+ [https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html) 构造函数
+ [https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html#getSynthesizeSpeechUrl-property](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html#getSynthesizeSpeechUrl-property)

## 步骤 1：创建一个 Amazon Cognito 身份池


在本练习中，您将创建并使用一个 Amazon Cognito 身份池，为浏览器脚本提供对 Amazon Polly 服务的无需验证身份的访问。创建身份池还会创建两个 IAM 角色，一个用于支持由身份提供商进行了身份验证的用户，另一个用于支持未经身份验证的来宾用户。

在本练习中，我们仅使用未经身份验证的用户角色，将重点放在任务上。您可在以后集成对身份提供商和通过身份验证的用户的支持。有关添加 Amazon Cognito 身份池的更多信息，请参阅《Amazon Cognito 开发人员指南**》中的[教程：创建身份池](https://docs.amazonaws.cn/cognito/latest/developerguide/tutorial-create-identity-pool.html)。

**创建 Amazon Cognito 身份池**

1. 登录 Amazon Web Services 管理控制台 并打开 Amazon Cognito 控制台，网址为 [https://console.aws.amazon.com/cognito/](https://console.amazonaws.cn/cognito/)。

1. 在左侧导航窗格中，选择**身份池**。

1. 选择**创建身份池**。

1. 在**配置身份池信任**中，选择**来宾访问权限**进行用户身份验证。

1. 在**配置权限**中，选择**创建新的 IAM 角色**并在 **IAM 角色名称**中输入一个名称（例如 *getStartedRole*）。

1. 在**配置属性**中，在**身份池名称**中输入一个名称（例如 *getStartedPool*）。

1. 在**查看并创建**中，确认您为新身份池所做的选择。选择**编辑**以返回向导并更改任何设置。完成后，选择**创建身份池**。

1. 记下新创建的 Amazon Cognito 身份池的**身份池 ID** 和**区域**。您需要这些值以便替换 [步骤 4：写入浏览器脚本](#getting-started-browser-write-sample) 中的*IDENTITY\$1POOL\$1ID* 和 *REGION*。

在创建 Amazon Cognito 身份池之后，您已准备好添加浏览器脚本使用 Amazon Polly 所需的权限。

## 步骤 2：将策略添加到创建的 IAM 角色


要启用浏览器脚本对 Amazon Polly 的访问以进行语音合成，请使用为 Amazon Cognito 身份池创建的未经身份验证的 IAM 角色。这需要您将 IAM policy 添加到角色。有关修改 IAM 角色的更多信息，请参阅《IAM 用户指南》**中的[修改角色权限策略](https://docs.amazonaws.cn/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-modify_permissions-policy)。

**将 Amazon Polly 策略添加到与未验证身份用户关联的 IAM 角色**

1. 登录 Amazon Web Services 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.amazonaws.cn/iam/)。

1. 在左侧导航窗格中，选择**角色**。

1. 选择要修改的角色的名称（例如，*getStartedRole*），然后选择**权限**选项卡。

1. 选择**添加权限**，然后选择**附加策略**。

1. 在此角色的**添加权限**页面中，找到并选中 **AmazonPollyReadOnly** 的复选框。
**注意**  
您可以使用此流程来启用对任何 Amazon 服务的访问权限。

1. 选择**添加权限**。

创建 Amazon Cognito 身份池并将 Amazon Polly 的权限添加到未验证身份用户的 IAM 角色之后，您已准备好生成网页和浏览器脚本。

## 步骤 3：创建 HTML 页面


示例应用程序只有一个 HTML 页面，其中包含用户界面和浏览器脚本。要开始，请创建一个 HTML 文档并将以下内容复制到其中。该页面包括输入字段和按钮、`<audio>` 元素（用于播放合成语音）以及 `<p>` 元素（用于显示消息）。（请注意，完整示例显示在此页面的底部。）

有关 `<audio>` 元素的更多信息，请参阅[音频](https://www.w3schools.com/tags/tag_audio.asp)。

```
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>Amazon SDK for JavaScript - Browser Getting Started Application</title>
  </head>

  <body>
    <div id="textToSynth">
      <input autofocus size="23" type="text" id="textEntry" value="It's very good to meet you."/>
      <button class="btn default" onClick="speakText()">Synthesize</button>
      <p id="result">Enter text above then click Synthesize</p>
    </div>
    <audio id="audioPlayback" controls>
      <source id="audioSource" type="audio/mp3" src="">
    </audio>
    <!-- (script elements go here) -->
 </body>
</html>
```

保存 HTML 文件，并将它命名为 `polly.html`。为应用程序创建用户界面之后，您已准备好添加运行应用程序的浏览器脚本代码。

## 步骤 4：写入浏览器脚本


创建浏览器脚本时首先要做的是，通过在页面的 `<audio>` 元素之后添加 `<script>` 元素来包括 SDK for JavaScript：要查找当前的 SDK\$1VERSION\$1NUMBER，请参阅 [适用于 JavaScript 的 Amazon SDK API Reference Guide](https://docs.amazonaws.cn/AWSJavaScriptSDK/latest/) 中适用于 SDK for JavaScript 的 API 参考。

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

然后，在开发工具包条目之后添加新的 `<script type="text/javascript">` 元素。您将浏览器脚本添加到此元素。为 SDK 设置 Amazon 区域和凭证。接下来，创建名为 `speakText()` 的函数，该函数由按钮作为事件处理程序调用。

要通过 Amazon Polly 合成语音，您必须提供多种参数，包括输出的声音格式、采样率、所用语音的 ID 以及要播放的文本。在您最初创建参数时，请将 `Text:` 参数设置为空字符串；`Text:` 参数将设置为您从网页的 `<input>` 元素检索的值。将以下代码中的 *IDENTITY\$1POOL\$1ID* 和 *REGION* 替换为[步骤 1：创建一个 Amazon Cognito 身份池](#getting-started-browser-create-identity-pool)中记下的值。

```
    <script type="text/javascript">

        // Initialize the Amazon Cognito credentials provider
        AWS.config.region = 'REGION';
        AWS.config.credentials = new AWS.CognitoIdentityCredentials({IdentityPoolId: 'IDENTITY_POOL_ID'});

        // Function invoked by button click
        function speakText() {
            // Create the JSON parameters for getSynthesizeSpeechUrl
            var speechParams = {
                OutputFormat: "mp3",
                SampleRate: "16000",
                Text: "",
                TextType: "text",
                VoiceId: "Matthew"
            };
            speechParams.Text = document.getElementById("textEntry").value;
```

Amazon Polly 将合成语音作为音频流返回。在浏览器中播放音频的最简单方法是让 Amazon Polly 通过预签名 URL 来提供音频，然后您可以在网页的 `<audio>` 元素中设置 `src` 属性。

创建新的 `AWS.Polly` 服务对象。然后创建 `AWS.Polly.Presigner` 对象，您将用它来创建可从中检索合成语音音频的预签名 URL。您必须传递所定义的语音参数，以及您为 `AWS.Polly` 构造函数创建的 `AWS.Polly.Presigner` 服务对象。

创建预签名程序对象之后，调用该对象的 `getSynthesizeSpeechUrl` 方法并传递语音参数。如果成功，此方法返回合成语音的 URL，然后您将其分配到 `<audio>` 元素进行播放。

```
            // Create the Polly service object and presigner object
            var polly = new AWS.Polly({apiVersion: '2016-06-10'});
            var signer = new AWS.Polly.Presigner(speechParams, polly)

            // Create presigned URL of synthesized speech file
            signer.getSynthesizeSpeechUrl(speechParams, function(error, url) {
            if (error) {
                document.getElementById('result').innerHTML = error;
            } else {
                document.getElementById('audioSource').src = url;
                document.getElementById('audioPlayback').load();
                document.getElementById('result').innerHTML = "Speech ready to play.";
            }
          });
        }
    </script>
```

## 步骤 5：运行示例


要运行示例应用程序，请将 `polly.html` 加载到 Web 浏览器中。浏览器的演示应该类似于此。

![\[Web 应用程序浏览器界面\]](http://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/images/browsergetstarted.png)


在输入框中输入您希望转换为语音的短语，然后选择 **Synthesize (合成)**。准备好播放音频时，将显示一条消息。使用音频播放器控件收听合成语音。

## 完整示例


下面是带有浏览器脚本的完整 HTML 页面。[GitHub 上的此处](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascript/example_code//browserstart/polly.html)也提供了该示例。

```
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>AWS SDK for JavaScript - Browser Getting Started Application</title>
  </head>

  <body>
    <div id="textToSynth">
      <input autofocus size="23" type="text" id="textEntry" value="It's very good to meet you."/>
      <button class="btn default" onClick="speakText()">Synthesize</button>
      <p id="result">Enter text above then click Synthesize</p>
    </div>
    <audio id="audioPlayback" controls>
      <source id="audioSource" type="audio/mp3" src="">
    </audio>
    <script src="https://sdk.amazonaws.com/js/aws-sdk-2.410.0.min.js"></script>
    <script type="text/javascript">

        // Initialize the Amazon Cognito credentials provider
        AWS.config.region = 'REGION';
        AWS.config.credentials = new AWS.CognitoIdentityCredentials({IdentityPoolId: 'IDENTITY_POOL_ID'});

        // Function invoked by button click
        function speakText() {
            // Create the JSON parameters for getSynthesizeSpeechUrl
            var speechParams = {
                OutputFormat: "mp3",
                SampleRate: "16000",
                Text: "",
                TextType: "text",
                VoiceId: "Matthew"
            };
            speechParams.Text = document.getElementById("textEntry").value;

            // Create the Polly service object and presigner object
            var polly = new AWS.Polly({apiVersion: '2016-06-10'});
            var signer = new AWS.Polly.Presigner(speechParams, polly)

            // Create presigned URL of synthesized speech file
            signer.getSynthesizeSpeechUrl(speechParams, function(error, url) {
            if (error) {
                document.getElementById('result').innerHTML = error;
            } else {
                document.getElementById('audioSource').src = url;
                document.getElementById('audioPlayback').load();
                document.getElementById('result').innerHTML = "Speech ready to play.";
            }
          });
        }
    </script>
  </body>
</html>
```

## 可能的增强功能


此处为该应用程序的变体，可用于进一步探索如何在浏览器脚本中使用 SDK for JavaScript。
+ 使用其他声音输出格式进行试验。
+ 添加选项，用于从 Amazon Polly 提供的多种语音中任选其一。
+ 集成 Facebook 或 Amazon 等身份提供商以使用经过身份验证的 IAM 角色。

# Node.js 入门
新的 Node.js 入门[此文本已忽略](https://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/getting-started-nodejs.html)

Node.js 入门经过了重新编写，使用更新的示例代码并更详细地介绍了如何创建 `package.json` 文件以及 Node.js 代码本身。有关新内容，请参阅 [Node.js 入门](https://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/getting-started-nodejs.html)。

![\[JavaScript code example that applies to Node.js execution\]](http://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/images/nodeicon.png)

**此 Node.js 代码示例演示：**
+ 如何为您的项目创建 `package.json` 清单。
+ 如何安装和包括项目所用的模块。
+ 如何通过 `AWS.S3` 客户端类创建 Amazon Simple Storage Service（Amazon S3）服务对象。
+ 如何创建 Amazon S3 桶并将对象上传到该桶。

## 情景


示例演示如何设置和运行简单 Node.js 模块，该模块创建 Amazon S3 桶，然后将文本对象添加到该桶。

由于 Amazon S3 中的桶名称必须全局唯一，此示例包括了第三方 Node.js 模块，用于生成您可纳入桶名称的唯一 ID 值。此额外的模块名为 `uuid`。

## 先决条件任务


要设置和运行此示例，您必须先完成以下任务：
+ 创建用于开发 Node.js 模块的工作目录。将此目录命名为 `awsnodesample`。请注意，必须在应用程序可更新的位置中创建该目录。例如，在 Windows 中，请勿在“C:\$1Program Files”下创建该目录。
+ 安装 Node.js。有关更多信息，请参阅 [Node.js](https://nodejs.org) 网站。您可在 [https://nodejs.org/en/download/current/](https://nodejs.org/en/download/current/) 中查找和下载适用于各种操作系统的 Node.js 最新版本和 LTS 版本。

**Contents**
+ [

## 情景
](#getting-started-nodejs-scenario)
+ [

## 先决条件任务
](#getting-started-nodejs-prerequisites)
+ [

## 步骤 1：安装 SDK 和依赖项
](#getting-started-nodejs-install-sdk)
+ [

## 步骤 2：配置凭证
](#getting-started-nodejs-credentials)
+ [

## 步骤 3：为项目创建包 JSON
](#getting-started-nodejs-download)
+ [

## 步骤 4：编写 Node.js 代码
](#getting-started-nodejs-js-code)
+ [

## 步骤 5：运行示例
](#getting-started-nodejs-run-sample)

## 步骤 1：安装 SDK 和依赖项


使用 [npm（Node.js 包管理器）](https://www.npmjs.com)安装 SDK for JavaScript 包：

从程序包中的 `awsnodesample` 目录，在命令行中键入以下内容。

```
npm install aws-sdk
```

此命令在项目中安装 SDK for JavaScript，并更新 `package.json` 以将该 SDK 作为项目依赖项列出。您可以在 [npm 网站](https://www.npmjs.com)上通过搜索“aws-sdk”找到有关此程序包的信息。

接下来，通过在命令行中键入以下内容，在项目中安装 `uuid` 模块，这会安装模块并更新 `package.json`。有关 `uuid` 的更多信息，请参阅位于 [https://www.npmjs.com/package/uuid](https://www.npmjs.com/package/uuid) 的模块页面。

```
npm install uuid
```

这些程序包及其关联的代码将安装在项目的 `node_modules` 子目录中。

有关安装 Node.js 包的更多信息，请参阅 [npm（Node.js 包管理器）网站](https://www.npmjs.com)上的 [Downloading and installing packages locally](https://docs.npmjs.com/getting-started/installing-npm-packages-locally) 和 [Creating Node.js Modules](https://docs.npmjs.com/getting-started/creating-node-modules)。有关下载和安装适用于 JavaScript 的 Amazon SDK的信息，请参阅[安装 SDK for JavaScript](installing-jssdk.md)。

## 步骤 2：配置凭证


您需要向 Amazon 提供凭证，这样只有您的账户及其资源可由 SDK 访问。有关获取您的账户凭证的更多信息，请参阅[使用 Amazon 进行 SDK 身份验证](getting-your-credentials.md)。

要保存此信息，我们建议您创建一个共享凭证文件。要了解如何操作，请参阅[从共享凭证文件加载 Node.js 中的凭证](loading-node-credentials-shared.md)。您的凭证文件应该类似于下例所示。

```
[default]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY
```

您可以通过在 Node.js 中执行以下代码来确定是否已正确设置您的凭证：

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

AWS.config.getCredentials(function(err) {
  if (err) console.log(err.stack);
  // credentials not loaded
  else {
    console.log("Access key:", AWS.config.credentials.accessKeyId);
  }
});
```

同样，如果您已在 `config` 文件中正确设置了区域，您可以通过将 `AWS_SDK_LOAD_CONFIG` 环境变量设置为任何值并使用以下代码来显示该值：

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

console.log("Region: ", AWS.config.region);
```

## 步骤 3：为项目创建包 JSON


创建 `awsnodesample` 项目目录之后，您可以创建和添加 `package.json` 文件用于保存 Node.js 项目的元数据。有关在 Node.js 项目中使用 `package.json` 的详细信息，请参阅 [Creating a package.json file](https://docs.npmjs.com/creating-a-package-json-file)。

在项目目录中，创建名为 `package.json` 的新文件。然后将此 JSON 添加到文件。

```
{
  "dependencies": {},
  "name": "aws-nodejs-sample",
  "description": "A simple Node.js application illustrating usage of the SDK for JavaScript.",
  "version": "1.0.1",
  "main": "sample.js",
  "devDependencies": {},
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "NAME",
  "license": "ISC"
}
```

保存该文件。在您安装所需的模块时，文件的 `dependencies` 部分将完成。您可以在 [GitHub 上的此处](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascript/example_code/nodegetstarted/example_package.json)找到显示这些依赖项的示例的 JSON 文件。

## 步骤 4：编写 Node.js 代码


创建名为 `sample.js` 的新文件以包含示例代码。首先，添加 `require` 函数调用以包括 SDK for JavaScript 和 `uuid` 模块，使其可供您使用。

通过将唯一 ID 值附加到可识别的前缀（在本例中为 `'node-sdk-sample-'`），生成用于创建 Amazon S3 桶的唯一桶名称。您可以通过调用 `uuid` 模块来生成唯一 ID。然后为用于将对象上传到存储桶的 `Key` 参数创建名称。

创建 `promise` 对象以调用 `createBucket` 服务对象的 `AWS.S3` 方法。收到成功响应时，创建将文本上传到新创建存储桶所需的参数。使用另一个 promise，调用 `putObject` 方法来将文本对象上传到存储桶。

```
// Load the SDK and UUID
var AWS = require("aws-sdk");
var uuid = require("uuid");

// Create unique bucket name
var bucketName = "node-sdk-sample-" + uuid.v4();
// Create name for uploaded object key
var keyName = "hello_world.txt";

// Create a promise on S3 service object
var bucketPromise = new AWS.S3({ apiVersion: "2006-03-01" })
  .createBucket({ Bucket: bucketName })
  .promise();

// Handle promise fulfilled/rejected states
bucketPromise
  .then(function (data) {
    // Create params for putObject call
    var objectParams = {
      Bucket: bucketName,
      Key: keyName,
      Body: "Hello World!",
    };
    // Create object upload promise
    var uploadPromise = new AWS.S3({ apiVersion: "2006-03-01" })
      .putObject(objectParams)
      .promise();
    uploadPromise.then(function (data) {
      console.log(
        "Successfully uploaded data to " + bucketName + "/" + keyName
      );
    });
  })
  .catch(function (err) {
    console.error(err, err.stack);
  });
```

此示例代码可在 [GitHub 上的此处](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascript/example_code/nodegetstarted/sample.js)找到。

## 步骤 5：运行示例


键入以下命令以运行示例。

```
node sample.js
```

如果上传成功，您将在命令行中看到一条确认消息。您还可在 [Amazon S3 控制台](https://console.amazonaws.cn/s3/)中找到存储桶和上传的文本对象。