Início Rápido: Criar um aplicativo do Cassandra com o .NET Core e o Azure Cosmos DB

  • Artigo

APLICA-SE AO: Cassandra

Este guia de início rápido mostra como usar o .NET Core e a API for Cassandra do Azure Cosmos DB para criar um aplicativo de perfil clonando um exemplo do GitHub. Este Início Rápido também mostra como usar o portal do Azure baseado na Web para criar uma conta do Azure Cosmos DB.

O Azure Cosmos DB é o serviço de banco de dados multimodelo distribuído globalmente da Microsoft. É possível criar e consultar rapidamente documentos, tabelas, valores-chave e bancos de dados de gráfico, todos os quais se beneficiam de recursos de distribuição global e escala horizontal e no núcleo do Azure Cosmos DB.

Pré-requisitos

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar. Como alternativa, você pode Experimentar o Azure Cosmos DB gratuitamente sem uma assinatura do Azure, sem ônus e sem compromisso.

Além disso, você precisa de:

  • Visual Studio mais recente com a carga de trabalho de desenvolvimento do Azure. É possível começar com o IDE do Visual Studio Communitygratuito. Habilite a carga de trabalho de desenvolvimento do Azure durante a instalação do Visual Studio.
  • Instale o Git para clonar o exemplo.

Criar uma conta de banco de dados

  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.

    The new account page for 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.

    The Azure portal Notifications pane

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

Clonar o aplicativo de exemplo

Agora, vamos trabalhar com o código. Agora vamos clonar um aplicativo do Cassandra do GitHub, definir a cadeia de conexão e executá-lo. Você verá como é fácil trabalhar usando dados de forma programática.

  1. Abra um prompt de comando. Crie uma pasta chamada git-samples. Em seguida, feche o prompt de comando.

    md "C:\git-samples"

  2. Abra uma janela de terminal de git, como git bash, e use o comando cd para alterar 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-dotnet-core-getting-started.git

  4. Depois, abra o arquivo de solução CassandraQuickStartSample no Visual Studio.

Examine o código

Esta etapa é opcional. Se você estiver interessado em aprender como o código cria os recursos de banco de dados,examine os snippets a seguir. Os snippets são todos obtidos do arquivo Program.cs no método async Task ProcessAsync() instalado na pasta C:\git-samples\azure-cosmos-db-cassandra-dotnet-core-getting-started\CassandraQuickStart. Caso contrário, você poderá pular para Atualizar sua cadeia de conexão.

  • Inicialize a sessão conectando-se a um ponto de extremidade do cluster Cassandra. A API for Cassandra no Azure Cosmos DB só dá suporte ao TLSv1.2.

    var options = new Cassandra.SSLOptions(SslProtocols.Tls12, true, ValidateServerCertificate);
options.SetHostNameResolver((ipAddress) => CASSANDRACONTACTPOINT);
Cluster cluster = Cluster
    .Builder()
    .WithCredentials(USERNAME, PASSWORD)
    .WithPort(CASSANDRAPORT)
    .AddContactPoint(CASSANDRACONTACTPOINT)
    .WithSSL(options)
    .Build()
;
ISession session = await cluster.ConnectAsync();

  • Remova o keyspace existente se ele já existir.

    await session.ExecuteAsync(new SimpleStatement("DROP KEYSPACE IF EXISTS uprofile"));

  • Crie um novo keyspace.

    await session.ExecuteAsync(new SimpleStatement("CREATE KEYSPACE uprofile WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 };"));

  • Crie uma nova tabela.

    await session.ExecuteAsync(new SimpleStatement("CREATE TABLE IF NOT EXISTS uprofile.user (user_id int PRIMARY KEY, user_name text, user_bcity text)"));

  • Insira entidades de usuário usando o objeto IMapper com uma nova sessão que se conecta ao keyspace do uprofile.

    await mapper.InsertAsync<User>(new User(1, "LyubovK", "Dubai"));

  • Consulte para obter todas as informações de usuário.

    foreach (User user in await mapper.FetchAsync<User>("Select * from user"))
{
    Console.WriteLine(user);
}

  • Consulte para obter uma informação única de usuário.

    mapper.FirstOrDefault<User>("Select * from user where user_id = ?", 3);

Atualizar sua cadeia de conexão

Agora, volte ao portal do Azure para obter informações sobre a cadeia de conexão e copiá-las para o aplicativo. As informações da cadeia de conexão permitem que seu aplicativo se comunique com o banco de dados hospedado.

  1. No portal do Azure, selecione Cadeia de Conexão.

  2. Use o botão no lado direito da tela para copiar o valor do NOME DE USUÁRIO.

    View and copy an access key in the Azure portal, Connection String page

  3. No Visual Studio, abra o arquivo Program.cs.

  4. Cole o valor do NOME DE USUÁRIO do portal sobre <PROVIDE> na linha 13.

    A linha 13 do Program.cs agora deve ser semelhante a

    private const string UserName = "cosmos-db-quickstart";

    Você também pode colar o mesmo valor em <PROVIDE> na linha 15 para o valor CONTACT POINT:

    private const string CassandraContactPoint = "cosmos-db-quickstarts.cassandra.cosmosdb.azure.com"; // DnsName

  5. Volte ao portal e copie o valor da SENHA. Cole o valor da SENHA do portal sobre <PROVIDE> na linha 14.

    A linha 14 do Program.cs agora deve ser semelhante a

    private const string Password = "2Ggkr662ifxz2Mg...==";

  6. Volte ao portal e copie o valor do PONTO DE CONTATO. Cole o valor do PONTO DE CONTATO do portal sobre <PROVIDE> na linha 16.

    A linha 16 de Program.cs agora será semelhante a

    private const string CASSANDRACONTACTPOINT = "quickstart-cassandra-api.cassandra.cosmos.azure.com";

  7. Salve o arquivo Program.cs.

Execute o aplicativo .NET Core

  1. No Visual Studio, selecione Ferramentas>Gerenciador de Pacotes do NuGet>Console do Gerenciador de Pacotes.

  2. No prompt de comando, use o comando a seguir para instalar o pacote NuGet do driver .NET.

    Install-Package CassandraCSharpDriver

  3. Aperte CTRL + F5 para executar o aplicativo. Seu aplicativo é exibido na janela do seu console.

    View and verify the output

    Pressione CTRL + C para interromper a execução do programa e feche a janela do console.

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

    View the data in Data Explorer

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.

    Azure Cosmos DB metrics suite

  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.

    Select the resource group to delete

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

    Delete the resource group

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

Próximas etapas

Neste início rápido, você aprendeu como criar uma conta do Azure Cosmos DB, como criar um contêiner usando o Data Explorer e como executar um aplicativo Web. Agora, você pode importar outros dados para sua conta do Azure Cosmos DB.

Importar dados do Cassandra para o Azure Cosmos DB