Uso de un controlador de cliente Java de Cassandra para acceder mediante programación a Amazon Keyspaces - Amazon Keyspaces (para Apache Cassandra)
Antes de empezarUso del controlador Java DataStax Complemento de autenticación para Java 4.xComplemento de autenticación para Java 3.x

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Uso de un controlador de cliente Java de Cassandra para acceder mediante programación a Amazon Keyspaces

En esta sección le mostramos cómo conectarse a Amazon Keyspaces mediante un controlador de cliente Java.

nota

Actualmente, Java 17 y el controlador DataStax Java 4.17 solo son compatibles con la versión beta. Para obtener más información, consulte https://docs.datastax.com/en/developer/java-driver/4.17/upgrade_guide/.

Para proporcionar a los usuarios y a las aplicaciones credenciales de acceso programático a los recursos de Amazon Keyspaces, puede realizar cualquiera de las siguientes acciones:

  • Cree credenciales específicas del servicio que estén asociadas a un usuario AWS Identity and Access Management () IAM específico.

  • Para mejorar la seguridad, recomendamos crear claves de IAM acceso para las IAM identidades que se utilizan en todos los AWS servicios. El complemento de autenticación SiGv4 de Amazon Keyspaces para los controladores de clientes de Cassandra le permite autenticar las llamadas a Amazon Keyspaces IAM mediante claves de acceso en lugar del nombre de usuario y la contraseña. Para obtener más información, consulte Crear y configurar AWS credenciales para Amazon Keyspaces.

nota

Para ver un ejemplo de cómo utilizar Amazon Keyspaces con Spring Boot, consulte https://github.com/aws-samples/amazon-keyspaces-examples/tree/main/java/datastax-v4/spring.

Antes de empezar

Para conectarse a Amazon Keyspaces, debe completar las siguientes tareas antes de poder comenzar.

  1. Amazon Keyspaces requiere el uso de Transport Layer Security (TLS) para proteger las conexiones con los clientes.

    1. Descargue el certificado digital de Starfield utilizando el siguiente comando y guarde sf-class2-root.crt localmente o en su directorio de inicio.

      curl https://certs.secureserver.net/repository/sf-class2-root.crt -O
      nota

      También puede utilizar el certificado digital de Amazon para conectarse a Amazon Keyspaces, y puede seguir haciéndolo si su cliente se conecta a Amazon Keyspaces correctamente. El certificado de Starfield proporciona compatibilidad retroactiva adicional para los clientes que utilicen autoridades de certificación más antiguas.

    2. Convierta el certificado digital de Starfield en un trustStore archivo.

      openssl x509 -outform der -in sf-class2-root.crt -out temp_file.der
keytool -import -alias cassandra -keystore cassandra_truststore.jks -file temp_file.der

      En este paso, debe crear una contraseña para el almacén de claves y dar confianza a este certificado. El comando interactivo tiene el siguiente aspecto.

      Enter keystore password:
Re-enter new password:
Owner: OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US
Issuer: OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US
Serial number: 0
Valid from: Tue Jun 29 17:39:16 UTC 2004 until: Thu Jun 29 17:39:16 UTC 2034
Certificate fingerprints:
	 MD5:  32:4A:4B:BB:C8:63:69:9B:BE:74:9A:C6:DD:1D:46:24
	 SHA1: AD:7E:1C:28:B0:64:EF:8F:60:03:40:20:14:C3:D0:E3:37:0E:B5:8A
	 SHA256: 14:65:FA:20:53:97:B8:76:FA:A6:F0:A9:95:8E:55:90:E4:0F:CC:7F:AA:4F:B7:C2:C8:67:75:21:FB:5F:B6:58
Signature algorithm name: SHA1withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 3
Extensions:
#1: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: BF 5F B7 D1 CE DD 1F 86   F4 5B 55 AC DC D7 10 C2  ._.......[U.....
0010: 0E A9 88 E7                                        ....
]
[OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US]
SerialNumber: [    00]
]
#2: ObjectId: 2.5.29.19 Criticality=false
BasicConstraints:[
  CA:true
  PathLen:2147483647
]
#3: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: BF 5F B7 D1 CE DD 1F 86   F4 5B 55 AC DC D7 10 C2  ._.......[U.....
0010: 0E A9 88 E7                                        ....
]
]
Trust this certificate? [no]:  y

  2. Adjunte el trustStore archivo en los JVM argumentos: 

    -Djavax.net.ssl.trustStore=path_to_file/cassandra_truststore.jks 
-Djavax.net.ssl.trustStorePassword=my_password

Step-by-step tutorial para conectarse a Amazon Keyspaces mediante el controlador DataStax Java para Apache Cassandra con credenciales específicas del servicio

En el siguiente step-by-step tutorial, se explica cómo conectarse a Amazon Keyspaces mediante un controlador Java para Cassandra con credenciales específicas del servicio. En concreto, utilizará la versión 4.0 del controlador de DataStax Java para Apache Cassandra.

Paso 1: Requisitos previos

Para seguir este tutorial, debe generar credenciales específicas del servicio y añadir el controlador DataStax Java para Apache Cassandra a su proyecto de Java.

Paso 2: Configurar el controlador

Puede especificar los ajustes del controlador DataStax Java Cassandra creando un archivo de configuración para su aplicación. Este archivo de configuración anula los ajustes predeterminados e indica al controlador que se conecte al punto de conexión del servicio de Amazon Keyspaces a través del puerto 9142. Para obtener una lista de los puntos de conexión de servicio disponibles, consulte Puntos de conexión de servicio para Amazon Keyspaces.

Cree un archivo de configuración y guárdelo en la carpeta de recursos de la aplicación; por ejemplo, src/main/resources/application.conf. Abra application.conf y añada los siguientes ajustes de configuración.

  1. Proveedor de autenticación: cree el proveedor de autenticación con la clase PlainTextAuthProvider. ServiceUserName y ServicePassword debe coincidir con el nombre de usuario y la contraseña que obtuvo al generar las credenciales específicas del servicio siguiendo los pasos que se indican en. Cree credenciales de servicios específicos para el acceso programático a Amazon Keyspaces

    nota

    Puede usar credenciales de corta duración mediante el complemento de autenticación del controlador DataStax Java para Apache Cassandra en lugar de codificar las credenciales en el archivo de configuración del controlador. Para obtener más información, siga las instrucciones de Step-by-step tutorial para conectarse a Amazon Keyspaces mediante el controlador DataStax Java 4.x para Apache Cassandra y el complemento de autenticación SigV4.

  2. Centro de datos local: establezca el valor de local-datacenter a la región a la que se conecte. Por ejemplo, si la aplicación se conecta a cassandra.us-east-2.amazonaws.com, entonces establezca el centro de datos local en us-east-2. Para conocer todas las Regiones de AWS disponibles, consulte Puntos de conexión de servicio para Amazon Keyspaces. Establezca slow-replica-avoidance = false para equilibrar la carga con menos nodos.

  3. SSL/TLS— Inicialízalo SSLEngineFactory añadiendo una sección en el archivo de configuración con una sola línea que especifique la clase con la que. class = DefaultSslEngineFactory Proporcione la ruta al trustStore archivo y la contraseña que creó anteriormente. Amazon Keyspaces no admite hostname-validation de pares, por lo que debe establecer esta opción en false.

datastax-java-driver {

    basic.contact-points = [ "cassandra.us-east-2.amazonaws.com:9142"]
    advanced.auth-provider{
        class = PlainTextAuthProvider
        username = "ServiceUserName"
        password = "ServicePassword"
    }
    basic.load-balancing-policy {
        local-datacenter = "us-east-2"
        slow-replica-avoidance = false           
    }

    advanced.ssl-engine-factory {
        class = DefaultSslEngineFactory
        truststore-path = "./src/main/resources/cassandra_truststore.jks"
        truststore-password = "my_password"
        hostname-validation = false
      }
}
nota

En lugar de añadir la ruta al archivo de configuración, también puede añadir la trustStore ruta directamente en el código de la aplicación o bien añadir la ruta trustStore a sus JVM argumentos. trustStore

Paso 3: Ejecutar el ejemplo de aplicación

Este ejemplo de código muestra una sencilla aplicación de línea de comandos que crea un grupo de conexión a Amazon Keyspaces utilizando el archivo de configuración se ha creado anteriormente. Confirma que se ha establecido la conexión ejecutando una consulta sencilla.

package <your package>;
// add the following imports to your project
import com.datastax.oss.driver.api.core.CqlSession;
import com.datastax.oss.driver.api.core.config.DriverConfigLoader;
import com.datastax.oss.driver.api.core.cql.ResultSet;
import com.datastax.oss.driver.api.core.cql.Row;

public class App 
{
    
    public static void main( String[] args )
    {
        //Use DriverConfigLoader to load your configuration file
        DriverConfigLoader loader = DriverConfigLoader.fromClasspath("application.conf");
        try (CqlSession session = CqlSession.builder()
                .withConfigLoader(loader)
                .build()) {

            ResultSet rs = session.execute("select * from system_schema.keyspaces");
            Row row = rs.one();
            System.out.println(row.getString("keyspace_name"));
        }
    }
}
nota

Utilice un bloque try para establecer la conexión a fin de garantizar que siempre esté cerrada. Si no utilizas un bloque try, recuerde cerrar su conexión para evitar fugas de recursos.

Step-by-step tutorial para conectarse a Amazon Keyspaces mediante el controlador DataStax Java 4.x para Apache Cassandra y el complemento de autenticación SigV4

En la siguiente sección se describe cómo utilizar el complemento de autenticación SigV4 para el controlador DataStax Java 4.x de código abierto para Apache Cassandra a fin de acceder a Amazon Keyspaces (para Apache Cassandra). El complemento está disponible en el repositorio. GitHub

El complemento de autenticación SigV4 le permite usar IAM credenciales para usuarios o roles cuando se conecta a Amazon Keyspaces. En lugar de requerir un nombre de usuario y una contraseña, este complemento firma API las solicitudes mediante claves de acceso. Para obtener más información, consulte Crear y configurar AWS credenciales para Amazon Keyspaces.

Paso 1: Requisitos previos

Para seguir este tutorial, necesita completar las siguientes tareas.

Paso 2: Configurar el controlador

Puede especificar los ajustes del controlador DataStax Java Cassandra creando un archivo de configuración para su aplicación. Este archivo de configuración anula los ajustes predeterminados e indica al controlador que se conecte al punto de conexión del servicio de Amazon Keyspaces a través del puerto 9142. Para obtener una lista de los puntos de conexión de servicio disponibles, consulte Puntos de conexión de servicio para Amazon Keyspaces.

Cree un archivo de configuración y guárdelo en la carpeta de recursos de la aplicación; por ejemplo, src/main/resources/application.conf. Abra application.conf y añada los siguientes ajustes de configuración.

  1. Proveedor de autenticación: establezca la advanced.auth-provider.class a una nueva instancia de software.aws.mcs.auth.SigV4AuthProvider. El SigV4 AuthProvider es el controlador de autenticación que proporciona el complemento para realizar la autenticación SigV4.

  2. Centro de datos local: establezca el valor de local-datacenter a la región a la que se conecte. Por ejemplo, si la aplicación se conecta a cassandra.us-east-2.amazonaws.com, entonces establezca el centro de datos local en us-east-2. Para ver todos los disponibles Regiones de AWS, consulte. Puntos de conexión de servicio para Amazon Keyspaces Se configura slow-replica-avoidance = false para equilibrar la carga con respecto a todos los nodos disponibles.

  3. Idempotencia: establezca el valor predeterminado de la aplicación idempotence para configurar el controlador de modo que siempre vuelva true a intentar las solicitudes de lectura/escritura/preparación/ejecución fallidas. Esta es una práctica recomendada para las aplicaciones distribuidas que ayuda a gestionar los errores transitorios al reintentar las solicitudes fallidas.

  4. SSL/TLS— Inicialice el SSLEngineFactory añadiendo una sección en el archivo de configuración con una sola línea que especifique la clase con la que se va a utilizar. class = DefaultSslEngineFactory Proporcione la ruta al trustStore archivo y la contraseña que creó anteriormente. Amazon Keyspaces no admite hostname-validation de pares, por lo que debe establecer esta opción en false.

  5. Conexiones: cree al menos 3 conexiones locales por punto final mediante la configuraciónlocal.size = 3. Esta es una práctica recomendada que ayuda a su aplicación a gestionar los sobrecargos y las ráfagas de tráfico. Para obtener más información sobre cómo calcular el número de conexiones locales por punto final que necesita su aplicación en función de los patrones de tráfico esperados, consulteConfiguración de conexiones en Amazon Keyspaces.

  6. Política de reintentos: implementa la AmazonKeyspacesExponentialRetryPolicy política de reintentos de Amazon Keyspaces en lugar de DefaultRetryPolicy la que viene con el controlador Cassandra. Esto le permite configurar el número de intentos de reintento que mejor se adapte a sus necesidades. AmazonKeyspacesExponentialRetryPolicy De forma predeterminada, el número de reintentos para el AmazonKeyspacesExponentialRetryPolicy está establecido en 3. Para obtener más información, consulte Cómo configurar la política de reintentos para las conexiones en Amazon Keyspaces.

  7. Declaraciones preparadas: establézcalo prepare-on-all-nodes en false para optimizar el uso de la red.

datastax-java-driver {
    basic {
        contact-points = [ "cassandra.us-east-2.amazonaws.com:9142"]  
        request {
            timeout = 2 seconds
            consistency = LOCAL_QUORUM
            page-size = 1024
            default-idempotence = true
        }
        load-balancing-policy {
            local-datacenter = "us-east-2"
            class = DefaultLoadBalancingPolicy
            slow-replica-avoidance = false           
        }
    }
    advanced {
        auth-provider {
            class = software.aws.mcs.auth.SigV4AuthProvider
            aws-region = us-east-2
        }
        ssl-engine-factory {
            class = DefaultSslEngineFactory
            truststore-path = "./src/main/resources/cassandra_truststore.jks"
            truststore-password = "my_password"
            hostname-validation = false
        }
        connection {
	     connect-timeout = 5 seconds
	     max-requests-per-connection = 512
	     pool {
                local.size = 3
	     }
        }
       retry-policy {
           class =  com.aws.ssa.keyspaces.retry.AmazonKeyspacesExponentialRetryPolicy
	    max-attempts = 3
	    min-wait = 10 mills
	    max-wait = 100 mills
       }
       prepared-statements {
	    prepare-on-all-nodes = false
       }
    }
}
nota

En lugar de añadir la trustStore ruta al archivo de configuración, también puede añadir la trustStore ruta directamente en el código de la aplicación o añadir la ruta trustStore a sus JVM argumentos.

Paso 3: Ejecute la aplicación

Este ejemplo de código muestra una sencilla aplicación de línea de comandos que crea un grupo de conexión a Amazon Keyspaces utilizando el archivo de configuración se ha creado anteriormente. Confirma que se ha establecido la conexión ejecutando una consulta sencilla.

package <your package>;
// add the following imports to your project
import com.datastax.oss.driver.api.core.CqlSession;
import com.datastax.oss.driver.api.core.config.DriverConfigLoader;
import com.datastax.oss.driver.api.core.cql.ResultSet;
import com.datastax.oss.driver.api.core.cql.Row;

public class App 
{
    
    public static void main( String[] args )
    {
        //Use DriverConfigLoader to load your configuration file
        DriverConfigLoader loader = DriverConfigLoader.fromClasspath("application.conf");
        try (CqlSession session = CqlSession.builder()
                .withConfigLoader(loader)
                .build()) {

            ResultSet rs = session.execute("select * from system_schema.keyspaces");
            Row row = rs.one();
            System.out.println(row.getString("keyspace_name"));
        }
    }
}
nota

Utilice un bloque try para establecer la conexión a fin de garantizar que siempre esté cerrada. Si no utilizas un bloque try, recuerde cerrar su conexión para evitar fugas de recursos.

Conéctese a Amazon Keyspaces mediante el controlador DataStax Java 3.x para Apache Cassandra y el complemento de autenticación SigV4

En la siguiente sección, se describe cómo utilizar el complemento de autenticación SigV4 para el controlador DataStax Java 3.x de código abierto para que Apache Cassandra acceda a Amazon Keyspaces. El complemento está disponible en el repositorio. GitHub

El complemento de autenticación SigV4 le permite usar IAM credenciales para usuarios y roles cuando se conecta a Amazon Keyspaces. En lugar de requerir un nombre de usuario y una contraseña, este complemento firma API las solicitudes mediante claves de acceso. Para obtener más información, consulte Crear y configurar AWS credenciales para Amazon Keyspaces.

Paso 1: Requisitos previos

Para ejecutar este código de ejemplo, primero debe completar las siguientes tareas.

Paso 2: Ejecute la aplicación

Este ejemplo de código muestra una sencilla aplicación de línea de comandos que crea un grupo de conexiones a Amazon Keyspaces. Confirma que se ha establecido la conexión ejecutando una consulta sencilla.

package <your package>;
// add the following imports to your project

import software.aws.mcs.auth.SigV4AuthProvider;  
import com.datastax.driver.core.Cluster;  
import com.datastax.driver.core.ResultSet;  
import com.datastax.driver.core.Row;  
import com.datastax.driver.core.Session;

public class App 
{
    
    public static void main( String[] args )
    {
        String endPoint = "cassandra.us-east-2.amazonaws.com";  
        int portNumber = 9142;
        Session session = Cluster.builder()  
	                                 .addContactPoint(endPoint)  
	                                 .withPort(portNumber)  
	                                 .withAuthProvider(new SigV4AuthProvider("us-east-2"))  
	                                 .withSSL()  
	                                 .build()  
	                                 .connect();

        ResultSet rs = session.execute("select * from system_schema.keyspaces");  
        Row row = rs.one();  
        System.out.println(row.getString("keyspace_name"));
    }
}

Notas de uso:

Para obtener una lista de los puntos de conexión disponibles, consulte Puntos de conexión de servicio para Amazon Keyspaces.

Consulte el siguiente repositorio para obtener políticas, ejemplos y prácticas recomendadas útiles al utilizar el controlador Java con Amazon Keyspaces: https://github.com/aws-samples/amazon-keyspaces-java-driver-helpers.