Dela via

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

  • Gäller för: ✅ Apache Cassanda

Kom igång med Azure Cosmos DB för Apache Cassandra-klientbiblioteket för Node.js 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 Node.js klientbibliotek, ansluta till kontot, utföra vanliga åtgärder och köra frågor mot dina slutliga exempeldata.

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

  1. Om du inte redan har en målresursgrupp använder du az group create kommandot för att skapa en ny resursgrupp i din prenumeration.

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

  2. az cosmosdb create Använd kommandot för att skapa ett nytt Azure Cosmos DB för Apache Cassandra-konto med standardinställningar.

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

  3. Skapa ett nytt keyspace med az cosmosdb cassandra keyspace create namnet cosmicworks.

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

  4. Skapa ett nytt JSON-objekt som representerar schemat med hjälp av ett Bash-kommando med flera rader. az cosmosdb cassandra table create Använd sedan kommandot för att skapa en ny tabell med namnet 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"

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.

  1. Använd az cosmosdb show för att hämta kontaktpunkten och användarnamnet för kontot.

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

  2. Registrera värdet för contactPoint egenskaperna och username från föregående kommandons utdata. Dessa egenskapers värden är kontaktpunkten och användarnamnet som du använder senare i den här guiden för att ansluta till kontot med biblioteket.

  3. Använd az cosmosdb keys list för att hämta nycklarna för kontot.

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

  4. Registrera värdet för primaryMasterKey egenskapen från föregående kommandons utdata. Den här egenskapens värde är det lösenord som du använder senare i den här guiden för att ansluta till kontot med biblioteket.

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. Starta i en tom mapp.

  2. Initiera en ny modul.

    npm init es6 --yes

  3. cassandra-driver Installera paketet från Node Package Manager (npm).

    npm install --save cassandra-driver

  4. Skapa filenindex.js .

  1. Börja i en tom katalog.

  2. Initiera en ny modul.

    npm init es6 --yes

  3. typescript Installera paketet från Node Package Manager (npm).

    npm install --save-dev typescript

  4. tsx Installera paketet från npm.

    npm install --save-dev tsx

  5. cassandra-driver Installera paketet från npm.

    npm install --save cassandra-driver

  6. Initiera TypeScript-projektet med hjälp av kompilatorn (tsc).

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

  7. Skapa filen index.ts .

Objektmodell

Beskrivning
Client Representerar en specifik anslutning till ett kluster
Mapper Cassandra Query Language-klienten (CQL) som används för att köra frågor

Kodexempel

Autentisera klient

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

  1. Öppna filenindex.js i din integrerade utvecklingsmiljö (IDE).

  2. Importera följande typer från modulen cassandra-driver :

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

  4. Skapa en annan strängvariabel för den region där du skapade ditt Azure Cosmos DB för Apache Cassandra-kontot. Ge variabeln region namnet.

    const region = '<azure-region>';

  5. Skapa ett nytt PlainTextAuthProvider objekt med de autentiseringsuppgifter som angavs i föregående steg.

    let authProvider = new PlainTextAuthProvider(
    username,
    password
);

  6. Skapa ett Client objekt med hjälp av variablerna för autentiseringsuppgifter och konfiguration som skapades i föregående steg.

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

  7. Anslut asynkront till klustret.

    await client.connect();

  8. Skapa en ny mappning som riktar sig till cosmicworks nyckelområdet och product tabellen. Namnge mapparen Product.

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

  9. Generera en mappningsinstans med hjälp av forModel funktionen och mappningsnamnet Product .

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

  1. Öppna filen index.ts i din integrerade utvecklingsmiljö (IDE).

  2. Importera följande typer från modulen cassandra-driver :

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

  4. Skapa en annan strängvariabel för den region där du skapade ditt Azure Cosmos DB för Apache Cassandra-kontot. Ge variabeln region namnet.

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

  5. Skapa ett nytt PlainTextAuthProvider objekt med de autentiseringsuppgifter som angavs i föregående steg.

    let authProvider = new PlainTextAuthProvider(
    username,
    password
);

  6. Skapa ett anonymt objekt med alternativ som säkerställer att du använder TLS-protokollet (Transport Layer Security) 1.2.

    let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};

  7. Skapa ett ClientOptions objekt med hjälp av variablerna för autentiseringsuppgifter och konfiguration som skapades i föregående steg.

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

  8. Skapa ett Client objekt med variabeln clientOptions i konstruktorn.

    let client = new Client(clientOptions);

  9. Anslut asynkront till klustret.

    await client.connect();

  10. Skapa en ny mappning som riktar sig till cosmicworks nyckelområdet och product tabellen. Namnge mapparen Product.

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

  11. Generera en mappningsinstans med hjälp av forModel funktionen och mappningsnamnet Product .

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

Varning

Fullständig TLS-validering (Transport Layer Security) är inaktiverad i den här guiden för att förenkla autentiseringen. Aktivera validering fullt ut för produktionsdistributioner.

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. Skapa ett nytt objekt i en variabel med namnet product.

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

  2. Asynkront anropa funktionen insert som skickar variabeln product som skapades i föregående steg.

    await productMapper.insert(product);

  1. Definiera ett nytt gränssnitt med namnet Product med fält som motsvarar tabellen som skapades tidigare i den här guiden.

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

    Tips/Råd

    I Node.jskan 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.

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

  3. Asynkront anropa funktionen insert som skickar variabeln product som skapades i föregående steg.

    await productMapper.insert(product);

Läs data

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

  1. Skapa ett anonymt objekt med namnet filter. I det här objektet inkluderar du en egenskap id med namnet med samma värde som den produkt som skapades tidigare i den här guiden.

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

  2. Anropa get-funktionen på mapparen genom att skicka variabeln filter. Lagra resultatet i en variabel med namnet matchedProduct.

    let matchedProduct = await productMapper.get(filter);

  1. Skapa ett anonymt objekt med namnet filter. I det här objektet inkluderar du en egenskap id med namnet med samma värde som den produkt som skapades tidigare i den här guiden.

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

  2. Anropa get-funktionen på mapparen genom att skicka variabeln filter. Lagra resultatet i en variabel med namnet matchedProduct av typen Product.

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

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 en ny strängvariabel med namnet query med en CQL-fråga som matchar objekt med samma category fält.

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

  2. Skapa ett anonymt objekt med namnet params. I det här objektet inkluderar du en egenskap category med namnet med samma värde som den produkt som skapades tidigare i den här guiden.

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

  3. Anropa funktionen asynkront execute och skicka både variablerna query och params som argument. Lagra resultatets rows egenskap som en variabel med namnet matchedProducts.

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

  4. Iterera över frågeresultaten genom att foreach anropa metoden i matrisen med produkter.

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

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

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

  2. Skapa ett anonymt objekt med namnet params. I det här objektet inkluderar du en egenskap category med namnet med samma värde som den produkt som skapades tidigare i den här guiden.

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

  3. Anropa funktionen asynkront execute och skicka både variablerna query och params som argument. Lagra resultatet i en variabel med namnet result av typen types.ResultSet.

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

  4. Lagra resultatets rows egenskap som en variabel med namnet matchedProducts av typen Product[].

    let matchedProducts: Product[] = result.rows;

  5. Iterera över frågeresultaten genom att foreach anropa metoden i matrisen med produkter.

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

Kör koden

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

node index.js

npx tsx index.ts

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

Översikt över Azure Cosmos DB för Apache Cassandra