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

# 使用 `cqlsh` 连接 Amazon Keyspaces
<a name="programmatic.cqlsh"></a>

要使用 `cqlsh` 连接 Amazon Keyspaces，您可以使用 `cqlsh-expansion`。该工具包包含常用的 Apache Cassandra 工具（例如 `cqlsh` 和帮助程序），能够对 Amazon Keyspaces 进行预配置，同时保持与 Apache Cassandra 的完全兼容。`cqlsh-expansion` 与 SigV4 身份验证插件集成，让您可以使用 IAM 访问密钥而不是用户名和密码进行连接。您只需安装 `cqlsh` 脚本即可建立连接，无需安装完整的 Apache Cassandra 发行版，因为 Amazon Keyspaces 是无服务器的。这一轻量级安装包包括 `cqlsh-expansion` 和经典 `cqlsh` 脚本，可以在任何支持 Python 的平台上安装。

**注意**  
`Murmur3Partitioner` 是 Amazon Keyspaces 和 `cqlsh-expansion` 的推荐分区程序。`cqlsh-expansion` 不支持 Amazon Keyspaces `DefaultPartitioner`。有关更多信息，请参阅 [使用 Amazon Keyspaces 中的分区程序](working-with-partitioners.md)。

有关 `cqlsh` 的一般信息，请参阅 [`cqlsh`：CQL Shell](https://cassandra.apache.org/doc/latest/cassandra/managing/tools/cqlsh.html)。

**Topics**
+ [

## 使用 `cqlsh-expansion` 连接 Amazon Keyspaces
](#using_cqlsh)
+ [

## 如何为 TLS 手动配置 `cqlsh` 连接
](#encrypt_using_tls)

## 使用 `cqlsh-expansion` 连接 Amazon Keyspaces
<a name="using_cqlsh"></a>

**安装和配置 `cqlsh-expansion`**

1. 要安装 `cqlsh-expansion` Python 软件包，您可以运行 `pip` 命令。该命令将使用 *pip 安装*在您的设备上安装 `cqlsh-expansion` 脚本以及一个包含依赖项列表的文件。`--user flag` 会告诉 `pip` 使用 Python 用户为平台安装目录。在基于 Unix 的系统上，应安装 `~/.local/` 目录。

   您需要使用 Python 3 来安装 `cqlsh-expansion`，要弄清楚您的 Python 版本，可使用 `Python --version`。要进行安装，您可以运行以下命令。

   ```
   python3 -m pip install --user cqlsh-expansion
   ```

   输出应如下所示：

   ```
   Collecting cqlsh-expansion
     Downloading cqlsh_expansion-0.9.6-py3-none-any.whl (153 kB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 153.7/153.7 KB 3.3 MB/s eta 0:00:00
   Collecting cassandra-driver
     Downloading cassandra_driver-3.28.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (19.1 MB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 19.1/19.1 MB 44.5 MB/s eta 0:00:00
   Requirement already satisfied: six>=1.12.0 in /usr/lib/python3/dist-packages (from cqlsh-expansion) (1.16.0)
   Collecting boto3
     Downloading boto3-1.29.2-py3-none-any.whl (135 kB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 135.8/135.8 KB 17.2 MB/s eta 0:00:00
   Collecting cassandra-sigv4>=4.0.2
     Downloading cassandra_sigv4-4.0.2-py2.py3-none-any.whl (9.8 kB)
   Collecting botocore<1.33.0,>=1.32.2
     Downloading botocore-1.32.2-py3-none-any.whl (11.4 MB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 11.4/11.4 MB 60.9 MB/s eta 0:00:00
   Collecting s3transfer<0.8.0,>=0.7.0
     Downloading s3transfer-0.7.0-py3-none-any.whl (79 kB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 79.8/79.8 KB 13.1 MB/s eta 0:00:00
   Collecting jmespath<2.0.0,>=0.7.1
     Downloading jmespath-1.0.1-py3-none-any.whl (20 kB)
   Collecting geomet<0.3,>=0.1
     Downloading geomet-0.2.1.post1-py3-none-any.whl (18 kB)
   Collecting python-dateutil<3.0.0,>=2.1
     Downloading python_dateutil-2.8.2-py2.py3-none-any.whl (247 kB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 247.7/247.7 KB 33.1 MB/s eta 0:00:00
   Requirement already satisfied: urllib3<2.1,>=1.25.4 in /usr/lib/python3/dist-packages (from botocore<1.33.0,>=1.32.2->boto3->cqlsh-expansion) (1.26.5)
   Requirement already satisfied: click in /usr/lib/python3/dist-packages (from geomet<0.3,>=0.1->cassandra-driver->cqlsh-expansion) (8.0.3)
   Installing collected packages: python-dateutil, jmespath, geomet, cassandra-driver, botocore, s3transfer, boto3, cassandra-sigv4, cqlsh-expansion
     WARNING: The script geomet is installed in '/home/ubuntu/.local/bin' which is not on PATH.
     Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
     WARNING: The scripts cqlsh, cqlsh-expansion and cqlsh-expansion.init are installed in '/home/ubuntu/.local/bin' which is not on PATH.
     Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
   Successfully installed boto3-1.29.2 botocore-1.32.2 cassandra-driver-3.28.0 cassandra-sigv4-4.0.2 cqlsh-expansion-0.9.6 geomet-0.2.1.post1 jmespath-1.0.1 python-dateutil-2.8.2 s3transfer-0.7.0
   ```

   如果安装目录不在 `PATH` 中，则需要按照操作系统的说明进行添加。以下是适用于 Ubuntu Linux 的一个示例。

   ```
   export PATH="$PATH:/home/ubuntu/.local/bin"
   ```

   要确认软件包已经安装，您可以运行以下命令。

   ```
   cqlsh-expansion --version
   ```

   输出应如下所示：

   ```
   cqlsh 6.1.0
   ```

1. 要配置 `cqlsh-expansion`，您可以运行安装后脚本来自动完成以下步骤：

   1. 在用户主目录下创建 `.cassandra` 目录（如果该目录尚不存在）。

   1. 将预配置的 `cqlshrc` 配置文件复制到 `.cassandra` 目录。

   1. 将合并后的证书文件复制到`.cassandra`目录中。Amazon Keyspaces 使用此证书通过传输层安全性协议 (TLS) 配置安全连接。传输中加密可在数据进出 Amazon Keyspaces 时对其进行加密，从而提供额外一层数据保护。有关证书的更多信息，请参阅[如何为 TLS 手动配置 `cqlsh` 连接](#encrypt_using_tls)。

   要先查看脚本，您可以访问 [https://github.com/aws-samples/amazon-keyspaces-toolkit/blob/master/cqlsh-expansion/cqlsh_expansion/post_install.py](https://github.com/aws-samples/amazon-keyspaces-toolkit/blob/master/cqlsh-expansion/cqlsh_expansion/post_install.py) 中的 Github 代码库中。

   要使用脚本，您可以运行以下命令。

   ```
   cqlsh-expansion.init
   ```
**注意**  
使用 `pip uninstall` 卸载 `cqlsh-expansion` 时，安装后脚本创建的目录和文件不会随之删除，必须要手动删除。

**使用 `cqlsh-expansion` 连接 Amazon Keyspaces**

1. 配置您的 Amazon Web Services 区域 并将其添加为用户环境变量。

   要在基于 Unix 的系统上将默认区域添加为环境变量，您可以运行以下命令。在这个例子中，我们使用`us-east-1`。

   ```
   export AWS_DEFAULT_REGION=us-east-1
   ```

   要详细了解如何设置环境变量（包括其他平台），请参阅[如何设置环境变量](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-envvars.html#envvars-set)。

1. 找到您的服务端点。

   为您的区域选择合适的服务端点。要查看 Amazon Keyspaces 的可用端点，请参阅 [Amazon Keyspaces 的服务端点](programmatic.endpoints.md)。在本示例中，我们使用的端点是 `cassandra.us-east-1.amazonaws.com`。

1. 配置身份验证方法。

   要增强安全性，建议您使用 IAM 访问密钥（IAM 用户、角色和联合身份）进行连接。

   在使用 IAM 访问密钥进行连接之前，您需要完成以下步骤：

   1. 创建 IAM 用户，或者遵循最佳实践创建一个 IAM 用户可以代入的 IAM 角色。有关如何创建 IAM 访问密钥的更多信息，请参阅[为 Amazon Keyspaces 创建和配置 Amazon 证书](access.credentials.md)。

   1. 创建一项 IAM 策略，至少向角色（或 IAM 用户）授予对 Amazon Keyspaces 的只读访问权限。要详细了解 IAM 用户或角色连接 Amazon Keyspaces 所需的权限，请参阅[访问 Amazon Keyspaces 表](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-access-one-table)。

   1. 将 IAM 用户的访问密钥添加到用户的环境变量中，如下例中所示。

      ```
      export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
      export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
      ```

      要详细了解如何设置环境变量（包括其他平台），请参阅[如何设置环境变量](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-envvars.html#envvars-set)。
**注意**  
如果您从 Amazon EC2 实例进行连接，则还需要在安全组中配置一条出站规则，允许流量从该实例流入 Amazon Keyspaces。有关如何查看和编辑 EC2 出站规则的更多信息，请参阅《Amazon EC2 用户指南》中的[向安全组添加规则](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/working-with-security-groups.html#adding-security-group-rule)。

1. 使用 `cqlsh-expansion` 和 SigV4 身份验证连接到 Amazon Keyspaces。

   要使用 `cqlsh-expansion` 连接到 Amazon Keyspaces，您可以使用以下命令。确保将服务端点替换为您所在区域的正确端点。

   ```
   cqlsh-expansion cassandra.us-east-1.amazonaws.com 9142 --ssl
   ```

   如果连接成功，您应该会看到类似于以下内容的输出：

   ```
   Connected to Amazon Keyspaces at cassandra.us-east-1.amazonaws.com:9142
   [cqlsh 6.1.0 | Cassandra 3.11.2 | CQL spec 3.4.4 | Native protocol v4]
   Use HELP for help.
   cqlsh current consistency level is ONE.
   cqlsh>
   ```

   如果遇到连接错误，请参见[我无法使用 cqlsh 连接到 Amazon Keyspaces](troubleshooting.connecting.md#troubleshooting.connection.cqlsh) 来获取疑难解答信息。
   + 使用服务特定凭证连接 Amazon Keyspaces。

     要使用 Cassandra 用于身份验证的传统用户名和密码组合进行连接，您必须首先为 Amazon Keyspaces 创建服务特定凭证，如[创建用于通过编程方式访问 Amazon Keyspaces 的服务特定凭证。](programmatic.credentials.ssc.md)中所述。您还必须向该用户授予访问 Amazon Keyspaces 的权限，更多信息请参阅[访问 Amazon Keyspaces 表](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-access-one-table)。

     为用户创建服务特定凭证和权限后，您必须更新 `cqlshrc` 文件，该文件通常位于用户目录路径 `~/.cassandra/` 中。在 `cqlshrc` 文件中，转到 Cassandra `[authentication]` 部分，使用 ";" 字符注释掉 `[auth_provider]` 下的 SigV4 模块和类，如以下示例所示。

     ```
     [auth_provider]
     
     ; module = cassandra_sigv4.auth
     
     ; classname = SigV4AuthProvider
     ```

     更新 `cqlshrc` 文件后，您可以使用以下命令通过服务特定凭证连接 Amazon Keyspaces。

     ```
     cqlsh-expansion cassandra.us-east-1.amazonaws.com 9142 -u myUserName -p myPassword --ssl
     ```

**清理**
+ 要删除 `cqlsh-expansion` 软件包，您可以使用 `pip uninstall` 命令。

  ```
  pip3 uninstall cqlsh-expansion
  ```

  `pip3 uninstall` 命令不会删除安装后脚本创建的目录和相关文件。要删除安装后脚本创建的文件夹和文件，您可以删除 `.cassandra` 目录。

## 如何为 TLS 手动配置 `cqlsh` 连接
<a name="encrypt_using_tls"></a>

Amazon Keyspaces 只接受使用传输层安全性协议 (TLS) 的安全连接。您可以使用该`cqlsh-expansion`实用程序自动为您下载证书并安装预配置的`cqlshrc`配置文件。有关更多信息，请参阅本页上的[使用 `cqlsh-expansion` 连接 Amazon Keyspaces](#using_cqlsh)。

如果要下载证书并手动配置连接，则可以使用以下步骤进行操作。

1.  下载以下数字证书并将文件保存在本地或您的主目录中。

   1. AmazonRootCA1

   1. AmazonRootCA2

   1. AmazonRootCA3

   1. AmazonRootCA4

   1. Starfield Class 2 Root（可选 — 为了向后兼容）

   要下载证书，您可以使用以下命令。

   ```
   curl -O https://www.amazontrust.com/repository/AmazonRootCA1.pem
   curl -O https://www.amazontrust.com/repository/AmazonRootCA2.pem
   curl -O https://www.amazontrust.com/repository/AmazonRootCA3.pem
   curl -O https://www.amazontrust.com/repository/AmazonRootCA4.pem
   curl -O https://certs.secureserver.net/repository/sf-class2-root.crt
   ```
**注意**  
Amazon Keyspaces 之前使用锚定在 Starfield Class 2 CA 上的 TLS 证书。 Amazon 正在将所有证书全部迁移 Amazon Web Services 区域 到根据亚马逊信任服务（Amazon Root CAs 1—4）颁发的证书。在此过渡期间，将客户端配置为同时信任 Amazon Root CAs 1—4 和 Starfield 根，以确保所有区域之间的兼容性。

1. 将所有下载的证书合并到一个`pem`文件中，其名称与我们的示例*keyspaces-bundle.pem*中的名称相同。您可以使用以下 命令进行这项操作：记下文件的路径，稍后需要这个。

   ```
   cat AmazonRootCA1.pem \
    AmazonRootCA2.pem \
    AmazonRootCA3.pem \
    AmazonRootCA4.pem \
    sf-class2-root.crt \
    > keyspaces-bundle.pem
   ```

1. 打开 Cassandra 主目录下的 `cqlshrc` 配置文件（例如 `${HOME}/.cassandra/cqlshrc`），然后添加以下行。

   ```
   [connection]
   port = 9142
   factory = cqlshlib.ssl.ssl_transport_factory
   
   [ssl]
   validate = true
   certfile =  path_to_file/keyspaces-bundle.pem
   ```