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 se vinculen a un usuario de AWS Identity and Access Management (IAM) específico.

  • Para mejorar la seguridad, se recomienda crear claves de acceso de IAM para las identidades de IAM que se utilizan en todos los servicios. AWS El complemento de autenticación SigV4 de Amazon Keyspaces para controladores de cliente de Cassandra habilita la autenticación de llamadas a Amazon Keyspaces utilizando claves de acceso de IAM en vez de nombre de usuario y contraseña. Para obtener más información, consulte Cómo 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 Seguridad de la capa de transporte (TLS) para ayudar a 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 archivo trustStore.

      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 archivo trustStore en los argumentos de la JVM: 

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

Un tep-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. ServiceUserEl nombre ServicePassworddebe 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. Generación de credenciales específicas del servicio

    nota

    Puede usar credenciales de corta duración mediante el complemento de autenticación del controlador de 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 Un tep-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: para inicializar el SSL, EngineFactory añada una sección en el archivo de configuración con una sola línea que especifique la clase con la que se especifica. class = DefaultSslEngineFactory Proporcione la ruta al archivo trustStore 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 vez de añadir la ruta al trustStore en el archivo de configuración, también puede añadir la ruta al trustStore directamente en el código de la aplicación o a sus argumentos de la JVM.

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.

Un tep-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 utilizar credenciales de IAM para usuarios o roles al conectarse a Amazon Keyspaces. En vez de requerir un nombre de usuario y una contraseña, este complemento firma las solicitudes de la API utilizando claves de acceso. Para obtener más información, consulte Cómo 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: para inicializar el SSL, EngineFactory añada una sección en el archivo de configuración con una sola línea que especifique la clase con la que se especifica. class = DefaultSslEngineFactory Proporcione la ruta al archivo trustStore 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ón. local.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: la AmazonKeyspacesExponentialRetryPolicy política de reintentos de Amazon Keyspaces es una alternativa a DefaultRetryPolicy la que viene con el controlador Cassandra. La principal diferencia entre las dos políticas de reintentos es que puede configurar la cantidad de reintentos para que se adapte a sus necesidades. AmazonKeyspacesExponentialRetryPolicy De forma predeterminada, el número de reintentos para el AmazonKeyspacesExponentialRetryPolicy está establecido en 3. Además, la política de reintentos de Amazon Keyspaces no devuelve el genérico. NoHostAvailableException En cambio, la política de reintentos de Amazon Keyspaces devuelve la excepción original devuelta por el servicio. Para ver más ejemplos de código que implementan políticas de reintentos, consulta las políticas de reintentos de Amazon Keyspaces en Github.

  7. Declaraciones preparadas: establézcalas en false prepare-on-all-nodes 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 vez de añadir la ruta al trustStore en el archivo de configuración, también puede añadir la ruta al trustStore directamente en el código de la aplicación o a sus argumentos de la JVM.

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 utilizar credenciales de IAM para usuarios o roles al conectarse a Amazon Keyspaces. En vez de requerir un nombre de usuario y una contraseña, este complemento firma las solicitudes de la API utilizando claves de acceso. Para obtener más información, consulte Cómo 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.