本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 `cqlsh` 連線至 Amazon Keyspaces
<a name="programmatic.cqlsh"></a>

若要使用 連線到 Amazon Keyspaces`cqlsh`，您可以使用 `cqlsh-expansion`。這是一個工具組，其中包含常見的 Apache Cassandra 工具，例如 `cqlsh`和針對 Amazon Keyspaces 預先設定的協助程式，同時保持與 Apache Cassandra 的完整相容性。`cqlsh-expansion` 整合了 SigV4 身分驗證外掛程式，並可讓您使用 IAM 存取金鑰來連線，而不是使用者名稱和密碼。您只需要安裝`cqlsh`指令碼來建立連線，而不是完整的 Apache Cassandra 分佈，因為 Amazon Keyspaces 是無伺服器。此輕量型安裝套件包含 `cqlsh-expansion`和傳統指令碼，您可以在任何支援 Python 的平台上安裝這些`cqlsh`指令碼。

**注意**  
`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 使用此憑證來設定與 Transport Layer Security (TLS) 的安全連線。傳輸中加密可在資料往返 Amazon Keyspaces 時加密資料，提供多一層的資料保護。如需憑證的詳細資訊，請參閱 [如何手動設定 TLS 的`cqlsh`連線](#encrypt_using_tls)。

   若要先檢閱指令碼，您可以在 的 Github 儲存庫中存取指令碼[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)。

   若要使用指令碼，您可以執行下列命令。

   ```
   cqlsh-expansion.init
   ```
**注意**  
當您`cqlsh-expansion`使用 解除安裝 時，不會移除安裝後指令碼建立的目錄和檔案`pip uninstall`，而且必須手動刪除。

**使用 連線至 Amazon Keyspaces `cqlsh-expansion`**

1. 設定您的 AWS 區域 並將其新增為使用者環境變數。

   若要將預設區域新增為 Unix 系統上的環境變數，您可以執行下列命令。在此範例中，我們使用 `us-east-1`。

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

   如需如何設定環境變數的詳細資訊，包括其他平台的 ，請參閱[如何設定環境變數](https://docs.aws.amazon.com/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 的 AWS 登入資料](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.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html#envvars-set)。
**注意**  
如果您是從 Amazon EC2 執行個體連線，您也需要在安全群組中設定傳出規則，以允許從執行個體到 Amazon Keyspaces 的流量。如需如何檢視和編輯 EC2 傳出規則的詳細資訊，請參閱《[Amazon EC2 使用者指南》中的將規則新增至安全群組](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/working-with-security-groups.html#adding-security-group-rule)。

1. 使用 `cqlsh-expansion`和 SigV4 身分驗證連線至 Amazon Keyspaces。

   若要使用 連線到 Amazon Keyspaces`cqlsh-expansion`，您可以使用下列命令。請務必將服務端點取代為您區域的正確端點。

   ```
   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 只接受使用 Transport Layer Security (TLS) 的安全連線。您可以使用 `cqlsh-expansion`公用程式來自動為您下載憑證，並安裝預先設定的`cqlshrc`組態檔案。如需詳細資訊，請參閱此頁面[使用 `cqlsh-expansion` 連線至 Amazon Keyspaces](#using_cqlsh)上的 。

如果您想要下載憑證並手動設定連線，您可以使用下列步驟執行此操作。

1.  下載下列數位憑證，並將檔案儲存在本機或主目錄中。

   1. AmazonRootCA1

   1. AmazonRootCA2

   1. AmazonRootCA3

   1. AmazonRootCA4

   1. Starfield Class 2 根目錄 （選用 – 用於回溯相容性）

   若要下載憑證，您可以使用下列命令。

   ```
   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 類別 2 CA 為基礎的 TLS 憑證。 AWS 正在將所有 遷移 AWS 區域 至根據 Amazon Trust Services (Amazon 根 CAs 發行的憑證。在此轉換期間，請將用戶端設定為信任 Amazon 根 CAs1–4 和 Starfield 根，以確保所有區域的相容性。

1. 使用範例中的名稱 *keyspaces-bundle.pem*，將所有下載的憑證合併成單一`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
   ```