Início Rápido: Criar uma aplicação Go com o `gocql` cliente para gerir dados do Azure Cosmos DB para o Apache Cassandra

Artigo
04/11/2023

APLICA-SE A: Cassandra

O Azure Cosmos DB é um serviço de base de dados de vários modelos que lhe permite criar e consultar rapidamente as bases de dados de documentos, tabelas, chave-valor e grafos com capacidades globais de distribuição e dimensionamento horizontal. Neste início rápido, irá começar por criar uma conta do Azure Cosmos DB para o Apache Cassandra. Em seguida, irá executar uma aplicação Go para criar um espaço de chaves, uma tabela e executar algumas operações do Cassandra. Esta aplicação Go utiliza gocql, que é um cliente Cassandra para o idioma Go.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie um gratuitamente. Em alternativa, experimente o Azure Cosmos DB gratuitamente sem uma subscrição do Azure.
Aceda à instalação no seu computador e a um conhecimento funcional do Go.
Git.

Criar uma conta de base de dados

Antes de poder criar uma base de dados, tem de criar uma conta do Cassandra com o Azure Cosmos DB.

No menu portal do Azure ou na Home page, selecione Criar um recurso.
Na página Novo , procure e selecione Azure Cosmos DB.
Na página do Azure Cosmos DB , selecione Criar.
Na página API , selecione Criar na secção Cassandra .

A API determina o tipo de conta a criar. O Azure Cosmos DB fornece cinco APIs: NoSQL para bases de dados de documentos, Gremlin para bases de dados de grafos, MongoDB para bases de dados de documentos, Tabela do Azure e Cassandra. Tem de criar uma conta separada para cada API.

Selecione Cassandra, porque neste início rápido está a criar uma tabela que funciona com a API para Cassandra.

Saiba mais sobre a API para Cassandra.

Na página Criar Conta do Azure Cosmos DB , introduza as definições básicas da nova conta do Azure Cosmos DB.

Definição	Valor	Descrição
Subscrição	A sua subscrição	Selecione a subscrição do Azure que quer utilizar para esta conta do Azure Cosmos DB.
Grupo de Recursos	Criar novo Em seguida, introduza o mesmo nome que Nome da Conta	Selecione Criar novo. Em seguida, introduza um novo nome de grupo de recursos para a sua conta. Para simplificar, utilize o mesmo nome que o nome da conta do Azure Cosmos DB.
Nome da Conta	Introduza um nome exclusivo	Introduza um nome exclusivo para identificar a sua conta do Azure Cosmos DB. O URI da sua conta será cassandra.cosmos.azure.com anexado ao nome exclusivo da sua conta. O nome da conta só pode utilizar letras minúsculas, números e hífenes (-) e tem de ter entre 3 e 31 carateres de comprimento.
Localização	A região mais próxima dos seus utilizadores	Selecione a localização geográfica para alojar a sua conta do Azure Cosmos DB. Utilize a localização mais próxima dos utilizadores para lhes dar o acesso mais rápido aos dados.
Modo de capacidade	Débito aprovisionado ou Sem Servidor	Selecione Débito aprovisionado para criar uma conta no modo de débito aprovisionado . Selecione Sem servidor para criar uma conta no modo sem servidor .
Aplicar desconto de escalão gratuito do Azure Cosmos DB	Aplicar ou Não aplicar	Com o escalão gratuito do Azure Cosmos DB, obterá gratuitamente as primeiras 1000 RU/s e 25 GB de armazenamento numa conta. Saiba mais sobre o escalão gratuito.
Limitar o débito total da conta	Selecione para limitar o débito da conta	Isto é útil se quiser limitar o débito total da conta a um valor específico.

Nota

Pode ter até uma conta do Azure Cosmos DB de escalão gratuito por subscrição do Azure e tem de optar ativamente por participar ao criar a conta. Se não vir a opção para aplicar o desconto de escalão gratuito, significa que outra conta na subscrição já foi ativada com o escalão gratuito.

A nova página de conta do Azure Cosmos DB para Apache Cassandra

No separador Distribuição Global , configure os seguintes detalhes. Pode deixar os valores predefinidos para efeitos deste início rápido:

Definição	Valor	Descrição
Redundância Geográfica	Desativar	Ative ou desative a distribuição global na sua conta ao emparelhar a sua região com uma região de par. Pode adicionar mais regiões à sua conta mais tarde.
Escritas de várias regiões	Desativar	A capacidade de escrita de várias regiões permite-lhe tirar partido do débito aprovisionado para as suas bases de dados e contentores em todo o mundo.
Zonas de Disponibilidade	Desativar	Zonas de Disponibilidade são localizações isoladas numa região do Azure. Cada zona é composta por um ou mais datacenters equipados com energia, refrigeração e rede independentes.

Nota

As seguintes opções não estão disponíveis se selecionar Sem servidor como modo de Capacidade:

Aplicar Desconto de Escalão Gratuito
Georredundância
Escritas de várias regiões

Opcionalmente, pode configurar detalhes adicionais nos seguintes separadores:
- Rede – configurar o acesso a partir de uma rede virtual.
- Política de Cópia de Segurança – configure uma política de cópia de segurança periódica ou contínua .
- Encriptação – utilize uma chave gerida pelo serviço ou uma chave gerida pelo cliente.
- Etiquetas – as etiquetas são pares de nomes/valores que lhe permitem categorizar recursos e ver a faturação consolidada ao aplicar a mesma etiqueta a vários recursos e grupos de recursos.
Selecione Rever + criar.
Reveja as definições da conta e, em seguida, selecione Criar. A criação da conta demora alguns minutos. Aguarde até que a página do portal apresente A implementação está concluída.
Selecione Ir para recurso para aceder à página da conta do Azure Cosmos DB.

Clonar a aplicação de exemplo

Comece por clonar a aplicação a partir do GitHub.

Abra uma linha de comandos e crie uma nova pasta com o nome git-samples.
```
md "C:\git-samples"
```
Abra uma janela de terminal do Git, como git bash. Utilize o cd comando para mudar para a nova pasta e instalar a aplicação de exemplo.
```
cd "C:\git-samples"
```
Execute o seguinte comando para clonar o repositório de exemplo. Este comando cria uma cópia da aplicação de exemplo no seu computador.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git
```

Rever o código

Este passo é opcional. Se estiver interessado em saber como o código cria os recursos da base de dados, pode rever os seguintes fragmentos de código. Caso contrário, pode avançar para Executar a aplicação

A GetSession função (parte de utils\utils.go) devolve uma *gocql.Session que é utilizada para executar operações de cluster, como inserir, localizar, 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
}

O anfitrião cassandra do Azure Cosmos DB é transmitido para a gocql.NewCluster função para obter uma *gocql.ClusterConfig estrutura que é configurada para utilizar o nome de utilizador, a palavra-passe, a porta e a versão do TLS adequada (REQUISITO de segurança de encriptação HTTPS/SSL/TLS)

Em GetSession seguida, a função é chamada a main partir da função (main.go).

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

As informações de conectividade e as credenciais são aceites sob a forma de variáveis de ambiente (resolvidas no init método)

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")
    }
}

Em seguida, é utilizado para executar várias operações (parte de operations\setup.go) no Azure Cosmos DB, começando com keyspace e table criação.

Como o nome sugere, a DropKeySpaceIfExists função remove a keyspace única se existir.

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")
}

CreateKeySpace a função é utilizada para criar o 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")
}

Segue-se a criação de tabelas (user) que é gerida pela CreateUserTable função

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")
}

Assim que o espaço de chaves e a tabela forem criados, invocamos operações CRUD (parte de operations\crud.go).

InsertUser é utilizado para criar um User. Define as informações do utilizador (ID, nome e cidade) como argumentos de consulta com 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 é utilizado para procurar um utilizador (model\user.go) com um ID de utilizador específico, ao Scan mesmo tempo que vincula os atributos do utilizador (devolvidos pelo Cassandra) a variáveis individuais (userid, name, city) – é apenas uma das formas de utilizar o resultado obtido como resultado da consulta de pesquisa

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

FindAllUsers é utilizado para obter todos os utilizadores. SliceMap é utilizado como uma abreviatura para obter todas as informações do utilizador sob a forma de um setor de maps. Pense em cada um map como pares chave-valor em que o nome da coluna (por exemplo, user_id) é a chave juntamente com o respetivo valor.

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 map uma das informações de utilizador é convertida numa User função de utilização mapToUser que simplesmente extrai o valor da respetiva coluna e utiliza-o para criar uma instância da User estrutura

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

Executar a aplicação

Conforme mencionado anteriormente, a aplicação aceita conectividade e credenciais na forma das variáveis de ambiente.

Na sua conta do Azure Cosmos DB no portal do Azure, selecione Cadeia de Ligação.

Copie os valores dos seguintes atributos (CONTACT POINT, PORTe USERNAME ) e PRIMARY PASSWORDdefina-os para as respetivas variáveis de ambiente

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

Na janela do terminal, mude para a pasta correta. Por exemplo:

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

No terminal, execute o seguinte comando para iniciar a aplicação.

go run main.go

A janela de terminal apresenta notificações para as várias operações, incluindo o espaço de chaves e a configuração da tabela, a criação de utilizadores, etc.
No portal do Azure, abra o Data Explorer para consultar, modificar e trabalhar com estes dados novos.

Rever os SLAs no portal do Azure

O portal do Azure monitoriza o débito, o armazenamento, a disponibilidade, a latência e a consistência da conta do Azure Cosmos DB. Os gráficos para métricas associadas a um Contrato de Nível de Serviço (SLA) do Azure Cosmos DB mostram o valor do SLA em comparação com o desempenho real. Este conjunto de métricas torna a monitorização dos SLAs transparente.

Para rever as métricas e os SLAs:

Selecione Métricas no menu de navegação da sua conta do Azure Cosmos DB.
Selecione um separador, como Latência, e selecione um período de tempo à direita. Compare as linhas Real e SLA nos gráficos.
Reveja as métricas nos outros separadores.

Limpar os recursos

Quando terminar a aplicação e a conta do Azure Cosmos DB, pode eliminar os recursos do Azure que criou para não incorrer em mais custos. Para eliminar os recursos:

Na barra de Pesquisa do portal do Azure, procure e selecione Grupos de recursos.
Na lista, selecione o grupo de recursos que criou para este início rápido.
Na página Descrição geral do grupo de recursos, selecione Eliminar grupo de recursos.
Na janela seguinte, introduza o nome do grupo de recursos a eliminar e, em seguida, selecione Eliminar.

Passos seguintes

Neste início rápido, aprendeu a criar uma conta do Azure Cosmos DB com a API para Cassandra e a executar uma aplicação Go que cria uma base de dados e um contentor do Cassandra. Agora pode importar dados adicionais para a sua conta do Azure Cosmos DB.

Importar dados do Cassandra para o Azure Cosmos DB

Início Rápido: Criar uma aplicação Go com o gocql cliente para gerir dados do Azure Cosmos DB para o Apache Cassandra