Compartilhar via

Início rápido: criar um aplicativo Go com o cliente do gocql para gerenciar dados do Azure Cosmos DB for Apache Cassandra

  • Artigo

APLICA-SE AO: 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, pares chave-valor e grafo com funcionalidades de escala horizontal e distribuição global. Neste guia de início rápido, você começará criando uma conta do Azure Cosmos DB for Apache Cassandra. Em seguida, você executará um aplicativo Go para criar um keyspace do Cassandra, uma tabela e executar algumas operações. Esse aplicativo Go usa o gocql, que é um cliente do Cassandra para a linguagem Go.

Pré-requisitos

Criar uma conta de banco de dados

Para criar um banco de dados, crie uma conta do Cassandra com o Azure Cosmos DB.

  1. No menu do portal do Azure ou na Home page, selecione Criar um recurso.

  2. Na página Novo, pesquise pelo Azure Cosmos DB e selecione-o.

  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 ser criada. O Azure Cosmos DB oferece cinco APIs: NoSQL para bancos de dados de documentos, Gremlin para bancos de dados de grafo, 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 guia de 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 uma Conta do Azure Cosmos DB, insira as configurações básicas da nova conta do Azure Cosmos DB.

    Configuração Valor Descrição
    Subscription Sua assinatura Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos DB.
    Grupo de recursos Create new

    Em seguida, digite o mesmo nome que o Nome da Conta    		 Selecione Criar novo. Em seguida, insira um novo nome de grupo de recursos para a conta. Para simplificar, use o mesmo nome que o Nome da Conta do Azure Cosmos DB.
    Nome da Conta Insira um nome exclusivo Insira um nome exclusivo para identificar a conta do Azure Cosmos DB. O URI da sua conta será cassandra.cosmos.azure.com acrescentado ao nome da conta exclusivo.

    O nome da conta pode usar apenas letras minúsculas, números e hifens (-) e deve ter de 3 a 31 caracteres.
    Location A região mais próxima dos usuários Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB. Use a localização mais próxima dos usuários para fornecer a eles 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 taxa de transferência provisionada. Selecione Sem servidor para criar uma conta no modo sem servidor.
    Aplicar o desconto por nível gratuito do Azure Cosmos DB Aplicar 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 para limitar a taxa de transferência da conta Isso será útil se você quiser limitar a taxa de transferência total da conta a um valor específico.

    Observação

    Você pode ter no máximo uma conta do nível gratuito do Azure Cosmos DB por assinatura do Azure e deve aceitar ao criar a conta. Se você não vir a opção de aplicar o desconto por nível gratuito, significa que outra conta da assinatura já foi habilitada com o nível gratuito.

    A página da nova conta do Azure Cosmos DB for Apache Cassandra

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

    Configuração Valor Descrição
    Redundância geográfica Desabilitar Habilite ou desabilite a distribuição global em sua conta emparelhando sua região com uma região de par. Você poderá adicionar mais regiões à sua conta posteriormente.
    Gravações de várias regiões Desabilitar A capacidade de gravação de 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 Disponibilidades Desabilitar As Zonas de Disponibilidade são localizações isoladas exclusivas em uma região do Azure. Cada zona é composta por um ou mais datacenters equipados com energia, resfriamento e rede independentes.

    Observação

    As seguintes opções não estarão disponíveis se você selecionar Sem servidor como Modo de capacidade:

    • Aplicar desconto por nível gratuito
    • Redundância geográfica
    • Gravações de várias regiões

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

    • Rede – configurar o acesso de uma rede virtual.
    • Política de Backup – configurar a política de backup periódica ou contínua.
    • Criptografia – use a chave gerenciada por serviço ou uma chave gerenciada pelo cliente.
    • Marcas – marcas são pares nome/valor que permitem categorizar recursos e exibir a cobrança consolidada por meio da aplicação da mesma marca a vários recursos e grupos de recursos.

  8. Selecione Examinar + criar.

  9. Examine as configurações da conta e selecione Criar. São necessários alguns minutos para criar a conta. Aguarde até que a página do portal exiba Sua implantação está concluída.

    O painel Notificações do portal do Azure

  10. Selecione Ir para recurso para ir para a página da conta do Azure Cosmos DB.

Clonar o aplicativo de exemplo

Comece clonando o aplicativo do GitHub.

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

    md "C:\git-samples"

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

    cd "C:\git-samples"

  3. Execute o comando a seguir para clonar o repositório de exemplo. Este comando cria uma cópia do aplicativo de exemplo no seu computador.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git

Examine o código

Esta etapa é opcional. Se estiver interessado em saber como o código cria os recursos de banco de dados, examine os snippets de código a seguir. Caso contrário, vá direto para Executar o aplicativo

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

A função GetSession é então chamada por meio da função main (main.go).

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

As informações de conectividade e as credenciais são aceitas na forma de variáveis de ambiente (resolvidas no 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")
    }
}

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

Como o nome sugere, a função DropKeySpaceIfExists remove o keyspace somente se ele 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")
}

A função CreateKeySpace é 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")
}

Isso é seguido da criação da tabela (user), que é responsável pela função 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")
}

Depois que o keyspace e a tabela são criados, invocamos operações CRUD (parte de operations\crud.go).

InsertUser é usado para criar um User. 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 pesquisar um usuário (model\user.go) usando uma ID de usuário específica, enquanto Scan associa os atributos de usuário (retornados pelo Cassandra) a variáveis individuais (userid, name e city); essa é apenas uma das maneiras de 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 função abreviada para obter todas as informações do usuário na forma de uma fatia de maps. Imagine cada map como pares chave-valor, em que o nome da coluna (por exemplo, user_id) é a chave junto com o respectivo 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 das informações do usuário é convertido em um User usando a função mapToUser que apenas extrai o valor da respectiva coluna e a usa para criar uma instância do struct 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}
}

Executar o aplicativo

Como mencionado anteriormente, o aplicativo aceita a conectividade e as credenciais no formato de variáveis de ambiente.

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

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

Copie os valores para os atributos a seguir (CONTACT POINT, PORT, USERNAME e PRIMARY PASSWORD) e defina-os com as respectivas 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 comando a seguir para iniciar o aplicativo.
go run main.go

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

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

    Exibir os dados no Data Explorer – Azure Cosmos DB

Examinar SLAs no Portal do Azure

O portal do Azure monitora a taxa de transferência, armazenamento, disponibilidade, latência e consistência da sua conta do Azure Cosmos DB. Gráficos de métricas associados a um SLA (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 o monitoramento dos SLAs transparente.

Para examinar as métricas e os SLAs:

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

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

    Pacote de métricas do Azure Cosmos DB

  3. Examine as métricas nas outras guias.

Limpar os recursos

Quando o aplicativo e a conta do Azure Cosmos DB estiverem prontos, você poderá excluir os recursos do Azure criados para não incorrer em mais cobranças. Para excluir 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 criado neste início rápido.

    Selecione o grupo de recursos a excluir

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

    Exclua o grupo de recursos

  4. Na próxima janela, insira o nome do grupo de recursos a ser excluído e selecione Excluir.

Próximas etapas

Neste guia de início rápido, você aprendeu a 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 do Cassandra. Agora, é possível importar outros dados para sua conta do Azure Cosmos DB.

Importar dados do Cassandra para o Azure Cosmos DB