As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Usar `cqlsh` para se conectar ao Amazon Keyspaces
<a name="programmatic.cqlsh"></a>

Para se conectar ao Amazon Keyspaces usando `cqlsh`, você pode usar o `cqlsh-expansion`. Este é um kit de ferramentas que contém ferramentas comuns do Apache Cassandra, como `cqlsh`, e auxiliares pré-configurados para o Amazon Keyspaces, mantendo total compatibilidade com o Apache Cassandra. O `cqlsh-expansion` integra o plug-in de autenticação SigV4 e permite que você se conecte usando chaves de acesso do IAM em vez de nome de usuário e senha. Você só precisa instalar os scripts `cqlsh` para fazer uma conexão e não a distribuição completa do Apache Cassandra, porque o Amazon Keyspaces é uma tecnologia sem servidor. Esse pacote de instalação leve inclui os `cqlsh-expansion` e os scripts clássicos `cqlsh` que você pode instalar em qualquer plataforma compatível com Python.

**nota**  
`Murmur3Partitioner` é o particionador recomendado para o Amazon Keyspaces e o `cqlsh-expansion`. O `cqlsh-expansion` não é compatível com o Amazon Keyspaces `DefaultPartitioner`. Para obter mais informações, consulte [Como trabalhar com particionadores no Amazon Keyspaces](working-with-partitioners.md).

Para obter informações gerais sobre o `cqlsh`, consulte [`cqlsh`: shell do CQL](https://cassandra.apache.org/doc/latest/cassandra/managing/tools/cqlsh.html).

**Topics**
+ [Usar a `cqlsh-expansion` para se conectar ao Amazon Keyspaces](#using_cqlsh)
+ [Como configurar manualmente as conexões `cqlsh` para o TLS](#encrypt_using_tls)

## Usar a `cqlsh-expansion` para se conectar ao Amazon Keyspaces
<a name="using_cqlsh"></a>

**Instalar e configurar a `cqlsh-expansion`**

1. Para instalar o pacote `cqlsh-expansion` Python, você pode executar um comando `pip`. Isso instala os scripts `cqlsh-expansion` em sua máquina usando uma *instalação pip* e um arquivo contendo uma lista de dependências. O `--user flag` instrui `pip` a usar o diretório de instalação do usuário do Python para sua plataforma. Em um sistema baseado em Unix, esse deve ser o diretório `~/.local/`.

   Você precisa do Python 3 para instalar o `cqlsh-expansion`. Para descobrir sua versão do Python, use `Python --version`. Para instalar, é possível executar o comando a seguir.

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

   A saída deve ser semelhante a esta.

   ```
   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
   ```

   Se o diretório de instalação não estiver no`PATH`, você precisará adicioná-lo seguindo as instruções do seu sistema operacional. Abaixo está um exemplo para o Ubuntu Linux.

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

   Para confirmar se o pacote foi instalado, você pode executar o comando a seguir.

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

   A saída deve ser algo parecido com isso.

   ```
   cqlsh 6.1.0
   ```

1. Para configurar o `cqlsh-expansion`, você pode executar um script de pós-instalação para concluir automaticamente as seguintes etapas:

   1. Crie o diretório `.cassandra` no diretório inicial do usuário se ele ainda não existir.

   1. Copie um arquivo `cqlshrc` de configuração pré-configurado no diretório `.cassandra`.

   1. Copie o arquivo de certificado combinado no `.cassandra` diretório. O Amazon Keyspaces usa esse certificado para configurar a conexão segura com o Transport Layer Security (TLS). A criptografia em trânsito fornece uma camada adicional de proteção de dados ao criptografar seus dados à medida que eles viajam de e para o Amazon Keyspaces. Para obter mais informações sobre certificados, consulte[Como configurar manualmente as conexões `cqlsh` para o TLS](#encrypt_using_tls).

   Para revisar o script primeiro, você pode acessá-lo no repositório do Github em [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).

   Para usar o script, você pode executar o seguinte comando. 

   ```
   cqlsh-expansion.init
   ```
**nota**  
O diretório e o arquivo criados pelo script de pós-instalação não são removidos quando você desinstala o `cqlsh-expansion` usando `pip uninstall`, e precisam ser excluídos manualmente.

**Conectar-se ao Amazon Keyspaces usando `cqlsh-expansion`**

1. Configure seu Região da AWS e adicione-o como uma variável de ambiente do usuário.

   Para adicionar sua região padrão como uma variável de ambiente em um sistema baseado em Unix, você pode executar o comando a seguir. Para este exemplo, usamos`us-east-1`.

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

   Para obter mais informações sobre como definir variáveis de ambiente, inclusive para outras plataformas, consulte [Como definir variáveis de ambiente](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html#envvars-set).

1. Encontre seu endpoint.

   Escolha o endpoint de serviço apropriado para sua região. Para analisar os endpoints disponíveis para o Amazon Keyspaces, consulte [Endpoints de serviço para Amazon Keyspaces](programmatic.endpoints.md). Para este exemplo, usamos o endpoint `cassandra.us-east-1.amazonaws.com`.

1. Configurar o modo de autenticação.

   A conexão com as chaves de acesso do IAM (usuários, perfis e identidades federadas do IAM) é o método recomendado para aumentar a segurança. 

   Antes de se conectar com as chaves de acesso do IAM, você precisa concluir as seguintes etapas:

   1. Crie um usuário do IAM ou siga as melhores práticas e crie um perfil do IAM que os usuários do IAM possam assumir. Para obter mais informações sobre como criar uma chave de acesso do IAM, consulte [Crie e configure AWS credenciais para o Amazon Keyspaces](access.credentials.md).

   1. Crie uma política do IAM que conceda ao perfil (ou ao usuário do IAM) no mínimo o acesso somente leitura ao Amazon Keyspaces. Para obter mais informações sobre as permissões necessárias para que o usuário ou o perfil do IAM se conecte ao Amazon Keyspaces, consulte [Como acessar as tabelas do Amazon Keyspaces](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-access-one-table).

   1. Adicione as chaves de acesso do usuário do IAM às variáveis de ambiente do usuário, conforme mostrado no exemplo a seguir.

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

      Para obter mais informações sobre como definir variáveis de ambiente, inclusive para outras plataformas, consulte [Como definir variáveis de ambiente](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html#envvars-set).
**nota**  
Se você estiver se conectando a partir de uma instância do Amazon EC2, também precisará configurar uma regra de saída no grupo de segurança que permita o tráfego da instância para o Amazon Keyspaces. Para obter mais informações sobre como exibir e editar regras de saída do EC2, consulte [Adicionar regras a um grupo de segurança no Guia do usuário do Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/working-with-security-groups.html#adding-security-group-rule).

1. Conectar-se ao Amazon Keyspaces usando a `cqlsh-expansion` e a autenticação SigV4.

   Para se conectar ao Amazon Keyspaces com a `cqlsh-expansion`, você pode usar o comando a seguir. Certifique-se de substituir o endpoint de serviço pelo endpoint correto para sua região.

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

   Se a conexão for bem-sucedida, você verá um resultado semelhante a este:

   ```
   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>
   ```

   Se você encontrar um erro de conexão, consulte [Não consigo me conectar ao Amazon Keyspaces com o cqlsh](troubleshooting.connecting.md#troubleshooting.connection.cqlsh) para obter informações sobre solução de problemas.
   + Conectar-se ao Amazon Keyspaces com credenciais específicas do serviço.

     Para se conectar à combinação tradicional de nome de usuário e senha que o Cassandra usa para autenticação, você deve primeiro criar credenciais específicas do serviço para o Amazon Keyspaces, conforme descrito em [Crie credenciais específicas do serviço para acesso programático ao Amazon Keyspaces](programmatic.credentials.ssc.md). Você também precisa conceder a esse usuário permissões para acessar o Amazon Keyspaces. Para obter mais informações, consulte [Como acessar as tabelas do Amazon Keyspaces](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-access-one-table). 

     Depois de criar credenciais e permissões específicas do serviço para o usuário, você deve atualizar o arquivo `cqlshrc`, normalmente encontrado no caminho do diretório do usuário `~/.cassandra/`. No arquivo `cqlshrc`, vá para a seção `[authentication]` do Cassandra e comente o módulo e a classe SigV4 em `[auth_provider]` usando o caractere “;”, conforme mostrado no exemplo a seguir. 

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

     Depois de atualizar o arquivo `cqlshrc`, você pode se conectar ao Amazon Keyspaces com credenciais específicas do serviço usando o comando a seguir.

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

**Limpeza**
+ Para remover o pacote `cqlsh-expansion`, é possível usar o comando `pip uninstall`.

  ```
  pip3 uninstall cqlsh-expansion
  ```

  O comando `pip3 uninstall` não remove o diretório e os arquivos relacionados criados pelo script de pós-instalação. Para remover a pasta e os arquivos criados pelo script de pós-instalação, você pode excluir o diretório `.cassandra`.

## Como configurar manualmente as conexões `cqlsh` para o TLS
<a name="encrypt_using_tls"></a>

O Amazon Keyspaces só aceita conexões seguras usando Transport Layer Security (TLS). Você pode usar o `cqlsh-expansion` utilitário que baixa automaticamente os certificados para você e instala um arquivo de `cqlshrc` configuração pré-configurado. Para obter mais informações sobre isso, consulte [Usar a `cqlsh-expansion` para se conectar ao Amazon Keyspaces](#using_cqlsh) nesta página. 

Se quiser baixar os certificados e configurar a conexão manualmente, você pode fazer isso usando as etapas a seguir. 

1.  Baixe os seguintes certificados digitais e salve os arquivos localmente ou em seu diretório pessoal.

   1. AmazonRootCA1

   1. AmazonRootCA2

   1. AmazonRootCA3

   1. AmazonRootCA4

   1. Starfield Class 2 Root (opcional — para compatibilidade com versões anteriores)

   Para baixar os certificados, você pode usar os seguintes comandos.

   ```
   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
   ```
**nota**  
O Amazon Keyspaces usava anteriormente certificados TLS ancorados na CA Starfield Class 2. AWS está migrando tudo Regiões da AWS para certificados emitidos pelo Amazon Trust Services (Amazon Root CAs 1—4). Durante essa transição, configure os clientes para que confiem tanto na Amazon Root CAs 1—4 quanto na raiz Starfield para garantir a compatibilidade em todas as regiões.

1. Combine todos os certificados baixados em um único `pem` arquivo com o nome *keyspaces-bundle.pem* em nossos exemplos. Você pode fazer isso executando o seguinte comando : Anote o caminho para o arquivo, você precisará disso mais tarde.

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

1. Abra o arquivo `cqlshrc` de configuração no diretório inicial do Cassandra, por exemplo, `${HOME}/.cassandra/cqlshrc`, e adicione as linhas a seguir.

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