Rychlý začátek: Klientská knihovna Azure Cosmos DB pro Apache Cassandra pro Node.js

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

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

Referenční dokumentace k | rozhraní API – Balíček zdrojového kódu | knihovny (npm)

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.

• Node.js 22 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 keyspace a tabulky.

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 na zdroj a dostanete se 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é složce.

2. Inicializace nového modulu

   npm init es6 --yes
   

3. cassandra-driver Nainstalujte balíček z Node Package Manageru (npm).

   npm install --save cassandra-driver
   

4. Vytvořte soubor index.js .

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

2. Inicializace nového modulu

   npm init es6 --yes
   

3. typescript Nainstalujte balíček z Node Package Manageru (npm).

   npm install --save-dev typescript
   

4. tsx Nainstalujte balíček z npm.

   npm install --save-dev tsx
   

5. cassandra-driver Nainstalujte balíček z npm.

   npm install --save cassandra-driver
   

6. Inicializace projektu TypeScript pomocí kompilátoru (tsc).

   npx tsc --init --target es2017 --module es2022 --moduleResolution nodenext
   

7. Vytvořte soubor index.ts .

Objektový model

	Popis
Client	Představuje konkrétní připojení ke 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 index.js v integrovaném vývojovém prostředí (IDE).

2. Importujte z cassandra-driver modulu následující typy:

   • cassandra
   • cassandra.Client
   • cassandra.mapping.Mapper
   • cassandra.auth.PlainTextAuthProvider

   import cassandra from 'cassandra-driver';
   
   const { Client } = cassandra;
   const { Mapper } = cassandra.mapping;
   const { PlainTextAuthProvider } = cassandra.auth;
   

3. 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 username = '<username>';
   const password = '<password>';
   const contactPoint = '<contact-point>';
   

4. Vytvořte další řetězcovou proměnnou pro oblast, ve které jste vytvořili účet Azure Cosmos DB for Apache Cassandra. Pojmenujte tuto proměnnou region.

   const region = '<azure-region>';
   

5. Vytvořte nový PlainTextAuthProvider objekt s přihlašovacími údaji zadanými v předchozích krocích.

   let authProvider = new PlainTextAuthProvider(
       username,
       password
   );
   

6. Vytvořte Client objekt pomocí přihlašovacích údajů a konfiguračních proměnných vytvořených v předchozích krocích.

   let client = new Client({
       contactPoints: [`${contactPoint}:10350`],
       authProvider: authProvider,
       localDataCenter: region,
       sslOptions: {
           secureProtocol: 'TLSv1_2_method'
       },
   });
   

7. Asynchronně se připojte ke clusteru.

   await client.connect();
   

8. Vytvořte nový mapovač, který cílí na cosmicworks prostor klíčů a product tabulku. Pojmenujte mapovač Product.

   const mapper = new Mapper(client, {
       models: {
           'Product': {
               tables: ['product'],
               keyspace: 'cosmicworks'
           }
       }
   });
   

9. Vygenerujte instanci mapperu forModel pomocí funkce a názvu mapperu Product .

   const productMapper = mapper.forModel('Product');
   

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

2. Importujte z cassandra-driver modulu následující typy:

   • cassandra.auth
   • cassandra.mapping
   • cassandra.types
   • cassandra.Client
   • cassandra.ClientOptions
   • cassandra.mapping.Mapper
   • cassandra.auth.PlainTextAuthProvider

   import { auth, mapping, types, Client, ClientOptions } from 'cassandra-driver';
   
   const { Mapper } = mapping;
   const { PlainTextAuthProvider } = auth;
   

3. 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 username: string = '<username>';
   const password: string = '<password>';
   const contactPoint: string = '<contact-point>';
   

4. Vytvořte další řetězcovou proměnnou pro oblast, ve které jste vytvořili účet Azure Cosmos DB for Apache Cassandra. Pojmenujte tuto proměnnou region.

   const region: string = '<azure-region>';
   

5. Vytvořte nový PlainTextAuthProvider objekt s přihlašovacími údaji zadanými v předchozích krocích.

   let authProvider = new PlainTextAuthProvider(
       username,
       password
   );
   

6. Vytvořte anonymní objekt s možnostmi, které zajistí, že používáte protokol TLS (Transport Layer Security) 1.2.

   let sslOptions = {
       secureProtocol: 'TLSv1_2_method'
   };
   

7. Vytvořte ClientOptions objekt pomocí přihlašovacích údajů a konfiguračních proměnných vytvořených v předchozích krocích.

   let clientOptions: ClientOptions = {
       contactPoints: [`${contactPoint}:10350`],
       authProvider: authProvider,
       localDataCenter: region,
       sslOptions: sslOptions
   };
   

8. Vytvořte Client objekt pomocí clientOptions proměnné v konstruktoru.

   let client = new Client(clientOptions);
   

9. Asynchronně se připojte ke clusteru.

   await client.connect();
   

10. Vytvořte nový mapovač, který cílí na cosmicworks prostor klíčů a product tabulku. Pojmenujte mapovač Product.

    const mapper = new Mapper( client, {
        models: {
            'Product': {
                tables: ['product'],
                keyspace: 'cosmicworks'
            }
        }
    });
    

11. Vygenerujte instanci mapperu forModel pomocí funkce a názvu mapperu Product .

    const productMapper = mapper.forModel('Product');
    

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. Vytvořte nový objekt v proměnné s názvem product.

   const product = {
       id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
       name: 'Yamba Surfboard',
       category: 'gear-surf-surfboards',
       quantity: 12,
       price: 850.00,
       clearance: false
   };
   

2. Asynchronně vyvolejte funkci insert a předejte proměnnou product vytvořenou v předchozím kroku.

   await productMapper.insert(product);
   

1. Definujte nové rozhraní 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

   interface Product {
       id: string;
       name: string;
       category: string;
       quantity: number;
       price: number;
       clearance: boolean;
   }
   

   Návod

   V Node.jsmůž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.

   const product: Product = {
       id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
       name: 'Yamba Surfboard',
       category: 'gear-surf-surfboards',
       quantity: 12,
       price: 850.00,
       clearance: false
   };
   

3. Asynchronně vyvolejte funkci insert a předejte proměnnou product vytvořenou v předchozím kroku.

   await productMapper.insert(product);
   

Čtení dat

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

1. Vytvořte anonymní objekt s názvem filter. V tomto objektu uveďte vlastnost s názvem id se stejnou hodnotou jako produkt vytvořený dříve v této příručce.

   const filter = {
       id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
   };
   

2. Vyvolejte funkci get mapperu a předejte proměnnou filter. Uložte výsledek do proměnné s názvem matchedProduct.

   let matchedProduct = await productMapper.get(filter);
   

1. Vytvořte anonymní objekt s názvem filter. V tomto objektu uveďte vlastnost s názvem id se stejnou hodnotou jako produkt vytvořený dříve v této příručce.

   const filter = {
       id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
   };
   

2. Vyvolejte funkci get mapperu a předejte proměnnou filter. Uložte výsledek do proměnné s názvem matchedProduct typu Product.

   let matchedProduct: Product = await productMapper.get(filter);
   

Dotaz k datům

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

1. Vytvořte novou řetězcovou proměnnou pojmenovanou query s dotazem CQL, který vyhledává položky se stejným polem category.

   const query = `
   SELECT
       *
   FROM
       cosmicworks.product
   WHERE
       category = :category
   ALLOW FILTERING
   `;
   

2. Vytvořte anonymní objekt s názvem params. V tomto objektu uveďte vlastnost s názvem category se stejnou hodnotou jako produkt vytvořený dříve v této příručce.

   const params = {
       category: 'gear-surf-surfboards'
   };
   

3. Asynchronně zavolejte funkci execute s proměnnými query a params jako argumenty. Uložte vlastnost výsledku rows jako proměnnou s názvem matchedProducts.

   let { rows: matchedProducts } = await client.execute(query, params);
   

4. Iterujte výsledky dotazu vyvoláním foreach metody v poli produktů.

   matchedProducts.forEach(product => {
       // Do something here with each result
   });
   

1. Vytvořte novou řetězcovou proměnnou pojmenovanou query s dotazem CQL, který vyhledává položky se stejným polem category.

   const query: string = `
   SELECT
       *
   FROM
       cosmicworks.product
   WHERE
       category = :category
   ALLOW FILTERING
   `;
   

2. Vytvořte anonymní objekt s názvem params. V tomto objektu uveďte vlastnost s názvem category se stejnou hodnotou jako produkt vytvořený dříve v této příručce.

   const params = {
       category: 'gear-surf-surfboards'
   };
   

3. Asynchronně zavolejte funkci execute s proměnnými query a params jako argumenty. Uložte výsledek do proměnné s názvem result typu types.ResultSet.

   let result: types.ResultSet = await client.execute(query, params);
   

4. Uložte vlastnost výsledku rows jako proměnnou s názvem matchedProducts typu Product[].

   let matchedProducts: Product[] = result.rows;
   

5. Iterujte výsledky dotazu vyvoláním foreach metody v poli produktů.

   matchedProducts.forEach((product: Product) => {
       // 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.

node index.js

npx tsx index.ts

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