Guia de início rápido: crie um aplicativo Go com o cliente para gerenciar dados gocql do Azure Cosmos DB para Apache Cassandra

  • Artigo

APLICA-SE A: Cassandra

O Azure Cosmos DB é um serviço de banco de dados multimodelo que permite criar e consultar rapidamente bancos de dados de documentos, tabelas, chave-valor e gráficos com recursos de distribuição global e escala horizontal. Neste início rápido, você começará criando uma conta do Azure Cosmos DB para Apache Cassandra. Em seguida, você executará um aplicativo Go para criar um keyspace Cassandra, uma tabela e executar algumas operações. Este aplicativo Go usa gocql, que é um cliente Cassandra para o idioma Go.

Pré-requisitos

Criar uma conta de base de dados

Antes de criar um banco de dados, você precisa criar uma conta Cassandra com o Azure Cosmos DB.

  1. A partir do menu do portal do Azure ou a partir da Home page, selecione Criar um recurso.

  2. Na página Novo, procure e selecione Azure Cosmos DB.

  3. Na página Azure Cosmos DB, selecione Criar.

  4. Na página API, selecione Criar na seção Cassandra.

    A API determina o tipo de conta a criar. O Azure Cosmos DB fornece cinco APIs: NoSQL para bancos de dados de documentos, Gremlin para bancos de dados gráficos, MongoDB para bancos de dados de documentos, Tabela do Azure e Cassandra. Você deve criar uma conta separada para cada API.

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

    Saiba mais sobre a API para Cassandra.

  5. Na página Criar Conta do Azure Cosmos DB, insira as configurações básicas para a nova conta do Azure Cosmos DB.

    Definição valor Description
    Subscrição a sua subscrição Selecione a subscrição do Azure que pretende utilizar para esta conta do Azure Cosmos DB.
    Grupo de Recursos Criar nova

    Em seguida, insira o mesmo nome que Nome da conta    		 Selecione Criar novo. Em seguida, insira um novo nome de grupo de recursos para sua conta. Para simplificar, use o mesmo nome que o nome da sua conta do Azure Cosmos DB.
    Nome da Conta Introduzir 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 seu nome de conta exclusivo.

    O nome da conta pode usar apenas letras minúsculas, números e hífenes (-), e deve ter entre 3 e 31 caracteres.
    Location 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 Taxa de transferência provisionada ou sem servidor Selecione Taxa de transferência provisionada para criar uma conta no modo de taxa de transferência provisionada. Selecione Serverless para criar uma conta no modo serverless .
    Aplicar desconto de nível gratuito do Azure Cosmos DB Candidatar-se ou Não aplicar Com o nível gratuito do Azure Cosmos DB, você receberá os primeiros 1000 RU/s e 25 GB de armazenamento gratuitamente em uma conta. Saiba mais sobre o nível gratuito.
    Limitar a taxa de transferência total da conta Selecione esta opção para limitar a taxa de transferência da conta Isso é útil se você quiser limitar a taxa de transferência total da conta a um valor específico.

    Nota

    Você pode ter até uma conta gratuita do Azure Cosmos DB por assinatura do Azure e deve optar por participar ao criar a conta. Se você não vir a opção de aplicar o desconto de nível gratuito, isso significa que outra conta na assinatura já foi habilitada com o nível gratuito.

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

  6. Na guia Distribuição Global, configure os seguintes detalhes. Você pode deixar os valores padrão para a finalidade deste início rápido:

    Definição valor Description
    Georredundância Desativar Habilite ou desative a distribuição global em sua conta emparelhando sua região com uma região par. Pode adicionar mais regiões à sua conta mais tarde.
    Escritas de várias regiões Desativar O recurso de gravação em várias regiões permite que você aproveite a taxa de transferência provisionada para seus bancos de dados e contêineres em todo o mundo.
    Zonas de Disponibilidade Desativar As Zonas de Disponibilidade são locais isolados dentro de uma 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 estarão disponíveis se você selecionar Serverless como o modo de Capacidade:

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

  7. Opcionalmente, você pode configurar detalhes adicionais nas seguintes guias:

    • Rede - Configure o acesso a partir de uma rede virtual.
    • Política de backup - Configure a política de backup periódico ou contínuo .
    • Criptografia - Use uma chave gerenciada pelo serviço ou uma chave gerenciada pelo cliente.
    • Tags - As tags são pares nome/valor que permitem categorizar recursos e exibir o faturamento consolidado aplicando a mesma tag a vários recursos e grupos de recursos.

  8. Selecione Rever + criar.

  9. 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.

    O painel Notificações do portal do Azure

  10. Selecione Ir para recurso para aceder à página da conta do Azure Cosmos DB.

Clonar a aplicação de exemplo

Comece clonando o aplicativo do GitHub.

  1. Abra um prompt de comando e crie uma nova pasta chamada git-samples.

    md "C:\git-samples"

  2. Abra uma janela de terminal do Git, como git bash. Use o cd comando para mudar para a nova pasta e instalar o aplicativo de exemplo.

    cd "C:\git-samples"

  3. 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 você estiver interessado em saber como o código cria os recursos do banco de dados, você pode revisar os seguintes trechos de código. Caso contrário, você pode pular para Executar o aplicativo

A GetSession função (parte de utils\utils.go) retorna um *gocql.Session que é usado 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 host Cassandra do Azure Cosmos DB é passado para a gocql.NewCluster função para obter uma *gocql.ClusterConfig estrutura que é configurada para usar o nome de usuário, a senha, a porta e a versão TLS apropriada (requisito de segurança de criptografia HTTPS/SSL/TLS)

A GetSession função é então chamada a partir da main função (main.go).

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

As informações e credenciais de conectividade são aceitas na 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, ele é usado 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 cai apenas keyspace 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 função é usada 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")
}

Isto é seguido pela criação de tabela (user) que é cuidada da 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")
}

Uma vez que o espaço de chave e a tabela são criados, invocamos operações CRUD (parte do operations\crud.go).

InsertUser é usado para criar um Userarquivo . Ele define as informações do usuário (ID, nome e cidade) como os argumentos de consulta usando 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 é usado para procurar um usuário (model\user.go) usando um ID de usuário específico enquanto Scan vincula os atributos de usuário (retornados por Cassandra) a variáveis individuais (userid, name, city) - é apenas uma das maneiras pelas quais você pode usar o resultado obtido como o 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 é usado para buscar todos os usuários. SliceMap é usado como uma abreviatura para obter todas as informações do usuário na forma de uma fatia de maps. Pense em cada map um como pares chave-valor onde o nome da coluna (por exemplo, user_id) é a chave juntamente com seu 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 do usuário é convertida em uma User função using mapToUser que simplesmente extrai o valor de sua respetiva coluna e o usa para criar uma instância do User struct

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

Como mencionado anteriormente, o aplicativo aceita conectividade e credenciais na forma de variáveis de ambiente.

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

    Exibir e copiar detalhes da página Cadeia de Conexão no portal do Azure

Copie os valores para os seguintes atributos (CONTACT POINT, PORTUSERNAME , e PRIMARY PASSWORD) e defina-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"
  1. No terminal, execute o seguinte comando para iniciar o aplicativo.
go run main.go

  1. A janela do terminal exibe notificações para as várias operações, incluindo keyspace e configuração de tabela, criação de usuário, etc

  2. No portal do Azure, abra o Data Explorer para consultar, modificar e trabalhar com estes dados novos.

    Exibir os dados no Data Explorer - Azure Cosmos DB

Rever os SLAs no portal do Azure

O portal do Azure monitora a taxa de transferência, o armazenamento, a disponibilidade, a latência e a consistência da sua conta do Azure Cosmos DB. Os gráficos para métricas associadas a um SLA (Service Level Agreement, contrato de nível de serviço) do Azure Cosmos DB mostram o valor do SLA em comparação com o desempenho real. Esse conjunto de métricas torna transparente o monitoramento de seus SLAs.

Para rever métricas e SLAs:

  1. Selecione Métricas no menu de navegação da sua conta do Azure Cosmos DB.

  2. Selecione uma guia, como Latência, e selecione um período à direita. Compare as linhas Real e SLA nos gráficos.

    Conjunto de métricas do Azure Cosmos DB

  3. Analise as métricas nas outras guias.

Clean up resources (Limpar recursos)

Quando terminar de usar seu aplicativo e sua conta do Azure Cosmos DB, você poderá excluir os recursos do Azure criados para não incorrer em mais cobranças. Para eliminar os recursos:

  1. Na barra de Pesquisa do portal do Azure, procure e selecione Grupos de recursos.

  2. Na lista, selecione o grupo de recursos que você criou para este início rápido.

    Selecione o grupo de recursos a ser excluído

  3. Na página Visão geral do grupo de recursos, selecione Excluir grupo de recursos.

    Eliminar o grupo de recursos

  4. Na janela seguinte, introduza o nome do grupo de recursos a eliminar e, em seguida, selecione Eliminar.

Próximos passos

Neste início rápido, você aprendeu como criar uma conta do Azure Cosmos DB com a API para Cassandra e executar um aplicativo Go que cria um banco de dados e um contêiner Cassandra. Agora você pode importar dados adicionais para sua conta do Azure Cosmos DB.

Importar dados do Cassandra para o Azure Cosmos DB