Guida introduttiva: Libreria client di Azure Cosmos DB for Apache Cassandra per Node.js

Si applica a: ✅ Apache Cassanda

Inizia a utilizzare la libreria client di Azure Cosmos DB per Apache Cassandra su Node.js per archiviare, gestire ed eseguire query sui dati non strutturati. Seguire la procedura descritta in questa guida per creare un nuovo account, installare una libreria client Node.js, connettersi all'account, eseguire operazioni comuni ed eseguire query sui dati di esempio finali.

Documentazione di riferimento sull'API | Codice sorgente della libreria | Pacchetto (npm)

Prerequisiti

Una sottoscrizione di Azure
- Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Versione più recente dell'interfaccia della riga di comando di Azure in Azure Cloud Shell.
- Se si preferisce eseguire i comandi CLI di riferimento in locale, accedere all'interfaccia della riga di comando di Azure usando il comando az login.

Node.js 22 o versione successiva

Configurazione

Prima di tutto, configurare l'account e l'ambiente di sviluppo per questa guida. Questa sezione illustra il processo di creazione di un account, il recupero delle credenziali e la preparazione dell'ambiente di sviluppo.

Crea un account

Per iniziare, creare un'API per l'account Apache Cassandra. Dopo aver creato l'account, creare il keyspace e le risorse della tabella.

Interfaccia della riga di comando di Azure
Portale di Azure

Se non si ha già un gruppo di risorse di destinazione, usare il az group create comando per creare un nuovo gruppo di risorse nella sottoscrizione.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Usare il az cosmosdb create comando per creare un nuovo account Azure Cosmos DB per Apache Cassandra con le impostazioni predefinite.

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

Creare un nuovo keyspace utilizzando az cosmosdb cassandra keyspace create denominato cosmicworks.

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

Creare un nuovo oggetto JSON per rappresentare lo schema usando un comando Bash a più righe. Usare quindi il az cosmosdb cassandra table create comando per creare una nuova tabella denominata 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"

Accedere al portale di Azure (https://portal.azure.com).
Immettere Azure Cosmos DB nella barra di ricerca globale.
In Servizi selezionare Azure Cosmos DB.
Nel riquadro Azure Cosmos DB selezionare Crea e quindi Azure Cosmos DB per Apache Cassandra nella scheda Altri .
Selezionare Account del database delle unità richieste (UR) per il tipo di account.

Nel riquadro Dati principali configurare le opzioni seguenti, quindi selezionare Rivedi e crea:

	Valore
Tipo di carico di lavoro	Attività di apprendimento
Abbonamento	Selezionare la sottoscrizione di Azure
Gruppo di risorse	Creare un nuovo gruppo di risorse o selezionare un gruppo di risorse esistente
Account Name:	Specificare un nome univoco globale
Zone di disponibilità	Disabilitare
Ubicazione	Selezionare un'area di Azure supportata per la sottoscrizione

Suggerimento

È possibile lasciare qualsiasi opzione non specificata impostata sui valori predefiniti. È anche possibile configurare l'account per limitare la velocità effettiva totale dell'account a 1.000 unità richiesta al secondo (UR/sec) o abilitare il livello gratuito per ridurre al minimo i costi.

Nel riquadro Rivedi e crea attendere il completamento della convalida dell'account e quindi selezionare Crea.
Il portale passa automaticamente al riquadro Distribuzione. Attendere il completamento della distribuzione.
Al termine della distribuzione, selezionare Vai alla risorsa per passare alla nuova API per l'account Apache Cassandra.
Nel menu delle risorse selezionare l'opzione Esplora dati .
In Esplora dati selezionare + Nuova tabella.

Nella finestra di dialogo Aggiungi tabella configurare le opzioni seguenti e quindi selezionare OK:

	Valore
Keyspace	Crea nuovo
Nome dello spazio delle chiavi	`cosmicworks`
Nome della tabella	`product`
Schema della tabella	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Suggerimento

È possibile lasciare qualsiasi opzione non specificata impostata sui valori predefiniti.

Ottenere le credenziali

Ottenere ora la password per la libreria client da usare per creare una connessione all'account creato di recente.

Interfaccia della riga di comando di Azure
Portale di Azure

Usare az cosmosdb show per ottenere il punto di contatto e il nome utente per l'account.

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

Registrare il valore delle proprietà contactPoint e username dall'output dei comandi precedenti. Questi valori delle proprietà sono il punto di contatto e il nome utente usati più avanti in questa guida per connettersi all'account con la libreria.

Usare az cosmosdb keys list per ottenere le chiavi per l'account.

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

Registrare il valore della primaryMasterKey proprietà dall'output dei comandi precedenti. Il valore di questa proprietà è la password usata più avanti in questa guida per connettersi all'account con la libreria.

Preparare l'ambiente di sviluppo

Configurare quindi l'ambiente di sviluppo con un nuovo progetto e la libreria client. Questo passaggio è l'ultimo prerequisito necessario prima di passare al resto di questa guida.

Iniziare in una cartella vuota.
Inizializzare un nuovo modulo.
```
npm init es6 --yes
```
Installare il cassandra-driver pacchetto da Node Package Manager (npm).
```
npm install --save cassandra-driver
```
Creare il file index.js .

Iniziare in una directory vuota.
Inizializzare un nuovo modulo.
```
npm init es6 --yes
```
Installare il typescript pacchetto da Node Package Manager (npm).
```
npm install --save-dev typescript
```
Installare il tsx pacchetto da npm.
```
npm install --save-dev tsx
```
Installare il cassandra-driver pacchetto da npm.
```
npm install --save cassandra-driver
```

Inizializzare il progetto TypeScript usando il compilatore (tsc).

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

Creare il file index.ts .

Modello a oggetti

	Descrizione
`Client`	Rappresenta una connessione specifica a un cluster
`Mapper`	Client Cassandra Query Language (CQL) usato per eseguire query

Autenticare il client

Per iniziare, autenticare il client usando le credenziali raccolte in precedenza in questa guida.

Aprire il file index.js nell'ambiente di sviluppo integrato (IDE).

Importare i tipi seguenti dal cassandra-driver modulo:

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;

Creare variabili costanti di tipo stringa per le credenziali raccolte in precedenza in questa guida. Assegna nomi alle variabili username, password, e contactPoint.
```
const username = '<username>';
const password = '<password>';
const contactPoint = '<contact-point>';
```
Creare un'altra variabile stringa per l'area in cui è stato creato l'account Azure Cosmos DB per Apache Cassandra. Assegnare alla variabile regionil nome .
```
const region = '<azure-region>';
```
Creare un nuovo PlainTextAuthProvider oggetto con le credenziali specificate nei passaggi precedenti.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```

Creare un Client oggetto usando le credenziali e le variabili di configurazione create nei passaggi precedenti.

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

Connettersi in modo asincrono al cluster.
```
await client.connect();
```

Creare un nuovo mapper destinato al cosmicworks keyspace e alla tabella product. Assegnare un nome al mapper Product.

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

Genera un'istanza di mapper utilizzando la funzione forModel e il nome mapper Product.
```
const productMapper = mapper.forModel('Product');
```

Aprire il file index.ts nell'ambiente di sviluppo integrato (IDE).
Importare i tipi seguenti dal cassandra-driver modulo:
- 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;
```
Creare variabili costanti di tipo stringa per le credenziali raccolte in precedenza in questa guida. Assegna nomi alle variabili username, password, e contactPoint.
```
const username: string = '<username>';
const password: string = '<password>';
const contactPoint: string = '<contact-point>';
```
Creare un'altra variabile stringa per l'area in cui è stato creato l'account Azure Cosmos DB per Apache Cassandra. Assegnare alla variabile regionil nome .
```
const region: string = '<azure-region>';
```
Creare un nuovo PlainTextAuthProvider oggetto con le credenziali specificate nei passaggi precedenti.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```
Creare un oggetto anonimo con opzioni che garantiscono l'uso del protocollo TLS (Transport Layer Security) 1.2.
```
let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};
```

Creare un ClientOptions oggetto usando le credenziali e le variabili di configurazione create nei passaggi precedenti.

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

Creare un Client oggetto usando la clientOptions variabile nel costruttore .
```
let client = new Client(clientOptions);
```
Connettersi in modo asincrono al cluster.
```
await client.connect();
```

Creare un nuovo mapper destinato al cosmicworks keyspace e alla tabella product. Assegnare un nome al mapper Product.

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

Genera un'istanza di mapper utilizzando la funzione forModel e il nome mapper Product.
```
const productMapper = mapper.forModel('Product');
```

Avvertimento

La convalida completa di TLS (Transport Layer Security) è disabilitata in questa guida per semplificare l'autenticazione. Nelle distribuzioni di produzione, abilitare completamente la validazione.

Aggiornare o inserire i dati

Eseguire quindi l'inserimento o aggiornamento dei nuovi dati all'interno di una tabella. L'upserting garantisce che i dati vengano creati o sostituiti in modo appropriato a seconda che nella tabella esistano già gli stessi dati.

Creare un nuovo oggetto in una variabile denominata product.

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

Richiamare in modo asincrono la insert funzione passando la product variabile creata nel passaggio precedente.
```
await productMapper.insert(product);
```

Definire una nuova interfaccia denominata Product con i campi corrispondenti alla tabella creata in precedenza in questa guida.

TIPO

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

In Node.jsè possibile creare questo tipo in un altro file o crearlo alla fine del file esistente.

	TIPO
`Id`	`string`
`Name`	`string`
`Category`	`string`
`Quantity`	`int`
`Price`	`decimal`
`Clearance`	`bool`

Creare un nuovo oggetto di tipo Product. Archiviare l'oggetto in una variabile denominata product.

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

Richiamare in modo asincrono la insert funzione passando la product variabile creata nel passaggio precedente.
```
await productMapper.insert(product);
```

Leggere dati

Leggere quindi i dati precedentemente inseriti nella tabella.

Creare un oggetto anonimo denominato filter. In questo oggetto includere una proprietà denominata id con lo stesso valore del prodotto creato in precedenza in questa guida.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
Richiamare la funzione get del mapper passando la variabilefilter. Archiviare il risultato in una variabile denominata matchedProduct.
```
let matchedProduct = await productMapper.get(filter);
```

Creare un oggetto anonimo denominato filter. In questo oggetto includere una proprietà denominata id con lo stesso valore del prodotto creato in precedenza in questa guida.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
Richiamare la funzione get del mapper passando la variabilefilter. Archiviare il risultato in una variabile denominata matchedProduct di tipo Product.
```
let matchedProduct: Product = await productMapper.get(filter);
```

Dati di query

Usare infine una query per trovare tutti i dati corrispondenti a un filtro specifico nella tabella.

Creare una nuova variabile stringa denominata query con una query CQL che corrisponde agli elementi con lo stesso category campo.
```
const query = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
Creare un oggetto anonimo denominato params. In questo oggetto includere una proprietà denominata category con lo stesso valore del prodotto creato in precedenza in questa guida.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Richiamare in modo asincrono la funzione execute passando sia la variabile query che la variabile params come argomenti. Archiviare la proprietà del rows risultato come variabile denominata matchedProducts.
```
let { rows: matchedProducts } = await client.execute(query, params);
```
Iterare sui risultati della query richiamando il metodo foreach sull'array di prodotti.
```
matchedProducts.forEach(product => {
    // Do something here with each result
});
```

Creare una nuova variabile stringa denominata query con una query CQL che corrisponde agli elementi con lo stesso category campo.
```
const query: string = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
Creare un oggetto anonimo denominato params. In questo oggetto includere una proprietà denominata category con lo stesso valore del prodotto creato in precedenza in questa guida.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Richiamare in modo asincrono la funzione execute passando sia la variabile query che la variabile params come argomenti. Archiviare il risultato in una variabile denominata result di tipo types.ResultSet.
```
let result: types.ResultSet = await client.execute(query, params);
```
Archiviare la proprietà del rows risultato come variabile denominata matchedProducts di tipo Product[].
```
let matchedProducts: Product[] = result.rows;
```

Iterare sui risultati della query richiamando il metodo foreach sull'array di prodotti.

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

Eseguire il codice

Eseguire l'applicazione appena creata usando un terminale nella directory dell'applicazione.

node index.js

npx tsx index.ts

Pulire le risorse

Quando l'account non è più necessario, rimuovere l'account dalla sottoscrizione di Azure eliminando la risorsa.

Interfaccia della riga di comando di Azure
Portale di Azure

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

Passo successivo

Panoramica di Azure Cosmos DB per Apache Cassandra

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-07-26