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

# 开始使用 Amazon DocumentDB 弹性集群
<a name="elastic-get-started"></a>

这个入门部分将向您介绍如何创建和查询您的第一个弹性集群。

有许多连接和开始使用 Amazon DocumentDB 的方式。以下过程是用户开始使用我们强大文档数据库的最快捷、最简便的方法。本指南使用 [AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) 直接从 AWS 管理控制台连接和查询 Amazon DocumentDB 集群。符合 AWS 免费套餐条件的新客户可以免费使用亚马逊 DocumentDB CloudShell。如果您的 AWS CloudShell 环境或 Amazon DocumentDB 弹性集群使用了超出免费套餐范围的资源，则您需要为这些资源支付正常 AWS 费率。本指南将在不到 5 分钟的时间内让你开始使用亚马逊 DocumentDB。

**Topics**
+ [先决条件](#elastic-clusters-prerequisites)
+ [第 1 步：创建弹性集群](#elastic-get-started-clusters)
+ [步骤 2：连接到您的弹性集群](#ec-gs-connect)
+ [步骤 3：对您的集合分片，插入和查询数据](#elastic-get-started-shard)
+ [第 4 步：探索](#ec-gs-congrats)

## 先决条件
<a name="elastic-clusters-prerequisites"></a>

在创建第一个 Amazon DocumentDB 集群之前，您必须执行以下操作：

**已创建 Amazon Web Services（AWS）账户**  
在开始使用 Amazon DocumentDB 之前，您必须拥有 Amazon Web Services（AWS）账户。该 AWS 账户是免费的。您只需为使用的服务和资源付费。  
如果您没有 AWS 账户，请完成以下步骤来创建一个。  

**要注册 AWS 账户**

1. 打开[https://portal.aws.amazon.com/billing/注册。](https://portal.aws.amazon.com/billing/signup)

1. 按照屏幕上的说明操作。

   在注册时，将接到电话或收到短信，要求使用电话键盘输入一个验证码。

   当您注册时 AWS 账户，就会创建*AWS 账户根用户*一个。根用户有权访问该账户中的所有 AWS 服务 和资源。作为最佳安全实践，请为用户分配管理访问权限，并且只使用根用户来执行[需要根用户访问权限的任务](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks)。

**设置所需的 AWS Identity and Access Management (IAM) 权限。**  
要管理集群、实例和集群参数组等 Amazon DocumentDB 资源，需要 AWS 能够对您的请求进行身份验证的证书。有关更多信息，请参阅 [适用于 Amazon DocumentDB 的 Identity and Access Management](security-iam.md)。  

1. 在的搜索栏中 AWS 管理控制台，键入 IAM，然后在下拉菜单中选择 **IAM**。

1. 一旦您进入 IAM 控制台，就从导航窗格中选择**用户**。

1. 选择您的用户名。

1. 单击**添加更多权限**。

1. 选择**直接附加策略**。

1. 在搜索栏中键入 `AmazonDocDBElasticFullAccess`，并且一旦它出现在搜索结果中就选择之。

1. 单击**下一步**。

1. 单击**添加更多权限**。

****  
您的 AWS 账户在每个区域都包含一个默认 VPC。如果您选择使用 Amazon VPC，请按照《Amazon VPC 用户指南》**的[创建 Amazon VPC](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html) 主题中的步骤进行操作。

## 第 1 步：创建弹性集群
<a name="elastic-get-started-clusters"></a>

在本节中，我们将说明如何使用 AWS 管理控制台 或 AWS CLI 并按照以下说明创建全新的弹性集群。

------
#### [ Using the AWS 管理控制台 ]

使用 AWS 管理控制台创建弹性集群配置：

1. [登录 AWS 管理控制台，然后在 /docdb 上打开亚马逊文档数据库控制台。https://console.aws.amazon.com](https://console.aws.amazon.com/docdb)

1. 在** Amazon DocumentDB 管理控制台**上，**集群**下，选择**创建**。  
![\[弹性集群表，显示没有集群作为起点。\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/ec-gs-start.png)

1. 在**创建 Amazon DocumentDB 集群**页面上，在**集群类型**部分中选择**弹性集群**。  
![\[弹性集群的“集群类型”对话框，显示了基于实例的集群和弹性集群的选项。\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/ec-gs-type.png)

1. 在**配置**部分中，配置以下内容：

   1. 在**集群名称**字段中，输入唯一集群标识符（遵循字段下方的命名要求）。

   1. 在**分片计数**字段中，输入您在自身集群中想要的分片的数目。每个集群的最大分片数目为 32。
**注意**  
将对每个分片部署两个节点。两个节点将具有相同的分片容量。

   1. 在**分片实例数**字段中，选择想要与每个分片关联的副本实例的数量。分片实例的最大数量为 16 个，以 1 个为增量。所有副本实例都有相同的分片容量，具体定义见以下字段。出于测试目的，默认值 2 应已足够。
**注意**  
副本实例的数量适用于弹性集群中的所有分片。分片实例计数值为 1 表示有一个写入器实例，其他任何实例都是可用于读取和提高可用性的副本。出于测试目的，默认值 2 应已足够。

   1. 在**分片容量**字段中，选择要与每个分片实例关联的虚拟 CPUs (vCPUs) 数量。CPUs 每个分片实例的最大 v 数为 64。允许值为 2、4、8、16、32、64。出于测试目的，默认值 2 应已足够。

   1. 在**虚拟私有云（VPC）**字段中，从下拉列表中选择一个 VPC。

   1. 对于**子网**和** VPC 安全组**，您可以使用默认值或选择您选定的三个子网和多达三个** VPC 安全组**（最少一个）。  
![\[弹性集群配置对话框，显示了可配置字段。\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/ec-gs-configuration.png)

1. 在**身份验证**部分，在**用户名**字段中输入确定主用户登录名称的字符串。

   在**密码**字段中，输入符合说明的唯一密码，然后确认该密码。  
![\[“身份验证”部分，其中包含用户名和密码的输入字段。\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/ec-gs-authentication.png)

1. 在**加密**部分中，保留默认设置（**默认密钥**）。

   或者，您可以输入自己创建的 AWS KMS key ARN。有关更多信息，请参阅 [用于 Amazon DocumentDB 弹性集群的静态数据加密](elastic-encryption.md)。
**重要**  
必须对弹性集群启用加密。

1. 在**备份**部分，根据您的备份要求编辑字段。出于测试目的，您可以保留默认设置。  
![\[“备份”对话框的屏幕截图，其中显示了用于配置集群备份时段的步骤。\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/ec-gs-backup.png)

   1. **备份留存期**：在列表中，选择在删除此集群的自动备份前保留它们的天数。

   1. **备份时段**：设置 Amazon DocumentDB 要备份此集群的每日时间和持续时间。

      1. 如果要配置创建备份的时间和时长，请选择**选择时段**。

         **开始时间**：在第一个列表中，选择开始自动备份的开始时间小时 (UTC)。在第二个列表中，选择您希望自动备份开始的时间（分钟）。

         **持续时间**：在该列表中，选择要向创建自动备份分配的小时数。

      1. 如果想要 Amazon DocumentDB 选择创建备份的时间和时长，请选择**无首选项**。

1. 在**维护**部分中，选择对集群进行修改或修补的日期、时间和持续时间。出于测试目的，您可以保留默认设置。  
![\[“维护”部分，其中显示了维护时段选项。\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/ec-gs-maintenance.png)

1. 选择**创建集群**。

弹性集群现正在预配置。此过程可能需要数分钟完成。当弹性集群状态在**集群**列表中显示为**可用**时，可以连接到您的集群。

------
#### [ Using the AWS CLI ]

要使用创建弹性集群 AWS CLI，请使用带有以下参数的`create-cluster`操作：
+ **--cluster-name**：必填项。创建期间输入或上次修改的弹性扩展集群的当前名称。
+ **--shard-capacity**：必填项。CPUs 分配给每个分片的 v 数。最大值为 64。允许值为 2、4、8、16、32、64。
+ **--shard-count**：必填项。分配给集群的分片的数目。最大值为 32。
+ **--shard-instance-count**：可选。适用于此集群中所有分片的副本实例数量。最大值为 16。
+ **--admin-user-name**：必填项。与管理用户关联的用户名。
+ **--admin-user-password**：必填项。与管理用户关联的密码。
+ **--auth-type**：必填项。用于确定从何处获取用于访问弹性集群的密码的身份验证类型。有效类型为 `PLAIN_TEXT` 和 `SECRET_ARN`。
+ **--vpc-security-group-ids**：可选。要与此集群关联的 EC2 VPC 安全组的列表。
+ **--preferred-maintenance-window**：可选。配置可进行系统维护的每周时间范围（采用通用协调时间（UTC））。

  格式为：`ddd:hh24:mi-ddd:hh24:mi`。有效值 (ddd)：Mon、Tue、Wed、Thu、Fri、Sat、Sun

  默认值为每个 Amazon Web Services 区域 8 小时的时间段中随机选择的 30 分钟时段（随机选取周中的某天进行）。

  至少 30 分钟的窗口。
+ **--kms-key-id**：可选。配置已加密集群的 KMS 密钥标识符。

  KMS 密钥标识符是 AWS KMS 加密密钥的亚马逊资源名称 (ARN)。如果使用拥有用于加密新集群的 KMS 加密密钥的同一 Amazon Web Services 账户创建集群，则可以使用 KMS 密钥别名而不是 KMS 加密密钥的 ARN。

  如果中未指定加密密钥， KmsKeyId 且`StorageEncrypted`参数为真，则 Amazon DocumentDB 将使用您的默认加密密钥。
+ **--preferred-backup-window**：可选。创建自动备份的每日首选时间范围。默认值是从 8 小时的时间段中随机选择一个 30 分钟的窗口。 AWS 区域
+ **--backup-retention-period**：可选。自动备份的保留天数。默认值是 1。
+ **--storage-encrypted**：可选。配置集群是已加密还是未加密。

  `--no-storage-encrypted` 指定集群未加密。
+ **--subnet-ids**：可选。配置网络子网 ID。

在以下示例中，将每个 *user input placeholder* 替换为您自己的信息。

**注意**  
以下示例包括创建特定 KMS 密钥。要使用默认 KMS 密钥，请不要包含 `--kms-key-id` 参数。

对于 Linux、macOS 或 Unix：

```
aws docdb-elastic create-cluster \
     --cluster-name sample-cluster-123 \
     --shard-capacity 8 \
     --shard-count 4 \
     --shard-instance-count 3 \
     --auth-type PLAIN_TEXT \
     --admin-user-name testadmin \
     --admin-user-password testPassword \
     --vpc-security-group-ids ec-65f40350 \
     --kms-key-id arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 \
     --subnet-ids subnet-9253c6a3, subnet-9f1b5af9 \
     --preferred-backup-window 18:00-18:30 \ 
     --backup-retention-period 7
```

对于 Windows：

```
aws docdb-elastic create-cluster ^
     --cluster-name sample-cluster-123 ^
     --shard-capacity 8 ^
     --shard-count 4 ^
     --shard-instance-count 3 ^
     --auth-type PLAIN_TEXT ^
     --admin-user-name testadmin ^
     --admin-user-password testPassword ^
     --vpc-security-group-ids ec-65f40350 ^
     --kms-key-id arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 ^
     --subnet-ids subnet-9253c6a3, subnet-9f1b5af9 \
     --preferred-backup-window 18:00-18:30 \ 
     --backup-retention-period 7
```

------

## 步骤 2：连接到您的弹性集群
<a name="ec-gs-connect"></a>

使用连接到您的亚马逊 DocumentDB 弹性集群。 AWS CloudShell

1. 在 Amazon DocumentDB 管理控制台上的**集群**下，找到您创建的弹性集群。单击集群旁边的复选框，选择您的集群。  
![\[Amazon DocumentDB 集群管理界面，其中显示了弹性集群\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/ec-gs-cluster-new.png)

1. 单击**连接到集群**（位于**操作**下拉菜单旁边）。只有在您单击集群旁边的复选框并且集群的状态显示为**可用**后，才会启用此按钮。将出现 “ CloudShell **运行命令**” 屏幕。

1. 在**新环境名称**字段中，输入唯一名称，例如“test”，然后单击**创建并运行**。将自动为您的 Amazon DocumentDB 数据库配置 VPC 环境详细信息。  
![\[弹性集群 CloudShell 运行命令屏幕请求新的环境名称\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/ec-gs-run-command.png)

1. 出现提示时，输入您在“步骤 1：创建 Amazon DocumentDB 弹性集群”（子步骤 5）中创建的密码。  
![\[弹性集群 CloudShell 屏幕请求用户密码\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/ec-gs-cs-password.png)

   在您输入密码并且提示符变成 `direct: mongos] <env-name>>` 后，表示您已成功连接到您的 Amazon DocumentDB 集群

**注意**  
有关对 流进行问题排查的更多信息，请参阅 [Amazon DocumentDB 问题排查](https://docs.aws.amazon.com/documentdb/latest/developerguide/troubleshooting.html)。

## 步骤 3：对您的集合分片，插入和查询数据
<a name="elastic-get-started-shard"></a>

弹性集群增加对 Amazon DocumentDB 中分片过程的支持。既然您已连接到集群，您可以对集群分片、插入数据并运行数个查询。

1. 要对集合分片，请输入以下：

   ```
   sh.shardCollection("db.Employee1" , { "Employeeid" : "hashed" })
   ```

1. 要插入单个文档，请输入以下内容：

   ```
   db.Employee1.insertOne({"Employeeid":1, "Name":"Joe", "LastName": "Bruin", "level": 1 })
   ```

   以下输出显示：

   ```
   WriteResult({ "nInserted" : 1 })
   ```

1. 要阅读您编写的文档，请输入以下`findOne()`命令（它返回单一文档）：

   ```
   db.Employee1.findOne()
   ```

   以下输出显示：

   ```
   {
   "_id" : ObjectId("61f344e0594fe1a1685a8151"),
   "EmployeeID" : 1,
   "Name" : "Joe",
   "LastName" : "Bruin",
   "level" : 1
   }
   ```

1. 要执行若干更多查询，请考虑游戏配制文件用例。首先，将几个条目插入标题为“员工”的集合。输入以下信息：

   ```
   db.profiles.insertMany([ { "_id": 1, "name": "Matt", "status": "active", "level": 12, "score": 202 }, 
        { "_id": 2, "name": "Frank", "status": "inactive", "level": 2, "score": 9 }, 
        { "_id": 3, "name": "Karen", "status": "active", "level": 7, "score": 87 }, 
        { "_id": 4, "name": "Katie", "status": "active", "level": 3, "score": 27 }
   ])
   ```

   以下输出显示：

   ```
   { acknowledged: true, 
        insertedIds: { 
           '0': ObjectId('679d02cd6b5a0581be78bcbd'),
           '1': ObjectId('679d02cd6b5a0581be78bcbe'),
           '2': ObjectId('679d02cd6b5a0581be78bcbf'),
           '3': ObjectId('679d02cd6b5a0581be78bcc0')
       }
   }
   ```

1. 要返回配制文件集合中的所有文档，请输入`find` () 命令：

   ```
   db.Employee.find()
   ```

   您在步骤 4 中输入的数据显示。

1. 要查询单一文档，请纳入过滤器（例如：“Katie”）。输入以下信息：

   ```
   db.Employee.find({name: "Katie"})
   ```

    以下输出显示：

   ```
   [

      {

        _id: ObjectId('679d02cd6b5a0581be78bcc0'),

        Employeeid: 4,

        name: 'Katie',

        lastname: 'Schaper',

        level: 3

      }

   ]
   ```

1. 要查找配置文件并对其进行修改，请输入`findAndModify`命令。在此示例中，给予员工“Matt”更高等级，即 “14”：

   ```
   db.Employee.findAndModify({     
       query: { "Employeeid" : 1, "name" : "Matt"},     
       update: { "Employeeid" : 1, "name" : "Matt", "lastname" : "Winkle", "level" : 14 } 
   })
   ```

   以下输出显示（请注意，级别尚未更改）：

   ```
   {

      _id: ObjectId('679d02cd6b5a0581be78bcbd'),

      Employeeid: 1,

      name: 'Matt',

      lastname: 'Winkle',

      level: 12

   }
   ```

1. 要验证级别提高，请输入以下查询：

   ```
   db.Employee.find({name: "Matt"})
   ```

   以下输出显示：

   ```
   [
      {

      _id: ObjectId('679d02cd6b5a0581be78bcbd'),

      Employeeid: 1,

      name: 'Matt',

      lastname: 'Winkle',

      level: 14

      }
   ]
   ```

## 第 4 步：探索
<a name="ec-gs-congrats"></a>

恭喜您！您已成功完成 Amazon DocumentDB 弹性集群的入门过程。

接下来做什么？ 了解如何充分利用这个数据库及其热门功能：
+  [Amazon DocumentDB 弹性集群最佳实践](elastic-best-practices.md) 
+  [管理 Amazon DocumentDB 弹性集群](elastic-managing.md) 

**注意**  
您在此入门过程中创建的弹性集群将继续产生费用，除非您将其删除。有关指导，请参阅[删除弹性集群](elastic-managing.md#elastic-delete)。