Udostępnij za pomocą

Szybki start: biblioteka klienta usługi Azure Cosmos DB dla systemu Apache Cassandra dla Node.js

  • Dotyczy: ✅ Apache Cassanda

Rozpocznij pracę z biblioteką klienta usługi Azure Cosmos DB for Apache Cassandra, aby Node.js przechowywać dane bez struktury i zarządzać nimi. Wykonaj kroki opisane w tym przewodniku, aby utworzyć nowe konto, zainstalować bibliotekę klienta Node.js, nawiązać połączenie z kontem, wykonać typowe operacje i wykonać zapytanie o ostateczne przykładowe dane.

Dokumentacja interfejsu API — pakiet | kodu | źródłowego biblioteki (npm)

Wymagania wstępne

  • Subskrypcja platformy Azure

    • Jeśli nie masz subskrypcji Azure, przed rozpoczęciem utwórz darmowe konto.
  • Node.js 22 lub nowsze

Konfigurowanie

Najpierw skonfiguruj konto i środowisko programistyczne dla tego przewodnika. W tej sekcji przedstawiono proces tworzenia konta, uzyskiwania poświadczeń, a następnie przygotowywania środowiska deweloperskiego.

Tworzenie konta

Zacznij od utworzenia interfejsu API dla konta apache Cassandra. Po utworzeniu konta utwórz przestrzeń kluczy i zasoby tabeli.

  1. Jeśli nie masz jeszcze docelowej grupy zasobów, użyj az group create polecenia , aby utworzyć nową grupę zasobów w ramach subskrypcji.

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

  2. Użyj polecenia , az cosmosdb create aby utworzyć nowe konto usługi Azure Cosmos DB dla bazy danych Apache Cassandra z ustawieniami domyślnymi.

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

  3. Utwórz nową przestrzeń kluczy za pomocą az cosmosdb cassandra keyspace create o nazwie cosmicworks.

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

  4. Utwórz nowy obiekt JSON reprezentujący schemat przy użyciu wielolinijkowego polecenia Bash. Następnie użyj az cosmosdb cassandra table create polecenia , aby utworzyć nową tabelę o nazwie 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"

Pobieranie poświadczeń

Teraz pobierz hasło biblioteki klienta do utworzenia połączenia z niedawno utworzonym kontem.

  1. Użyj az cosmosdb show polecenia , aby uzyskać punkt kontaktu i nazwę użytkownika dla konta.

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

  2. Zapisz wartości właściwości contactPoint i username z danych wyjściowych poprzednich poleceń. Wartości tych właściwości to punkt kontaktowy i nazwa użytkownika używana w dalszej części tego przewodnika w celu nawiązania połączenia z kontem z biblioteką.

  3. Użyj az cosmosdb keys list polecenia, aby pobrać klucze dla konta.

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

  4. Zanotuj wartość właściwości primaryMasterKey z danych wyjściowych wcześniejszych poleceń. Wartość tej właściwości to hasło , którego użyjesz w dalszej części tego przewodnika, aby nawiązać połączenie z kontem z biblioteką.

Przygotowywanie środowiska projektowego

Następnie skonfiguruj środowisko deweloperskie przy użyciu nowego projektu i biblioteki klienta. Ten krok jest ostatnim wymaganiem wstępnym przed przejściem do pozostałej części tego przewodnika.

  1. Rozpocznij w pustym folderze.

  2. Zainicjuj nowy moduł.

    npm init es6 --yes

  3. cassandra-driver Zainstaluj pakiet z poziomu menedżera pakietów node (npm).

    npm install --save cassandra-driver

  4. Utwórz plik index.js .

  1. Rozpocznij w pustym katalogu.

  2. Zainicjuj nowy moduł.

    npm init es6 --yes

  3. typescript Zainstaluj pakiet z poziomu menedżera pakietów node (npm).

    npm install --save-dev typescript

  4. Zainstaluj pakiet tsx z npm.

    npm install --save-dev tsx

  5. Zainstaluj pakiet cassandra-driver z npm.

    npm install --save cassandra-driver

  6. Zainicjuj projekt TypeScript przy użyciu kompilatora (tsc).

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

  7. Utwórz plik index.ts .

Model obiektów

Opis
Client Reprezentuje określone połączenie z klastrem
Mapper Klient języka zapytań Cassandra (CQL) używany do uruchamiania zapytań

Przykłady kodu

Uwierzytelnianie klienta

Zacznij od uwierzytelnienia klienta przy użyciu poświadczeń zebranych wcześniej w tym przewodniku.

  1. Otwórz plik index.js w zintegrowanym środowisku projektowym (IDE).

  2. Zaimportuj następujące typy z modułu 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. Utwórz zmienne stałe ciągu dla poświadczeń zebranych wcześniej w tym przewodniku. Nazwij zmienne username, passwordi contactPoint.

    const username = '<username>';
const password = '<password>';
const contactPoint = '<contact-point>';

  4. Utwórz kolejną zmienną ciągu dla regionu, w którym utworzono usługę Azure Cosmos DB dla konta apache Cassandra. Nadaj tej zmiennej regionnazwę .

    const region = '<azure-region>';

  5. Utwórz nowy PlainTextAuthProvider obiekt z poświadczeniami określonymi w poprzednich krokach.

    let authProvider = new PlainTextAuthProvider(
    username,
    password
);

  6. Client Utwórz obiekt przy użyciu zmiennych poświadczeń i konfiguracji utworzonych w poprzednich krokach.

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

  7. Nawiąż asynchroniczne połączenie z klastrem.

    await client.connect();

  8. Utwórz nowy mapper przeznaczony dla przestrzeni kluczy cosmicworks i tabeli product. Nadaj maperowi Productnazwę .

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

  9. Wygeneruj wystąpienie mapowania przy użyciu forModel funkcji i Product nazwy mapowania.

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

  1. Otwórz plik index.ts w zintegrowanym środowisku projektowym (IDE).

  2. Zaimportuj następujące typy z modułu 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. Utwórz zmienne stałe ciągu dla poświadczeń zebranych wcześniej w tym przewodniku. Nazwij zmienne username, passwordi contactPoint.

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

  4. Utwórz kolejną zmienną ciągu dla regionu, w którym utworzono usługę Azure Cosmos DB dla konta apache Cassandra. Nadaj tej zmiennej regionnazwę .

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

  5. Utwórz nowy PlainTextAuthProvider obiekt z poświadczeniami określonymi w poprzednich krokach.

    let authProvider = new PlainTextAuthProvider(
    username,
    password
);

  6. Utwórz obiekt anonimowy z opcjami, które zapewniają, że używasz protokołu TLS (Transport Layer Security) 1.2.

    let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};

  7. ClientOptions Utwórz obiekt przy użyciu zmiennych poświadczeń i konfiguracji utworzonych w poprzednich krokach.

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

  8. Client Utwórz obiekt przy użyciu zmiennej clientOptions w konstruktorze.

    let client = new Client(clientOptions);

  9. Nawiąż asynchroniczne połączenie z klastrem.

    await client.connect();

  10. Utwórz nowy mapper przeznaczony dla przestrzeni kluczy cosmicworks i tabeli product. Nadaj maperowi Productnazwę .

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

  11. Wygeneruj wystąpienie mapowania przy użyciu forModel funkcji i Product nazwy mapowania.

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

Ostrzeżenie

Pełna weryfikacja zabezpieczeń warstwy transportu (TLS) jest wyłączona w tym przewodniku, aby uprościć uwierzytelnianie. W przypadku wdrożeń produkcyjnych w pełni włącz walidację.

Aktualizuj lub dodaj dane

Następnie dodaj nowe dane do tabeli. Upserting gwarantuje, że dane są tworzone lub zastępowane odpowiednio w zależności od tego, czy te same dane już istnieją w tabeli.

  1. Utwórz nowy obiekt w zmiennej o nazwie product.

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

  2. Asynchronicznie wywołaj funkcję insert, przekazując zmienną product utworzoną w poprzednim kroku.

    await productMapper.insert(product);

  1. Zdefiniuj nowy interfejs o nazwie Product z polami odpowiadającymi tabeli utworzonej wcześniej w tym przewodniku.

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

    Wskazówka

    W Node.jsmożna utworzyć ten typ w innym pliku lub utworzyć go na końcu istniejącego pliku.

  2. Utwórz nowy obiekt typu Product. Zapisz obiekt w zmiennej o nazwie 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. Asynchronicznie wywołaj funkcję insert, przekazując zmienną product utworzoną w poprzednim kroku.

    await productMapper.insert(product);

Odczyt danych

Następnie odczytaj dane, które zostały wcześniej dodane lub zmodyfikowane w tabeli.

  1. Utwórz obiekt anonimowy o nazwie filter. W tym obiekcie dołącz właściwość o nazwie id o tej samej wartości co produkt utworzony wcześniej w tym przewodniku.

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

  2. Wywołaj get funkcję mappera, przekazując zmienną filter. Zapisz wynik w zmiennej o nazwie matchedProduct.

    let matchedProduct = await productMapper.get(filter);

  1. Utwórz obiekt anonimowy o nazwie filter. W tym obiekcie dołącz właściwość o nazwie id o tej samej wartości co produkt utworzony wcześniej w tym przewodniku.

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

  2. Wywołaj get funkcję mappera, przekazując zmienną filter. Zapisz wynik w zmiennej o nazwie matchedProduct typu Product.

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

Wykonywanie zapytań o dane

Na koniec użyj zapytania, aby znaleźć wszystkie dane zgodne z określonym filtrem w tabeli.

  1. Utwórz nową zmienną ciągu o nazwie query z zapytaniem CQL, które pasuje do elementów z tym samym category polem.

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

  2. Utwórz obiekt anonimowy o nazwie params. W tym obiekcie dołącz właściwość o nazwie category o tej samej wartości co produkt utworzony wcześniej w tym przewodniku.

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

  3. Wywołaj asynchronicznie funkcję execute, przekazując zarówno zmienne query i params jako argumenty. Zapisz właściwość wyniku rows jako zmienną o nazwie matchedProducts.

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

  4. Iteruj przez wyniki zapytania, wywołując metodę foreach na tablicy produktów.

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

  1. Utwórz nową zmienną ciągu o nazwie query z zapytaniem CQL, które pasuje do elementów z tym samym category polem.

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

  2. Utwórz obiekt anonimowy o nazwie params. W tym obiekcie dołącz właściwość o nazwie category o tej samej wartości co produkt utworzony wcześniej w tym przewodniku.

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

  3. Wywołaj asynchronicznie funkcję execute, przekazując zarówno zmienne query i params jako argumenty. Zapisz wynik w zmiennej o nazwie result typu types.ResultSet.

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

  4. Zapisz właściwość wyniku rows jako zmienną o nazwie matchedProducts typu Product[].

    let matchedProducts: Product[] = result.rows;

  5. Iteruj przez wyniki zapytania, wywołując metodę foreach na tablicy produktów.

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

Uruchamianie kodu

Uruchom nowo utworzoną aplikację przy użyciu terminalu w katalogu aplikacji.

node index.js

npx tsx index.ts

Uprzątnij zasoby

Jeśli konto nie jest już potrzebne, usuń konto z subskrypcji platformy Azure, usuwając zasób.

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

Następny krok

Omówienie usługi Azure Cosmos DB dla bazy danych Apache Cassandra

  • Last updated on