Início Rápido: Biblioteca de clientes do Azure Cosmos DB for Apache Cassandra para .NET

Comece a usar a biblioteca cliente do Azure Cosmos DB para Apache Cassandra no .NET para armazenar, gerenciar e consultar dados não estruturados. Siga as etapas neste guia para criar uma nova conta, instalar uma biblioteca de clientes do .NET, conectar-se à conta, executar operações comuns e consultar seus dados de exemplo finais.

Documentação de referência da API | Código-fonte da biblioteca | Pacote (NuGet)

Pré-requisitos

• Uma assinatura do Azure

  • Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

• A versão mais recente da CLI do Azure no Azure Cloud Shell.

  • Se você preferir executar comandos de referência da CLI localmente, entre na CLI do Azure usando o az login comando.

• SDK do .NET 9.0 ou posterior

Configurando

Primeiro, configure a conta e o ambiente de desenvolvimento para este guia. Esta seção orienta você pelo processo de criação de uma conta, obtendo suas credenciais e, em seguida, preparando seu ambiente de desenvolvimento.

Criar uma conta

Comece criando uma conta da API para Apache Cassandra. Depois que a conta for criada, crie o keyspace e os recursos da tabela.

Obter credenciais

Agora, obtenha a senha da biblioteca de clientes a ser usada para criar uma conexão com a conta criada recentemente.

Prepare o ambiente de desenvolvimento

Em seguida, configure seu ambiente de desenvolvimento com um novo projeto e a biblioteca de clientes. Esta etapa é o último pré-requisito necessário antes de passar para o restante deste guia.

1. Inicie em um diretório vazio.

2. Criar um novo aplicativo de console do .NET

   dotnet new console
   

3. Adicione o pacote CassandraCSharpDriver do NuGet.

   dotnet add package CassandraCSharpDriver
   

4. Compile o projeto.

   dotnet build
   

Modelo de objeto

Exemplos de código

• Autenticar cliente
• Inserção ou atualização de dados
• Ler dados
• Consultar dados

Autenticar cliente

Comece autenticando o cliente usando as credenciais coletadas anteriormente neste guia.

1. Abra o arquivo Program.cs no IDE (ambiente de desenvolvimento integrado).

2. Exclua qualquer conteúdo existente no arquivo.

3. Adicione diretivas de uso para os seguintes namespaces:

   • System.Security.Authentication
   • Cassandra
   • Cassandra.Mapping

   using System.Security.Authentication;
   using Cassandra;
   using Cassandra.Mapping;
   

4. Crie variáveis constantes de cadeia de caracteres para as credenciais coletadas anteriormente neste guia. Nomeie as variáveis usernamee passwordcontactPoint.

   const string username = "<username>";
   const string password = "<password>";
   const string contactPoint = "<contact-point>";
   

5. Crie um novo SSLoptions objeto para garantir que você esteja usando o protocolo TLS (segurança da camada de transporte) 1.2, verificando a revogação de certificado e não executando nenhuma validação de certificação extra do lado do cliente.

   SSLOptions sslOptions = new(
       sslProtocol: SslProtocols.Tls12,
       checkCertificateRevocation: true,
       remoteCertValidationCallback: (_, _, _, _) => true);
   

6. Construa um novo Cluster objeto usando a sintaxe fluente Cluster.Builder() . Use as variáveis de credencial e configuração criadas nas etapas anteriores.

   Cluster cluster = Cluster.Builder()
       .WithCredentials(username, password)
       .WithPort(10350)
       .AddContactPoint(contactPoint)
       .WithSSL(sslOptions)
       .Build();
   

7. Crie uma nova session variável usando o ConnectAsync método que passa o nome do keyspace de destino (cosmicworks).

   using ISession session = await cluster.ConnectAsync("cosmicworks");
   

8. Crie uma nova variável mapper usando o construtor da classe Mapper, passando a variável session que foi criada recentemente.

   Mapper mapper = new(session);
   

Inserir ou atualizar dados

Em seguida, insira novos dados em uma tabela. O upserting garante que os dados sejam criados ou substituídos adequadamente, dependendo se os mesmos dados já existem na tabela.

1. Defina um novo tipo de registro nomeado Product com campos correspondentes à tabela criada anteriormente neste guia.

   	Tipo
   Id	string
   Name	string
   Category	string
   Quantity	int
   Price	decimal
   Clearance	bool

   record Product
   {
       public required string Id { get; init; }
   
       public required string Name { get; init; }
   
       public required string Category { get; init; }
   
       public required int Quantity { get; init; }
   
       public required decimal Price { get; init; }
   
       public required bool Clearance { get; init; }
   }
   

   Dica

   No .NET, você pode criar esse tipo em outro arquivo ou criá-lo no final do arquivo existente.

2. Criar um novo objeto do tipo Product. Armazene o objeto em uma variável chamada product.

   Product product = new()
   {
       Id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       Name = "Yamba Surfboard",
       Category = "gear-surf-surfboards",
       Quantity = 12,
       Price = 850.00m,
       Clearance = false
   };
   

3. Invoque o método InsertAsync de forma assíncrona passando a variável product criada na etapa anterior.

   await mapper.InsertAsync(product);
   

Ler dados

Em seguida, leia os dados que foram inseridos anteriormente na tabela.

1. Crie uma nova variável de cadeia de caracteres nomeada readQuery com uma consulta CQL que corresponda a itens com o mesmo id campo.

   string readQuery = "SELECT * FROM product WHERE id = ? LIMIT 1";
   

2. Crie uma variável de cadeia de caracteres nomeada id com o mesmo valor que o produto criado anteriormente neste guia.

   string id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
   

3. Utilize o método genérico SingleAsync<> para executar a consulta armazenada em readQuery, passar a variável id como argumento e mapear a saída para o tipo Product. Armazene o resultado dessa operação em uma variável do tipo Product.

   Product matchedProduct = await mapper.SingleAsync<Product>(readQuery, [id]);
   

Consultar dados

Por fim, use uma consulta para localizar todos os dados que correspondem a um filtro específico na tabela.

1. Crie variáveis de cadeia de caracteres nomeadas findQuery e category com a consulta CQL e o parâmetro necessário.

   string findQuery = "SELECT * FROM product WHERE category = ? ALLOW FILTERING";
   string category = "gear-surf-surfboards";
   

2. Use as duas variáveis de cadeia de caracteres e o FetchAsync<> método genérico para consultar de forma assíncrona vários resultados. Armazene o resultado dessa consulta em uma variável do tipo IEnumerable<Product> denominado queriedProducts.

   IEnumerable<Product> queriedProducts = await mapper.FetchAsync<Product>(findQuery, [category]);
   

3. Use um loop foreach para iterar sobre os resultados da consulta.

   foreach (Product queriedProduct in queriedProducts)
   {
       // Do something here with each result
   }
   

Executar o código

Execute o aplicativo recém-criado usando um terminal no diretório do aplicativo.

dotnet run

Limpar os recursos

Quando você não precisar mais da conta, remova a conta de sua assinatura do Azure excluindo o recurso.

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

Próxima etapa