Mulai cepat: Pustaka klien Azure Cosmos DB for Apache Cassandra untuk Java

Berlaku untuk: ✅ Apache Cassanda

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

Dokumentasi referensi API | Kode sumber perpustakaan | Paket (Maven)

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 .

Java 21 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 di direktori kosong.

Buat proyek konsol Java baru menggunakan Maven.

mvn archetype:generate -DgroupId=quickstart -DartifactId=console -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Mengimpor paket java-driver-core dari Maven. Tambahkan bagian ini ke file pom.xml Anda.

<dependency>
  <groupId>org.apache.cassandra</groupId>
  <artifactId>java-driver-core</artifactId>
  <version>[4.,)</version>
</dependency>

Buka file /console/src/main/java/quickstart/App.java .

Amati boilerplate aplikasi Java yang ada.

package quickstart;

/**
 * Hello world!
 *
 */
public class App 
{
    public static void main( String[] args )
    {
        System.out.println( "Hello World!" );
    }
}

Hapus komentar dan keluaran konsol dari kode dasar. Blok kode ini adalah titik awal untuk sisa panduan ini.
```
package quickstart;

public class App 
{
    public static void main(String[] args)
    {
    }
}
```
Impor namespace java.security.NoSuchAlgorithmException.
```
import java.security.NoSuchAlgorithmException;
```
Perbarui signature metode main untuk menunjukkan bahwa itu dapat menghasilkan pengecualian NoSuchAlgorithmException.
```
public static void main(String[] args) throws NoSuchAlgorithmException
{    
}
```
Penting

Langkah-langkah yang tersisa dalam panduan ini mengasumsikan bahwa Anda menambahkan kode Anda dalam metode main.
Bangun proyek.
```
mvn compile
```

Model objek

	Deskripsi
`CqlSession`	Mewakili koneksi tertentu ke kluster
`PreparedStatement`	Mewakili pernyataan CQL yang telah dikommpilasikan sebelumnya yang dapat dijalankan beberapa kali secara efisien
`BoundStatement`	Mewakili pernyataan yang disiapkan dengan parameter terikat
`Row`	Mewakili satu baris hasil kueri

Mengautentikasi klien

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

Buka file /console/src/main/java/quickstart/App.java di lingkungan pengembangan terintegrasi (IDE) Anda.

Impor jenis berikut:

java.net.InetSocketAddress
javax.net.ssl.SSLContext
com.datastax.oss.driver.api.core.CqlIdentifier
com.datastax.oss.driver.api.core.CqlSession
com.datastax.oss.driver.api.core.cql.BoundStatement
com.datastax.oss.driver.api.core.cql.PreparedStatement
com.datastax.oss.driver.api.core.cql.ResultSet
com.datastax.oss.driver.api.core.cql.Row

import java.net.InetSocketAddress;    

import javax.net.ssl.SSLContext;

import com.datastax.oss.driver.api.core.CqlIdentifier;
import com.datastax.oss.driver.api.core.CqlSession;
import com.datastax.oss.driver.api.core.cql.BoundStatement;
import com.datastax.oss.driver.api.core.cql.PreparedStatement;
import com.datastax.oss.driver.api.core.cql.ResultSet;
import com.datastax.oss.driver.api.core.cql.Row;

Buat variabel string untuk kredensial yang dikumpulkan sebelumnya dalam panduan ini. Beri nama variabel username, , passworddan contactPoint. Buat juga variabel string bernama region untuk pusat data lokal.
```
String username = "<username>";
String password = "<password>";
String contactPoint = "<contact-point>";
```
Buat variabel string lain untuk wilayah tempat Anda membuat akun Azure Cosmos DB for Apache Cassandra. Beri nama variabel regionini .
```
String region = "<region>";
```
Buat SSLContext objek untuk memastikan bahwa Anda menggunakan protokol keamanan lapisan transportasi (TLS).
```
SSLContext sslContext = SSLContext.getDefault();
```

Buat objek baru CqlSession menggunakan variabel kredensial dan konfigurasi yang dibuat di langkah-langkah sebelumnya. Atur titik kontak, pusat data lokal, kredensial autentikasi, keyspace, dan konteks Keamanan Lapisan Transportasi (TLS).

CqlSession session = CqlSession.builder()
    .addContactPoint(new InetSocketAddress(contactPoint, 10350))
    .withLocalDatacenter(region)
    .withAuthCredentials(username, password)
    .withKeyspace(CqlIdentifier.fromCql("cosmicworks"))
    .withSslContext(sslContext)
    .build();

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.

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

class Product {
    public String id;
    public String name;
    public String category;
    public int quantity;
    public boolean clearance;

    public Product(String id, String name, String category, int quantity, boolean clearance) {
        this.id = id;
        this.name = name;
        this.category = category;
        this.quantity = quantity;
        this.clearance = clearance;
    }

    @Override
    public String toString() {
        return String.format("Product{id='%s', name='%s', category='%s', quantity=%d, clearance=%b}",
                id, name, category, quantity, clearance);
    }
}

Tip

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

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

Product product = new Product(
    "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "Yamba Surfboard",
    "gear-surf-surfboards",
    12,
    false
);

Buat variabel string baru bernama insertQuery dengan kueri Cassandra Query Language (CQL) untuk menyisipkan baris baru.
```
String insertQuery = "INSERT INTO product (id, name, category, quantity, clearance) VALUES (?, ?, ?, ?, ?)";
```

Siapkan pernyataan sisipan dan ikat properti produk sebagai parameter.

PreparedStatement insertStmt = session.prepare(insertQuery);
BoundStatement boundInsert = insertStmt.bind(
    product.id,
    product.name,
    product.category,
    product.quantity,
    product.clearance
);

Lakukan pembaruan atau sisipan produk dengan mengeksekusi pernyataan yang telah diikat.
```
session.execute(boundInsert);
```

Baca data

Kemudian, baca data yang sebelumnya diupsert ke dalam tabel.

Buat variabel string baru bernama readQuery dengan kueri CQL yang cocok dengan item dengan bidang yang sama id .
```
String readQuery = "SELECT * FROM product WHERE id = ? LIMIT 1";
```
Buat variabel string bernama id dengan nilai yang sama dengan produk yang dibuat sebelumnya dalam panduan ini.
```
String id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
```

Siapkan pernyataan dan ikat bidang produk id sebagai parameter.

PreparedStatement readStmt = session.prepare(readQuery);
BoundStatement boundRead = readStmt.bind(id);

Jalankan pernyataan terikat dan simpan hasilnya dalam variabel bernama readResult.
```
ResultSet readResult = session.execute(boundRead);
```

Ambil baris pertama dari kumpulan hasil dan petakan ke Product objek jika ditemukan.

Row row = readResult.one();
Product matchedProduct = new Product(
    row.getString("id"),
    row.getString("name"),
    row.getString("category"),
    row.getInt("quantity"),
    row.getBoolean("clearance")
);

Mencari data

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

Buat variabel string baru bernama findQuery dengan kueri CQL yang cocok dengan item dengan bidang yang sama category .
```
String findQuery = "SELECT * FROM product WHERE category = ? ALLOW FILTERING";
```
Buat variabel string bernama id dengan nilai yang sama dengan produk yang dibuat sebelumnya dalam panduan ini.
```
String category = "gear-surf-surfboards";
```

Siapkan pernyataan dan ikat kategori produk sebagai parameter.

PreparedStatement findStmt = session.prepare(findQuery);
BoundStatement boundFind = findStmt.bind(category);

Jalankan pernyataan terikat dan simpan hasilnya dalam variabel bernama findResults.
```
ResultSet results = session.execute(boundFind);
```

Ulangi hasil kueri dan petakan setiap baris ke Product objek.

for (Row result : results) {
    Product queriedProduct = new Product(
        result.getString("id"),
        result.getString("name"),
        result.getString("category"),
        result.getInt("quantity"),
        result.getBoolean("clearance")
    );
    // Do something here with each result
}

Tutup sesi

Di Java, Anda diharuskan menutup sesi setelah selesai dengan kueri dan operasi apa pun.

session.close();

Menjalankan kode

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

mvn compile
mvn exec:java -Dexec.mainClass="quickstart.App"

Tip

Pastikan Anda menjalankan perintah ini dalam jalur /console yang dibuat dalam panduan ini.

Membersihkan sumber daya