Inicio rápido: Creación de una aplicación de Go con el cliente `gocql` para administrar los datos de Azure Cosmos DB for Apache Cassandra

Artículo
03/22/2023

SE APLICA A: Cassandra

Azure Cosmos DB es un servicio de base de datos multimodelo que permite crear y consultar rápidamente bases de datos de documentos, tablas, claves-valores y grafos con funcionalidades de distribución global y escala horizontal. En esta guía de inicio rápido, comenzará por crear una cuenta de Azure Cosmos DB for Apache Cassandra. A continuación, ejecutará una aplicación de Go para crear un espacio de claves de Cassandra, una tabla y ejecutar algunas operaciones. Esta aplicación de Go usa gocql, que es un cliente de Cassandra para el lenguaje Go.

Requisitos previos

Una cuenta de Azure con una suscripción activa. cree una de forma gratuita. O bien, pruebe gratis Azure Cosmos DB sin una suscripción de Azure.
Instalación de Go en el equipo y conocimientos de cómo funciona.
Git.

Creación de una cuenta de base de datos

Para poder crear una base de datos, debe crear una cuenta de Cassandra con Azure Cosmos DB.

En el menú de Azure Portal o en la página principal, seleccione Crear un recurso.
En la página Nuevos, busque y seleccione Azure Cosmos DB.
En la página Azure Cosmos DB, seleccione Crear.
En la página API, seleccione Crear en la sección Cassandra.

La API determina el tipo de cuenta que se va a crear. Azure Cosmos DB proporciona cinco API: NoSQL para bases de datos de documentos, Gremlin para bases de datos de grafos, MongoDB para bases de datos de documentos, Azure Table y Cassandra. Debe crear una cuenta independiente para cada API.

Seleccione Cassandra, ya que en este inicio rápido va a crear una tabla que funciona con la API para Cassandra.

Más información acerca de la API para Cassandra.

En la página Crear una cuenta de Azure Cosmos DB, especifique la configuración básica de la nueva cuenta de Azure Cosmos DB.

Configuración	Value	Descripción
Subscription	Su suscripción	Seleccione la suscripción de Azure que quiere usar para esta cuenta de Azure Cosmos DB.
Grupo de recursos	Crear nuevo A continuación, escriba el mismo nombre que el nombre de cuenta.	Seleccione Crear nuevo. Luego, escriba un nombre nuevo de grupo de recursos para la cuenta. Para simplificar, use el mismo nombre que el de la cuenta de Azure Cosmos DB.
Nombre de cuenta	Escriba un nombre único.	Escriba un nombre único para identificar la cuenta de Azure Cosmos DB. El URI de la cuenta será cassandra.cosmos.azure.com y se anexará al nombre único de la cuenta. El nombre de la cuenta solo puede utilizar letras minúsculas, números y guiones (-), y debe tener entre 3 y 31 caracteres de longitud.
Location	Región más cercana a los usuarios	Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB. Use la ubicación más cercana a los usuarios para que puedan acceder de la forma más rápida posible a los datos.
Capacity mode (Modo de capacidad)	Rendimiento aprovisionado o sin servidor	Seleccione Provisioned throughput (Rendimiento aprovisionado) para crear una cuenta en modo de rendimiento aprovisionado. Seleccione Serverless (Sin servidor) para crear una cuenta en modo sin servidor.
Aplicar el descuento del nivel Gratis de Azure Cosmos DB	Aplicar o No aplicar	Con el nivel Gratis de Azure Cosmos DB, recibirá los primeros 1000 RU/s y 25 GB de almacenamiento gratis en una cuenta. Más información acerca del nivel Gratis.
Límite del rendimiento total de la cuenta	Seleccione esta opción para limitar el rendimiento de la cuenta	Esto resultará útil si desea limitar el rendimiento total de la cuenta a un valor específico.

Nota

Puede tener una cuenta de Azure Cosmos DB de nivel Gratis por cada suscripción de Azure y debe optar por tenerla al crear la cuenta. Si no ve la opción para aplicar el descuento por nivel Gratis, significará que en otra cuenta de la suscripción ya se ha habilitado el nivel Gratis.

Página de la nueva cuenta de Azure Cosmos DB for Apache Cassandra

En la pestaña Distribución global, configure los detalles siguientes. Puede dejar los valores predeterminados para este inicio rápido:

Configuración	Value	Descripción
Redundancia geográfica	Deshabilitar	Habilite o deshabilite la distribución global en su cuenta. Para ello, debe emparejar su región con una región de par. Puede agregar más regiones a su cuenta más adelante.
Escrituras en varias regiones	Deshabilitar	La funcionalidad de escrituras en varias regiones le permite aprovechar el rendimiento aprovisionado para sus bases de datos y contenedores de todo el mundo.
Zonas de disponibilidad	Deshabilitar	Las zona de disponibilidad son ubicaciones aisladas dentro de una región de Azure. Cada zona de disponibilidad consta de uno o varios centros de datos equipados con alimentación, refrigeración y redes independientes.

Nota

Las siguientes opciones no están disponibles si selecciona Serverless (Sin servidor) en Capacity mode (Modo de capacidad):

Aplicación de descuento por nivel Gratis
Redundancia geográfica
Escrituras en varias regiones

Opcionalmente, puede configurar detalles adicionales en las pestañas siguientes:
- Redes: configure el acceso desde una red virtual.
- Directiva de copia de seguridad: configure una directiva de copia de seguridad periódica o continua.
- Cifrado: use una clave administrada por el servicio o una clave administrada por el cliente.
- Etiquetas: son pares nombre-valor que permiten categorizar los recursos y ver una facturación consolidada mediante la aplicación de la misma etiqueta en varios recursos y grupos de recursos.
Seleccione Revisar + crear.
Revise la configuración de la cuenta y seleccione Crear. La operación de creación de la cuenta tarda unos minutos. Espere hasta que la página del portal muestre Se completó la implementación .
Seleccione Ir al recurso para ir a la página de la cuenta de Azure Cosmos DB.

Clonación de la aplicación de ejemplo

Comience por clonar la aplicación desde GitHub.

Abra un símbolo del sistema y cree una nueva carpeta llamada git-samples.
```
md "C:\git-samples"
```
Abra una ventana de terminal de Git, como Git Bash. Use el comando cd para cambiar a la nueva carpeta e instalar la aplicación de ejemplo.
```
cd "C:\git-samples"
```
Ejecute el comando siguiente para clonar el repositorio de ejemplo. Este comando crea una copia de la aplicación de ejemplo en el equipo.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git
```

Revisión del código

Este paso es opcional. Si le interesa aprender cómo crea el código los recursos de base de datos, puede revisar los siguientes fragmentos de código. En caso contrario, puede ir directamente a Ejecución de la aplicación.

La función GetSession (parte de utils\utils.go) devuelve un elemento *gocql.Session que se usa para ejecutar operaciones del clúster como insertar, buscar, etc.

func GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword string) *gocql.Session {
    clusterConfig := gocql.NewCluster(cosmosCassandraContactPoint)
    port, err := strconv.Atoi(cosmosCassandraPort)
    
    clusterConfig.Authenticator = gocql.PasswordAuthenticator{Username: cosmosCassandraUser, Password: cosmosCassandraPassword}
    clusterConfig.Port = port
    clusterConfig.SslOpts = &gocql.SslOptions{Config: &tls.Config{MinVersion: tls.VersionTLS12}}
    clusterConfig.ProtoVersion = 4
    
    session, err := clusterConfig.CreateSession()
    ...
    return session
}

El host de Cassandra de Azure Cosmos DB se pasa a la función gocql.NewCluster para obtener una estructura *gocql.ClusterConfig que se configura para usar el nombre de usuario, la contraseña, el puerto y la versión de TLS adecuada (requisito de seguridad de cifrado HTTPS/SSL/TLS).

A continuación, se llama a la función GetSession desde la función main (main.go).

func main() {
    session := utils.GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword)
    defer session.Close()
    ...
}

La información de conectividad y las credenciales se aceptan en forma de variables de entorno (se resuelven en el método init).

func init() {
    cosmosCassandraContactPoint = os.Getenv("COSMOSDB_CASSANDRA_CONTACT_POINT")
    cosmosCassandraPort = os.Getenv("COSMOSDB_CASSANDRA_PORT")
    cosmosCassandraUser = os.Getenv("COSMOSDB_CASSANDRA_USER")
    cosmosCassandraPassword = os.Getenv("COSMOSDB_CASSANDRA_PASSWORD")

    if cosmosCassandraContactPoint == "" || cosmosCassandraUser == "" || cosmosCassandraPassword == "" {
        log.Fatal("missing mandatory environment variables")
    }
}

A continuación, se usan para ejecutar varias operaciones (parte de operations\setup.go) en Azure Cosmos DB que comienzan con la creación de los elementos keyspace y table.

Como sugiere el nombre, la función DropKeySpaceIfExists elimina el elemento keyspace solo si este existe.

const dropKeyspace = "DROP KEYSPACE IF EXISTS %s"

func DropKeySpaceIfExists(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(dropKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to drop keyspace", err)
    }
    log.Println("Keyspace dropped")
}

La función CreateKeySpace se usa para crear el elemento keyspace (user_profile).

const createKeyspace = "CREATE KEYSPACE %s WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }"

func CreateKeySpace(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(createKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to create keyspace", err)
    }
    log.Println("Keyspace created")
}

Esto va seguido de la creación de la tabla (user), de lo que se ocupa la función CreateUserTable.

const createTable = "CREATE TABLE %s.%s (user_id int PRIMARY KEY, user_name text, user_bcity text)"

func CreateUserTable(keyspace, table string, session *gocql.Session) {
    err := session.Query(fmt.Sprintf(createTable, keyspace, table)).Exec()
    if err != nil {
        log.Fatal("failed to create table ", err)
    }
    log.Println("Table created")
}

Una vez que se crean el espacio de claves y la tabla, se invocan las operaciones CRUD (parte de operations\crud.go).

Se utiliza InsertUser para crear un elemento User. Establece la información de usuario (identificador, nombre y ciudad) como argumentos de consulta mediante. Bind.

const createQuery = "INSERT INTO %s.%s (user_id, user_name , user_bcity) VALUES (?,?,?)"

func InsertUser(keyspace, table string, session *gocql.Session, user model.User) {
    err := session.Query(fmt.Sprintf(createQuery, keyspace, table)).Bind(user.ID, user.Name, user.City).Exec()
    if err != nil {
        log.Fatal("Failed to create user", err)
    }
    log.Println("User created")
}

FindUser se utiliza para buscar un usuario (model\user.go) mediante un identificador de usuario específico, mientras que Scan enlaza los atributos del usuario (devueltos por Cassandra) a variables individuales (userid, name y city); esta es solo una de las formas en las que se puede usar el resultado obtenido como resultado de la consulta de búsqueda.

const selectQuery = "SELECT * FROM %s.%s where user_id = ?"

func FindUser(keyspace, table string, id int, session *gocql.Session) model.User {
    var userid int
    var name, city string
    err := session.Query(fmt.Sprintf(selectQuery, keyspace, table)).Bind(id).Scan(&userid, &name, &city)

    if err != nil {
        if err == gocql.ErrNotFound {
            log.Printf("User with id %v does not exist\n", id)
        } else {
            log.Printf("Failed to find user with id %v - %v\n", id, err)
        }
    }
    return model.User{ID: userid, Name: name, City: city}
}

Se utiliza FindAllUsers para recuperar todos los usuarios. SliceMap se utiliza como una forma abreviada para obtener toda la información del usuario en forma de un segmento de map. Piense en cada elemento map como pares clave-valor donde el nombre de la columna (por ejemplo, user_id) es la clave, junto con su valor respectivo.

const findAllUsersQuery = "SELECT * FROM %s.%s"

func FindAllUsers(keyspace, table string, session *gocql.Session) []model.User {
    var users []model.User
    results, _ := session.Query(fmt.Sprintf(findAllUsersQuery, keyspace, table)).Iter().SliceMap()

    for _, u := range results {
        users = append(users, mapToUser(u))
    }
    return users
}

Cada elemento map de información de usuario se convierte en un elemento User mediante la función mapToUser, que simplemente extrae el valor de su columna respectiva y lo usa para crear una instancia de la estructura User.

func mapToUser(m map[string]interface{}) model.User {
    id, _ := m["user_id"].(int)
    name, _ := m["user_name"].(string)
    city, _ := m["user_bcity"].(string)

    return model.User{ID: id, Name: name, City: city}
}

Ejecución de la aplicación

Como se mencionó anteriormente, la aplicación acepta los datos de conectividad y las credenciales en forma de variables de entorno.

En la cuenta de Azure Cosmos DB, en Azure Portal, seleccione Cadena de conexión.

Copie los valores de los siguientes atributos (CONTACT POINT, PORT, USERNAME y PRIMARY PASSWORD) y establézcalos en las variables de entorno respectivas.

set COSMOSDB_CASSANDRA_CONTACT_POINT=<value for "CONTACT POINT">
set COSMOSDB_CASSANDRA_PORT=<value for "PORT">
set COSMOSDB_CASSANDRA_USER=<value for "USERNAME">
set COSMOSDB_CASSANDRA_PASSWORD=<value for "PRIMARY PASSWORD">

En la ventana de terminal, cambie a la carpeta correcta. Por ejemplo:

cd "C:\git-samples\azure-cosmosdb-cassandra-go-getting-started"

En el terminal, ejecute el comando siguiente para iniciar la aplicación.

go run main.go

La ventana de terminal muestra las notificaciones de las distintas operaciones, como la configuración del espacio de claves y la tabla, la creación de usuarios, etc.
En Azure Portal abra Explorador de datos para consultar, modificar y trabajar con estos nuevos datos.

Revisión de los SLA en Azure Portal

Azure Portal supervisa el rendimiento, capacidad de almacenamiento, disponibilidad, latencia y coherencia de su cuenta de Azure Cosmos DB. Los gráficos de las métricas asociadas con un Acuerdo de Nivel de Servicio (SLA) de Azure Cosmos DB muestran el rendimiento real en comparación con el valor de este acuerdo. Este conjunto de métricas hace que la supervisión de los Acuerdos de Nivel de Servicio sea transparente.

Para revisar las métricas y los Acuerdos de Nivel de Servicio:

Seleccione Métricas en el menú de navegación de la cuenta de Azure Cosmos DB.
Seleccione una pestaña como Latencia y seleccione un período de tiempo a la derecha. Compare las líneas Real y SLA de los gráficos.
Revise las métricas de las otras pestañas.

Limpieza de recursos

Cuando haya terminado tanto con la aplicación como con la cuenta de Azure Cosmos DB, puede eliminar los recursos de Azure que creó para no tener más gastos. Para eliminar los recursos:

En la barra de búsqueda de Azure Portal, busque y seleccione Grupos de recursos.
En la lista, seleccione el grupo de recursos que creó para este inicio rápido.
En la página Información general del grupo de recursos, seleccione Eliminar grupo de recursos.
En la ventana siguiente, escriba el nombre del grupo de recursos que desea eliminar y, después, seleccione Eliminar.

Pasos siguientes

En esta guía de inicio rápido ha aprendido a crear una cuenta de Azure Cosmos DB con la API para Cassandra y a ejecutar una aplicación de Go que crea un contenedor y una base de datos de Cassandra. Ya puede importar datos adicionales en la cuenta de Azure Cosmos DB.

Importación de datos de Cassandra en Azure Cosmos DB

Inicio rápido: Creación de una aplicación de Go con el cliente gocql para administrar los datos de Azure Cosmos DB for Apache Cassandra