Rychlý start: Klientská knihovna Azure Cosmos DB pro Apache Cassandra a .NET

• Python
• Node.js
• C#
• Java
• Pokračovat

Začínáme s klientskou knihovnou Azure Cosmos DB for Apache Cassandra pro .NET pro ukládání, správu a dotazování nestrukturovaných dat Podle kroků v tomto průvodci vytvořte nový účet, nainstalujte klientskou knihovnu .NET, připojte se k účtu, proveďte běžné operace a dotazujte se na konečná ukázková data.

Dokumentace k referenci API | Zdrojový kód knihovny | Balíček (NuGet)

Požadavky

• Předplatné Azure

  • Pokud nemáte předplatné Azure, vytvořte si bezplatný účet před zahájením.

• Nejnovější verze Azure CLI v Azure Cloud Shellu

  • Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, přihlaste se k Azure CLI pomocí az login příkazu.

• .NET SDK 9.0 nebo novější

Instalace

Nejprve pro tuto příručku nastavte účet a vývojové prostředí. Tato část vás provede procesem vytvoření účtu, získáním jeho přihlašovacích údajů a následnou přípravou vývojového prostředí.

Vytvoření účtu

Začněte vytvořením rozhraní API pro účet Apache Cassandra. Po vytvoření účtu vytvořte klíčový prostor a tabulkové zdroje.

Azure CLI

1. Pokud ještě nemáte cílovou skupinu prostředků, použijte az group create příkaz k vytvoření nové skupiny prostředků ve vašem předplatném.

   az group create \
       --name "<resource-group-name>" \
       --location "<location>"
   

2. az cosmosdb create Pomocí příkazu vytvořte nový účet Azure Cosmos DB pro Apache Cassandra s výchozím nastavením.

   az cosmosdb create \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --locations "regionName=<location>" \
       --capabilities "EnableCassandra"
   

3. Vytvořte nový keyspace pojmenovaný az cosmosdb cassandra keyspace createcosmicworks.

   az cosmosdb cassandra keyspace create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --name "cosmicworks"
   

4. Vytvořte nový objekt JSON, který bude reprezentovat schéma pomocí příkazu Bash s více řádky. Potom pomocí az cosmosdb cassandra table create příkazu vytvořte novou tabulku s názvem products.

   schemaJson=$(cat <<EOF
   {
     "columns": [
       {
         "name": "id",
         "type": "text"
       },
       {
         "name": "name",
         "type": "text"
       },
       {
         "name": "category",
         "type": "text"
       },
       {
         "name": "quantity",
         "type": "int"
       },
       {
         "name": "price",
         "type": "decimal"
       },
       {
         "name": "clearance",
         "type": "boolean"
       }
     ],
     "partitionKeys": [
       {
         "name": "id"
       }
     ]
   }
   EOF
   )
   

   az cosmosdb cassandra table create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --keyspace-name "cosmicworks" \
       --name "product" \
       --schema "$schemaJson"
   

Azure Portal

1. Přihlaste se k webu Azure Portal (https://portal.azure.com).

2. Do globálního panelu hledání zadejte Azure Cosmos DB .

3. V rámci služeb vyberte Azure Cosmos DB.

4. V podokně Azure Cosmos DB vyberte Vytvořit a potom Azure Cosmos DB for Apache Cassandra na kartě Ostatní.

5. Jako typ účtu vyberte účet databáze jednotky žádosti (RU ).

6. V podokně Základy nakonfigurujte následující možnosti a pak vyberte Zkontrolovat a vytvořit:

   	Hodnota
   Typ úlohy	Vzdělávání
   Předplatné	Výběr předplatného Azure
   Skupina prostředků	Vytvoření nové skupiny prostředků nebo výběr existující skupiny prostředků
   Název účtu	Zadejte globálně jedinečný název.
   Zóny dostupnosti	Zakázat
   Umístění	Vyberte podporovanou oblast Azure pro vaše předplatné.

   Návod

   U výchozích hodnot můžete ponechat všechny nezadané možnosti. Můžete také nakonfigurovat účet tak, aby omezil celkovou propustnost účtu na 1 000 jednotek žádostí za sekundu (RU/s), nebo povolit úroveň Free, aby se minimalizovaly náklady.

7. V podokně Zkontrolovat a vytvořit počkejte na úspěšné ověření účtu a pak vyberte Vytvořit.

8. Portál automaticky přejde do podokna Nasazení . Počkejte, až se nasazení dokončí.

9. Po dokončení nasazení vyberte Přejít k prostředku a přejděte do nového rozhraní API pro účet Apache Cassandra.

10. V nabídce prostředků vyberte možnost Průzkumník dat .

11. V Průzkumníku dat vyberte + Nová tabulka.

12. V dialogovém okně Přidat tabulku nakonfigurujte následující možnosti a pak vyberte OK:

    	Hodnota
    Keyspace	Create new
    Název prostoru klíčů	cosmicworks
    Název tabulky	product
    Schéma tabulky	(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))

    Návod

    U výchozích hodnot můžete ponechat všechny nezadané možnosti.

Získání přihlašovacích údajů

Teď získejte heslo pro klientskou knihovnu, které se má použít k vytvoření připojení k nedávno vytvořenému účtu.

Azure CLI

1. Slouží az cosmosdb show k získání kontaktního bodu a uživatelského jména pro účet.

   az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "{username:name,contactPoint:documentEndpoint}"
   

2. Poznamenejte si hodnotu contactPoint a username vlastnosti z výstupu předchozích příkazů. Hodnoty těchto vlastností jsou kontaktní bod a uživatelské jméno , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

3. Slouží az cosmosdb keys list k získání klíčů pro účet.

   az cosmosdb keys list \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --type "keys"
   

4. Poznamenejte si hodnotu primaryMasterKey vlastnosti z výstupu předchozích příkazů. Hodnota této vlastnosti je heslo , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

Azure Portal

1. V nabídce prostředků pro účet vyberte možnost Připojovací řetězce v části Nastavení .

2. Poznamenejte si hodnotu pole KONTAKTNÍ BOD na této stránce. Hodnota této vlastnosti je kontaktní bod , který použijete později v tomto průvodci pro připojení k účtu s knihovnou.

3. Poznamenejte si hodnotu pole USERNAME na této stránce. Hodnota této vlastnosti je uživatelské jméno , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

4. Zveřejnit a zaznamenat hodnotu pole PRIMÁRNÍ HESLO na této stránce. Hodnota této vlastnosti je heslo , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

Příprava vývojového prostředí

Potom nakonfigurujte vývojové prostředí s novým projektem a klientskou knihovnou. Tento krok je posledním požadovaným předpokladem před přechodem na zbytek této příručky.

1. Začněte v prázdném adresáři.

2. Vytvoření nové konzolové aplikace .NET

   dotnet new console
   

3. CassandraCSharpDriver Přidejte balíček z NuGetu.

   dotnet add package CassandraCSharpDriver
   

4. Zkompilujte projekt.

   dotnet build
   

Objektový model

	Popis
Cluster	Představuje stav připojení ke clusteru.
ISession	Entity vláknově bezpečné, které obsahují určité připojení k clusteru
Mapper	Klient Cassandra Query Language (CQL) používaný ke spouštění dotazů

Příklady kódu

• Ověření klienta
• Provést operaci Upsert (aktualizace nebo vložení) na data
• Čtení dat
• Dotazování dat

Ověření klienta

Začněte ověřením klienta pomocí přihlašovacích údajů shromážděných dříve v této příručce.

1. Otevřete soubor Program.cs v integrovaném vývojovém prostředí (IDE).

2. Odstraňte veškerý existující obsah v souboru.

3. Přidejte direktivy using pro následující obory názvů:

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

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

4. Vytvořte proměnné řetězcové konstanty pro přihlašovací údaje shromážděné dříve v tomto průvodci. Pojmenujte proměnné username, passworda contactPoint.

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

5. Vytvořte nový SSLoptions objekt, abyste zajistili, že používáte protokol TLS (Transport Layer Security) 1.2, kontrolujete odvolání certifikátu a neprovádíte žádné další ověření certifikace na straně klienta.

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

6. Vytvořte nový Cluster objekt pomocí fluent Cluster.Builder() syntaxe. Použijte přihlašovací údaje a konfigurační proměnné vytvořené v předchozích krocích.

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

7. Vytvořte novou session proměnnou pomocí ConnectAsync metody, která předává název cílového prostoru klíčů (cosmicworks).

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

8. Vytvořte novou mapper proměnnou pomocí konstruktoru Mapper třídy, který předává nedávno vytvořenou session proměnnou.

   Mapper mapper = new(session);
   

Výstraha

Úplné ověření protokolu TLS (Transport Layer Security) je v tomto průvodci zakázané, aby se zjednodušilo ověřování. Pro produkční nasazení plně povolte ověřování.

Vložit nebo aktualizovat data

V dalším kroku přepište nová data do tabulky. Přenesení zajistí, že se data vytvoří nebo nahradí odpovídajícím způsobem v závislosti na tom, jestli stejná data již v tabulce existují.

1. Definujte nový typ záznamu s Product poli odpovídajícími tabulce vytvořené dříve v této příručce.

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

   Návod

   V .NET můžete tento typ vytvořit v jiném souboru nebo ho vytvořit na konci existujícího souboru.

2. Vytvořte nový objekt typu Product. Uložte objekt do proměnné s názvem 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. Asynchronně vyvoláte metodu InsertAsync , která předává proměnnou product vytvořenou v předchozím kroku.

   await mapper.InsertAsync(product);
   

Čtení dat

Potom načtěte data, která byla dříve převedena do tabulky.

1. Vytvořte novou řetězcovou proměnnou pojmenovanou readQuery s dotazem CQL, který odpovídá položkám se stejným polem id.

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

2. Vytvořte řetězcovou proměnnou s názvem id se stejnou hodnotou jako produkt vytvořený dříve v této příručce.

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

3. SingleAsync<> Pomocí obecné metody spusťte dotaz uložený v readQuery, předejte id proměnnou jako argument a namapujte výstup na Product typ. Uložte výsledek této operace do proměnné typu Product.

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

Dotaz k datům

Nakonec pomocí dotazu najděte všechna data, která odpovídají určitému filtru v tabulce.

1. Vytvořte řetězcové proměnné pojmenované findQuery a category pomocí dotazu CQL a požadovaného parametru.

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

2. Pomocí dvou řetězcových proměnných a FetchAsync<> obecné metody můžete asynchronně dotazovat více výsledků. Uložte výsledek tohoto dotazu do proměnné typu IEnumerable<Product> s názvem queriedProducts.

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

3. foreach Pomocí smyčky iterujte výsledky dotazu.

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

Spuštění kódu

Spusťte nově vytvořenou aplikaci pomocí terminálu v adresáři vaší aplikace.

dotnet run

Vyčistěte zdroje

Pokud účet už nepotřebujete, odeberte ho z předplatného Azure odstraněním prostředku.

Azure CLI

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

Azure Portal

1. Přejděte k existujícímu prostředku Azure Cosmos DB for Apache Cassandra , který jste vytvořili dříve v této příručce.

2. Na stránce zdroje vyberte na panelu nástrojů Odstranit.

3. Postupujte podle pokynů v potvrzovacím dialogovém okně.

Další krok

Přehled služby Azure Cosmos DB pro Apache Cassandra