Snabbstart: Azure Cosmos DB för Apache Cassandra-klientbiblioteket för .NET

Kom igång med Azure Cosmos DB för Apache Cassandra-klientbiblioteket för .NET för att lagra, hantera och fråga ostrukturerade data. Följ stegen i den här guiden för att skapa ett nytt konto, installera ett .NET-klientbibliotek, ansluta till kontot, utföra vanliga åtgärder och köra frågor mot dina slutliga exempeldata.

API-referensdokumentation | Bibliotekets källkod | Paket (NuGet)

Förutsättningar

• En prenumeration på Azure

  • Om du inte har en Azure-prenumeration, skapa ett gratis konto innan du börjar.

• Den senaste versionen av Azure CLI i Azure Cloud Shell.

  • Om du föredrar att köra CLI-referenskommandon lokalt loggar du in på Azure CLI med hjälp az login av kommandot .

• .NET SDK 9.0 eller senare

Förbereda

Konfigurera först konto- och utvecklingsmiljön för den här guiden. Det här avsnittet beskriver hur du skapar ett konto, hämtar dess autentiseringsuppgifter och sedan förbereder utvecklingsmiljön.

Skapa ett konto

Börja med att skapa ett API för Apache Cassandra-konto. När kontot har skapats skapar du nyckelområdet och tabellresurserna.

Hämta autentiseringsuppgifter

Hämta nu lösenordet för klientbiblioteket som ska användas för att skapa en anslutning till det nyligen skapade kontot.

Förbereda utvecklingsmiljön

Konfigurera sedan utvecklingsmiljön med ett nytt projekt och klientbiblioteket. Det här steget är det sista nödvändiga kravet innan du går vidare till resten av den här guiden.

1. Börja i en tom katalog.

2. Skapa ett nytt .NET-konsolprogram

   dotnet new console
   

3. CassandraCSharpDriver Lägg till paketet från NuGet.

   dotnet add package CassandraCSharpDriver
   

4. Skapa projektet.

   dotnet build
   

Objektmodell

Kodexempel

• Autentisera klient
• Upsert-data
• Läsa data
• Fråga efter data

Autentisera klient

Börja med att autentisera klienten med de autentiseringsuppgifter som samlats in tidigare i den här guiden.

1. Öppna filen Program.cs i din integrerade utvecklingsmiljö (IDE).

2. Ta bort befintligt innehåll i filen.

3. Lägg till med hjälp av direktiv för följande namnområden:

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

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

4. Skapa konstanta strängvariabler för de autentiseringsuppgifter som samlats in tidigare i den här guiden. Ge variablerna username, password och contactPoint namn.

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

5. Skapa ett nytt SSLoptions objekt för att säkerställa att du använder TLS-protokollet (Transport Layer Security) 1.2, kontrollerar om certifikatet återkallas och inte utför någon extra certifieringsverifiering på klientsidan.

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

6. Konstruera ett nytt Cluster objekt med hjälp av fluent-syntaxen Cluster.Builder() . Använd de autentiserings- och konfigurationsvariabler som skapades i föregående steg.

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

7. Skapa en ny session variabel med hjälp av metoden ConnectAsync som skickar in namnet på målnyckelområdet (cosmicworks).

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

8. Skapa en ny mapper variabel med hjälp Mapper av klasskonstruktorn som skickar in den nyligen skapade session variabeln.

   Mapper mapper = new(session);
   

Infoga eller uppdatera data

Därefter ökar du nya data till en tabell. Upserting säkerställer att data skapas eller ersätts på lämpligt sätt beroende på om samma data redan finns i tabellen.

1. Definiera en ny posttyp med namnet Product med fält som motsvarar de fält i tabellen som skapades tidigare i den här guiden.

   	Typ
   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; }
   }
   

   Tips/Råd

   I .NET kan du skapa den här typen i en annan fil eller skapa den i slutet av den befintliga filen.

2. Skapa ett nytt objekt av typen Product. Lagra objektet i en variabel med namnet 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. Anropa asynkront metoden InsertAsync som skickar variabeln product som skapades i föregående steg.

   await mapper.InsertAsync(product);
   

Läs data

Läs sedan data som tidigare har laddats upp i tabellen.

1. Skapa en ny strängvariabel med namnet readQuery med en CQL-fråga som matchar objekt med samma id fält.

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

2. Skapa en strängvariabel id med namnet med samma värde som den produkt som skapades tidigare i den här guiden.

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

3. Använd den SingleAsync<> generiska metoden för att köra frågan som lagras i readQuery, skicka in variabeln id som ett argument och mappa utdata till Product typen. Lagra resultatet av den här åtgärden i en variabel av typen Product.

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

Fråga efter data

Slutligen använder du en fråga för att hitta alla data som matchar ett specifikt filter i tabellen.

1. Skapa strängvariabler med namnet findQuery och category med CQL-frågan och den obligatoriska parametern.

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

2. Använd de två strängvariablerna och den FetchAsync<> generiska metoden för att asynkront fråga efter flera resultat. Lagra resultatet av den här frågan i en variabel av typen IEnumerable<Product> med namnet queriedProducts.

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

3. Använd en foreach loop för att iterera över frågeresultaten.

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

Kör koden

Kör det nyligen skapade programmet med hjälp av en terminal i programkatalogen.

dotnet run

Rensa resurser

När du inte längre behöver kontot tar du bort kontot från din Azure-prenumeration genom att ta bort resursen.

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

Nästa steg