Guia de início rápido: criar um aplicativo Apache Cassandra com o SDK do .NET e o Azure Cosmos DB

  • Artigo

APLICA-SE A: Cassandra

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

A Base de Dados Cosmos do Azure é um serviço de bases de dados com vários modelos da Microsoft distribuído globalmente. Pode criar e consultar rapidamente o documento, a tabela, a chave/valor e as bases de dados de gráficos que beneficiam de capacidades de escalamento horizontal e distribuição global no centro do Azure Cosmos DB.

Pré-requisitos

Se não tiver uma subscrição do Azure, crie uma conta gratuita do Azure antes de começar. Em alternativa, pode Experimentar o Azure Cosmos DB gratuitamente sem uma subscrição do Azure, sem encargos e compromissos.

Além disso, necessita:

  • Visual Studio mais recente com a carga de trabalho de desenvolvimento do Azure. Você pode começar a usar o IDE gratuitoda Comunidade do Visual Studio. Habilite a carga de trabalho de desenvolvimento do Azure durante a instalação do Visual Studio.
  • Instalar Git para clonar o exemplo.

Criar uma conta de base de dados

  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 Descrição
    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 novas , e formulários de aplicação do

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

    The new account page for Azure Cosmos DB for 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 Descrição
    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 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.

    The Azure portal Notifications pane

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

Clonar a aplicação de exemplo

Agora, vamos trabalhar com código. Vamos clonar uma API para o aplicativo Cassandra do GitHub, definir a cadeia de conexão e executá-la. Você verá com que facilidade pode trabalhar com dados programaticamente.

  1. Abra uma linha de comandos. Crie uma nova pasta com o nome git-samples. Em seguida, feche a linha de comandos.

    md "C:\git-samples"

  2. Abra uma janela de terminal do git, como o git bash e utilize o comando cd para alterar para uma nova pasta e instalar a aplicação 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-dotnet-getting-started.git

  4. Em seguida, abra o ficheiro da solução CassandraQuickStartSample no Visual Studio.

Rever o código

Este passo é opcional. Se estiver interessado em saber de que forma o código cria os recursos da base de dados, pode rever os fragmentos seguintes. Todos os fragmentos são retirados do ficheiro Program.cs instalado na pasta C:\git-samples\azure-cosmos-db-cassandra-dotnet-getting-started\CassandraQuickStartSample. Caso contrário, pode avançar diretamente para Update your connection string (Atualizar a cadeia de ligação).

  • Inicie a sessão através da ligação a um ponto final de cluster do Cassandra. A API para Cassandra no Azure Cosmos DB suporta apenas 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 = cluster.Connect();

  • Criar um keyspace novo.

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

  • Criar uma nova tabela.

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

  • Insira entidades de utilizador utilizando o objeto de IMapper com uma nova sessão que liga ao keyspace do perfil.

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

  • Efetue uma consulta para obter as informações de todos os utilizadores.

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

  • Efetue uma consulta para obter as informações de um único utilizador.

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

Atualizar a cadeia de ligação

Agora, regresse ao portal do Azure para obter as informações da cadeia de ligação e copie-as para a aplicação. As informações da cadeia de ligação permitem à aplicação comunicar com a base de dados alojada.

  1. No portal do Azure, clique em Cadeia de Ligação.

  2. Use o botão no lado direito da tela para copiar o valor USERNAME.

    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 UTILIZADOR do portal em <FILLME> na linha 13.

    A Linha 13 do Program.cs deve agora ter um aspeto semelhante a

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

  5. Volte ao portal e copie o valor do NOME DE UTILIZADOR. Cole o valor da PALAVRA-PASSE do portal em <FILLME> na linha 14.

    A Linha 14 do Program.cs deve agora ter um aspeto semelhante a

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

  6. Volte ao portal e copie o valor do PONTO DE CONTACTO. Cole o valor do PONTO DE CONTACTO do portal em <FILLME> na linha 15.

    A Linha 15 do Program.cs deve agora ter um aspeto semelhante a

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

  7. Guarde o ficheiro Program.cs.

Executar o aplicativo .NET

  1. No Visual Studio, selecione Ferramentas>Gestor de pacote NuGet>Consola do Gestor de Pacotes.

  2. Na linha de comandos, utilize o comando seguinte para instalar o pacote NuGet do controlador do .NET.

    Install-Package CassandraCSharpDriver

  3. Prima CTRL + F5 para executar a aplicação. A aplicação é apresentada na janela da consola.

    View and verify the output

    Prima CTRL + C para interromper a execução do programa e feche a janela da consola.

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

    View the data in Data Explorer

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 o monitoramento de seus SLAs transparente.

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.

    Azure Cosmos DB metrics suite

  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.

    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 janela seguinte, introduza o nome do grupo de recursos a eliminar e, em seguida, selecione Eliminar.

Próximos passos

Neste guia rápido, aprendeu a criar uma conta do Azure Cosmos DB, a criar uma coleção com o Data Explorer e a executar uma aplicação Web. Agora você pode importar outros dados para sua conta do Azure Cosmos DB.

Importar dados do Cassandra para o Azure Cosmos DB