Panduan Memulai Cepat: Pustaka klien Azure Cosmos DB for Apache Cassandra untuk Node.js

Berlaku untuk: ✅ Apache Cassanda

Mulai menggunakan pustaka klien Azure Cosmos DB for Apache Cassandra agar Node.js menyimpan, mengelola, dan mengkueri data yang tidak terstruktur. Ikuti langkah-langkah dalam panduan ini untuk membuat akun baru, menginstal pustaka klien Node.js, menyambungkan ke akun, melakukan operasi umum, dan mengkueri data sampel akhir Anda.

Dokumentasi referensi API | Kode sumber pustaka | Paket (npm)

Prasyarat

Langganan Azure
- Jika Anda tidak memiliki langganan Azure, buatlah akun gratis sebelum Anda memulai.

Versi terbaru Azure CLI di Azure Cloud Shell.
- Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, masuk ke Azure CLI dengan menggunakan az login perintah .

Node.js 22 atau yang lebih baru

Persiapan

Pertama, siapkan akun dan lingkungan pengembangan untuk panduan ini. Bagian ini memandu Anda melalui proses pembuatan akun, mendapatkan kredensial akun, lalu menyiapkan lingkungan pengembangan Anda.

Buat akun

Mulailah dengan membuat API untuk akun Apache Cassandra. Setelah akun dibuat, buat keyspace dan sumber daya tabel.

Azure CLI
Portal Microsoft Azure

Jika Anda belum memiliki grup sumber daya target, gunakan az group create perintah untuk membuat grup sumber daya baru di langganan Anda.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

az cosmosdb create Gunakan perintah untuk membuat akun Azure Cosmos DB for Apache Cassandra baru dengan pengaturan default.

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

Buat keyspace baru menggunakan az cosmosdb cassandra keyspace create bernama cosmicworks.

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

Buat objek JSON baru untuk mewakili skema Anda menggunakan perintah Bash multibaris. Kemudian, gunakan az cosmosdb cassandra table create perintah untuk membuat tabel baru bernama 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"

Masuk ke portal Azure (https://portal.azure.com).
Masukkan Azure Cosmos DB di bilah pencarian global.
Dalam Layanan, pilih Azure Cosmos DB.
Di panel Azure Cosmos DB , pilih Buat, lalu Azure Cosmos DB untuk Apache Cassandra dalam tab Lainnya .
Pilih tipe akun Akun database unit permintaan (RU).

Dalam panel Dasar , konfigurasikan opsi berikut, lalu pilih Tinjau + buat:

	Nilai
Jenis Beban Kerja	Belajar
Abonemen	Pilih langganan Azure Anda
Grup Sumber Daya	Membuat grup sumber daya baru atau memilih grup sumber daya yang sudah ada
Nama Akun	Berikan nama yang unik secara global
Zona Ketersediaan	Nonaktifkan
Tempat	Pilih wilayah Azure yang didukung untuk langganan Anda

Tip

Anda dapat membiarkan opsi yang tidak ditentukan pada nilai default. Anda juga dapat mengonfigurasi akun untuk membatasi total throughput akun hingga 1.000 unit permintaan per detik (RU/dtk) atau mengaktifkan lapisan gratis untuk meminimalkan biaya Anda.

Pada panel Tinjau + buat , tunggu validasi akun Anda berhasil diselesaikan, lalu pilih Buat.
Portal secara otomatis menavigasi ke panel Penyebaran. Tunggu hingga penerapan selesai.
Setelah penyebaran selesai, pilih Buka sumber daya untuk menavigasi ke API baru untuk akun Apache Cassandra.
Di menu sumber daya, pilih opsi Data Explorer .
Di Data Explorer, pilih + Tabel Baru.

Dalam dialog Tambahkan Tabel , konfigurasikan opsi berikut, lalu pilih OK:

	Nilai
Keyspace	Buat baru
Nama ruang kunci	`cosmicworks`
Nama tabel	`product`
Skema tabel	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Tip

Anda dapat membiarkan opsi yang tidak ditentukan pada nilai default.

Mendapatkan kredensial

Sekarang, dapatkan kata sandi untuk pustaka klien yang akan digunakan guna membuat koneksi ke akun yang baru saja dibuat.

Azure CLI
Portal Microsoft Azure

Gunakan az cosmosdb show untuk mendapatkan titik kontak dan nama pengguna untuk akun tersebut.

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

Catat nilai contactPoint dan username properti dari keluaran perintah sebelumnya. Nilai properti ini adalah titik kontak dan nama pengguna yang Anda gunakan nanti dalam panduan ini untuk menyambungkan ke akun dengan pustaka.

Gunakan az cosmosdb keys list untuk mendapatkan kunci untuk akun tersebut.

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

Catat nilai primaryMasterKey properti dari output perintah sebelumnya. Nilai properti ini adalah kata sandi yang Anda gunakan nanti dalam panduan ini untuk menyambungkan ke akun dengan pustaka.

Menyiapkan lingkungan pengembangan

Kemudian, konfigurasikan lingkungan pengembangan Anda dengan proyek baru dan pustaka klien. Langkah ini adalah prasyarat terakhir yang diperlukan sebelum beralih ke sisa panduan ini.

Mulai dalam folder kosong.
Menginisialisasi modul baru.
```
npm init es6 --yes
```
cassandra-driver Instal paket dari Node Package Manager (npm).
```
npm install --save cassandra-driver
```
Buat file index.js .

Mulai di direktori kosong.
Menginisialisasi modul baru.
```
npm init es6 --yes
```
typescript Instal paket dari Node Package Manager (npm).
```
npm install --save-dev typescript
```
tsx Instal paket dari npm.
```
npm install --save-dev tsx
```
cassandra-driver Instal paket dari npm.
```
npm install --save cassandra-driver
```

Inisialisasi proyek TypeScript menggunakan pengkompilasi (tsc).

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

Buat file index.ts .

Model objek

	Deskripsi
`Client`	Mewakili koneksi tertentu ke kluster
`Mapper`	Klien Cassandra Query Language (CQL) yang digunakan untuk menjalankan kueri

Mengautentikasi klien

Mulailah dengan mengautentikasi klien menggunakan kredensial yang dikumpulkan sebelumnya dalam panduan ini.

Buka file index.js di lingkungan pengembangan terintegrasi (IDE) Anda.

Impor jenis berikut dari cassandra-driver modul:

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;

Buat variabel konstanta string untuk kredensial yang dikumpulkan sebelumnya dalam panduan ini. Beri nama variabel username, , passworddan contactPoint.
```
const username = '<username>';
const password = '<password>';
const contactPoint = '<contact-point>';
```
Buat variabel string lain untuk wilayah tempat Anda membuat akun Azure Cosmos DB for Apache Cassandra. Beri nama variabel regionini .
```
const region = '<azure-region>';
```
Buat objek baru PlainTextAuthProvider dengan kredensial yang ditentukan di langkah sebelumnya.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```

Buat Client objek menggunakan variabel kredensial dan konfigurasi yang dibuat di langkah-langkah sebelumnya.

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

Secara asinkron terhubung ke kluster.
```
await client.connect();
```

Buat pemetaan baru yang menargetkan keyspace cosmicworks dan tabel product. Beri nama pemeta Product.

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

Buat instans pemeta menggunakan forModel fungsi dan Product nama pemeta.
```
const productMapper = mapper.forModel('Product');
```

Buka file index.ts di lingkungan pengembangan terintegrasi (IDE) Anda.
Impor jenis berikut dari cassandra-driver modul:
- 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;
```
Buat variabel konstanta string untuk kredensial yang dikumpulkan sebelumnya dalam panduan ini. Beri nama variabel username, , passworddan contactPoint.
```
const username: string = '<username>';
const password: string = '<password>';
const contactPoint: string = '<contact-point>';
```
Buat variabel string lain untuk wilayah tempat Anda membuat akun Azure Cosmos DB for Apache Cassandra. Beri nama variabel regionini .
```
const region: string = '<azure-region>';
```
Buat objek baru PlainTextAuthProvider dengan kredensial yang ditentukan di langkah sebelumnya.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```
Buat objek anonim dengan opsi yang memastikan bahwa Anda menggunakan protokol keamanan lapisan transportasi (TLS) 1.2.
```
let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};
```

Buat ClientOptions objek menggunakan variabel kredensial dan konfigurasi yang dibuat di langkah-langkah sebelumnya.

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

Buat Client objek menggunakan clientOptions variabel di konstruktor.
```
let client = new Client(clientOptions);
```
Secara asinkron terhubung ke kluster.
```
await client.connect();
```

Buat pemetaan baru yang menargetkan keyspace cosmicworks dan tabel product. Beri nama pemeta Product.

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

Buat instans pemeta menggunakan forModel fungsi dan Product nama pemeta.
```
const productMapper = mapper.forModel('Product');
```

Peringatan

Validasi keamanan lapisan transportasi (TLS) lengkap dinonaktifkan dalam panduan ini untuk menyederhanakan autentikasi. Untuk penyebaran produksi, aktifkan validasi sepenuhnya.

Memasukkan atau memperbarui data

Selanjutnya, upsert data baru ke dalam tabel. Upserting memastikan bahwa data dibuat atau diganti dengan tepat tergantung pada apakah data yang sama sudah ada dalam tabel.

Buat objek baru dalam variabel bernama product.

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

Memanggil fungsi insert secara asinkron dengan memasukkan variabel product yang dibuat pada langkah sebelumnya.
```
await productMapper.insert(product);
```

Tentukan antarmuka baru bernama Product dengan bidang yang sesuai dengan tabel yang dibuat sebelumnya dalam panduan ini.

Tipe

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

Di Node.js, Anda dapat membuat jenis ini di file lain atau membuatnya di akhir file yang ada.

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

Buat objek baru berjenis Product. Simpan objek dalam variabel bernama product.

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

Memanggil fungsi insert secara asinkron dengan memasukkan variabel product yang dibuat pada langkah sebelumnya.
```
await productMapper.insert(product);
```

Baca data

Kemudian, baca data yang sebelumnya diupsert ke dalam tabel.

Buat objek anonim bernama filter. Dalam objek ini, sertakan properti bernama id dengan nilai yang sama dengan produk yang dibuat sebelumnya dalam panduan ini.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
Panggil fungsi pemeta get menggunakan variabel filter. Simpan hasilnya di variabel bernama matchedProduct.
```
let matchedProduct = await productMapper.get(filter);
```

Buat objek anonim bernama filter. Dalam objek ini, sertakan properti bernama id dengan nilai yang sama dengan produk yang dibuat sebelumnya dalam panduan ini.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
Panggil fungsi pemeta get menggunakan variabel filter. Simpan hasil dalam variabel bernama matchedProduct jenis Product.
```
let matchedProduct: Product = await productMapper.get(filter);
```

Mencari data

Terakhir, gunakan kueri untuk menemukan semua data yang cocok dengan filter tertentu dalam tabel.

Buat variabel string baru bernama query dengan kueri CQL yang cocok dengan item dengan bidang yang sama category .
```
const query = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
Buat objek anonim bernama params. Dalam objek ini, sertakan properti bernama category dengan nilai yang sama dengan produk yang dibuat sebelumnya dalam panduan ini.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Memanggil fungsi execute secara asinkron dengan meneruskan variabel query dan params sebagai argumen. Simpan properti hasil rows sebagai variabel bernama matchedProducts.
```
let { rows: matchedProducts } = await client.execute(query, params);
```

Melakukan iterasi hasil kueri dengan menggunakan metode foreach pada array produk.

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

Buat variabel string baru bernama query dengan kueri CQL yang cocok dengan item dengan bidang yang sama category .

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

Buat objek anonim bernama params. Dalam objek ini, sertakan properti bernama category dengan nilai yang sama dengan produk yang dibuat sebelumnya dalam panduan ini.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Memanggil fungsi execute secara asinkron dengan meneruskan variabel query dan params sebagai argumen. Simpan hasil dalam variabel bernama result jenis types.ResultSet.
```
let result: types.ResultSet = await client.execute(query, params);
```
Simpan properti hasil rows sebagai variabel bernama matchedProducts dari jenis Product[].
```
let matchedProducts: Product[] = result.rows;
```

Melakukan iterasi hasil kueri dengan menggunakan metode foreach pada array produk.

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

Menjalankan kode

Jalankan aplikasi yang baru dibuat menggunakan terminal di direktori aplikasi Anda.

node index.js

npx tsx index.ts

Membersihkan sumber daya

Saat Anda tidak lagi memerlukan akun, hapus akun dari langganan Azure Anda dengan menghapus sumber daya.

Azure CLI
Portal Microsoft Azure

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

Langkah selanjutnya

Ringkasan Azure Cosmos DB untuk Apache Cassandra

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-07-21