Quickstart: Azure Cosmos DB voor Apache Cassandra-clientbibliotheek voor .NET

Ga aan de slag met de Azure Cosmos DB voor Apache Cassandra-clientbibliotheek voor .NET om ongestructureerde gegevens op te slaan, te beheren en er query's op uit te voeren. Volg de stappen in deze handleiding om een nieuw account te maken, een .NET-clientbibliotheek te installeren, verbinding te maken met het account, algemene bewerkingen uit te voeren en uw uiteindelijke voorbeeldgegevens op te vragen.

API-referentiedocumentatie | Broncode bibliotheek | Pakket (NuGet)

Vereiste voorwaarden

• Een Azure-abonnement

  • Als je geen Azure-abonnement hebt, maak dan een gratis account aan voordat je begint.

• De nieuwste versie van de Azure CLI in Azure Cloud Shell.

  • Als u liever CLI-referentieopdrachten lokaal uitvoert, meldt u zich aan bij de Azure CLI met behulp van de az login opdracht.

• .NET SDK 9.0 of hoger

Installeren

Stel eerst de account- en ontwikkelomgeving voor deze handleiding in. In deze sectie wordt u begeleid bij het maken van een account, het verkrijgen van de referenties en het voorbereiden van uw ontwikkelomgeving.

Een account maken

Begin met het maken van een API voor een Apache Cassandra-account. Zodra het account is gemaakt, maakt u de keyspace- en tabelbronnen.

Referenties ophalen

Haal nu het wachtwoord op dat de clientbibliotheek moet gebruiken om een verbinding te maken met het onlangs gemaakte account.

Ontwikkelomgeving voorbereiden

Configureer vervolgens uw ontwikkelomgeving met een nieuw project en de clientbibliotheek. Deze stap is het laatste vereiste voordat u verdergaat met de rest van deze handleiding.

1. Begin in een lege map.

2. Een nieuwe .NET-consoletoepassing maken

   dotnet new console
   

3. Voeg het CassandraCSharpDriver pakket toe vanuit NuGet.

   dotnet add package CassandraCSharpDriver
   

4. Bouw het project.

   dotnet build
   

Objectmodel

Codevoorbeelden

• Client verifiëren
• Upsert-gegevens
• Gegevens lezen
• Gegevens opvragen

Client verifiëren

Begin met het verifiëren van de client met behulp van de referenties die eerder in deze handleiding zijn verzameld.

1. Open het bestand Program.cs in uw IDE (Integrated Development Environment).

2. Verwijder alle bestaande inhoud in het bestand.

3. Voeg gebruiksrichtlijnen toe voor de volgende naamruimten:

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

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

4. Maak tekenreeksconstante variabelen voor de referenties die eerder in deze handleiding zijn verzameld. Geef de variabelen usernameeen naam en passwordcontactPoint.

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

5. Maak een nieuw SSLoptions object om ervoor te zorgen dat u het TLS 1.2-protocol (Transport Layer Security) gebruikt, controleert op certificaatintrekking en voert geen extra certificeringsvalidatie aan de clientzijde uit.

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

6. Maak een nieuw Cluster object met behulp van de fluent-syntaxis Cluster.Builder() . Gebruik de referentie- en configuratievariabelen die in de vorige stappen zijn gemaakt.

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

7. Maak een nieuwe session variabele met behulp van de ConnectAsync methode die de naam van de doelsleutelruimte (cosmicworks) doorgeeft.

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

8. Maak een nieuwe mapper variabele met behulp van de Mapper klasseconstructor die de onlangs gemaakte session variabele doorgeeft.

   Mapper mapper = new(session);
   

Gegevens bijwerken of toevoegen

Vervolgens worden nieuwe gegevens in een tabel geplaatst. Upserting zorgt ervoor dat de gegevens op de juiste wijze worden gemaakt of vervangen, afhankelijk van of dezelfde gegevens al in de tabel aanwezig zijn.

1. Definieer een nieuw recordtype met de velden Product die overeenkomen met de tabel die u eerder in deze handleiding hebt gemaakt.

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

   Aanbeveling

   In .NET kunt u dit type in een ander bestand maken of maken aan het einde van het bestaande bestand.

2. Maak een nieuw object van het type Product. Sla het object op in een variabele met de naam 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. Roep asynchroon de InsertAsync methode aan die wordt doorgegeven in de product variabele die in de vorige stap is gemaakt.

   await mapper.InsertAsync(product);
   

Gegevens lezen

Lees vervolgens gegevens die eerder in de tabel zijn geplaatst.

1. Maak een nieuwe tekenreeksvariabele met de naam readQuery en een CQL-query die overeenkomt met items met hetzelfde id-veld.

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

2. Maak een tekenreeksvariabele id met dezelfde waarde als het product dat eerder in deze handleiding is gemaakt.

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

3. Gebruik de SingleAsync<> algemene methode om de query uit te voeren die is opgeslagen, readQuerygeef de id variabele door als argument en wijs de uitvoer toe aan het Product type. Sla het resultaat van deze bewerking op in een variabele van het type Product.

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

Gegevens opvragen

Gebruik ten slotte een query om alle gegevens te vinden die overeenkomen met een specifiek filter in de tabel.

1. Maak tekenreeksvariabelen met de naam findQuery en category met de CQL-query en de vereiste parameter.

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

2. Gebruik de twee tekenreeksvariabelen en de FetchAsync<> algemene methode om asynchroon meerdere resultaten op te vragen. Sla het resultaat van deze query op in een variabele van het type IEnumerable<Product> met de naam queriedProducts.

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

3. Gebruik een foreach lus om de queryresultaten te herhalen.

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

De code uitvoeren

Voer de zojuist gemaakte toepassing uit met behulp van een terminal in uw toepassingsmap.

dotnet run

De hulpbronnen opschonen

Wanneer u het account niet meer nodig hebt, verwijdert u het account uit uw Azure-abonnement door de resource te verwijderen .

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

Volgende stap