Panduan Singkat: Perpustakaan Klien Azure Cosmos DB untuk Apache Cassandra di Go

Berlaku untuk: ✅ Apache Cassanda

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

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

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 .

Go 1.24 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 modul Go baru.
```
go mod init quickstart
```
github.com/apache/cassandra-gocql-driver/v2 Impor paket dari Go.
```
go get github.com/apache/cassandra-gocql-driver/v2
```
Buat file main.go .
Tambahkan boilerplate aplikasi Go.
```
package main

func main() {    
}
```
Penting

Langkah-langkah yang tersisa dalam panduan ini mengasumsikan bahwa Anda menambahkan kode Anda dalam main fungsi .

Model objek

	Deskripsi
`Cluster`	Mewakili koneksi tertentu ke kluster
`Session`	Entitas yang menyimpan koneksi tertentu ke kluster

Mengautentikasi klien

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

Buka file main.go di lingkungan pengembangan terintegrasi (IDE) Anda.
Dalam fungsi main, impor paket berikut bersama dengan paket github.com/apache/cassandra-gocql-driver/v2:
- context
- crypto/tls
```
import (
    "context"
    "crypto/tls"
    "github.com/apache/cassandra-gocql-driver/v2"
)
```
Buat variabel string untuk kredensial yang dikumpulkan sebelumnya dalam panduan ini. Beri nama variabel username, , passworddan contactPoint.
```
username := "<username>"
password := "<password>"
contactPoint := "<contact-point>"
```
Konfigurasikan instans jenis PasswordAuthenticator dengan kredensial yang ditentukan dalam langkah-langkah sebelumnya. Simpan hasilnya di variabel bernama authentication.
```
authentication := gocql.PasswordAuthenticator{
    Username: username,
    Password: password,
}
```
Konfigurasikan instans SslOptions dengan versi minimum Keamanan Lapisan Transportasi (TLS) 1.2 dan contactPoint variabel sebagai nama server target. Simpan hasilnya di variabel bernama sslOptions.
```
sslOptions := &gocql.SslOptions{
    Config: &tls.Config{
        MinVersion: tls.VersionTLS12,
        ServerName: contactPoint,
    },
}
```
Buat spesifikasi kluster baru menggunakan NewCluster dan contactPoint variabel .
```
cluster := gocql.NewCluster(contactPoint)
```
Konfigurasikan objek spesifikasi kluster dengan menggunakan variabel kredensial dan konfigurasi yang dibuat di langkah-langkah sebelumnya.
```
cluster.SslOpts = sslOptions
cluster.Authenticator = authentication
```

Konfigurasikan sisa objek spesifikasi kluster dengan nilai statis ini.

cluster.Keyspace = "cosmicworks"
cluster.Port = 10350
cluster.ProtoVersion = 4

Buat sesi baru yang tersambung ke kluster menggunakan CreateSession.
```
session, _ := cluster.CreateSession()
```
Konfigurasikan sesi untuk memanggil fungsi Close setelah fungsi main dikembalikan.
```
defer session.Close()
```
Buat objek konteks baru Background dan simpan dalam ctx variabel .
```
ctx := context.Background()
```

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 jenis baru bernama Product dengan bidang yang sesuai dengan tabel yang dibuat sebelumnya dalam panduan ini.
```
type Product struct {
    id        string
    name      string
    category  string
    quantity  int
    clearance bool
}
```
Tip

Di Go, 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 {
    id:        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    name:      "Yamba Surfboard",
    category:  "gear-surf-surfboards",
    quantity:  12,
    clearance: false,
}

Buat variabel string baru bernama insertQuery dengan kueri Cassandra Query Language (CQL) untuk menyisipkan baris baru.

insertQuery := `
    INSERT INTO
        product (id, name, category, quantity, clearance)
    VALUES
        (?, ?, ?, ?, ?)
`

Gunakan fungsi Query dan ExecContext untuk menjalankan kueri. Masukkan berbagai atribut variabel product sebagai parameter kueri.

_ = session.Query(
    insertQuery,
    product.id, 
    product.name, 
    product.category, 
    product.quantity, 
    product.clearance,
).ExecContext(ctx)

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 .

readQuery := `
    SELECT
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE id = ?
    LIMIT 1
`

Buat variabel string bernama id dengan nilai yang sama dengan produk yang dibuat sebelumnya dalam panduan ini.
```
id := "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" 
```
Buat variabel lain bernama matchedProduct untuk menyimpan hasil operasi ini.
```
var matchedProduct Product
```

Gunakan fungsi Query, Consistency, IterContext, dan Scan secara bersamaan untuk menemukan item tunggal yang cocok dengan kueri dan menetapkan propertinya ke variabel matchedProduct.

session.Query(
    readQuery,
    &id,
).Consistency(gocql.One).IterContext(ctx).Scan(
    &matchedProduct.id,
    &matchedProduct.name,
    &matchedProduct.category,
    &matchedProduct.quantity,
    &matchedProduct.clearance,
)

Mencari data

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

Buat variabel string bernama findQuery dan category dengan kueri CQL dan parameter yang diperlukan.

findQuery := `
    SELECT
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE
        category = ?
    ALLOW FILTERING
`

category := "gear-surf-surfboards"

Gunakan fungsi Query, Consistency, IterContext, dan Scanner bersama-sama untuk membuat pemindai yang dapat melakukan iterasi pada beberapa item yang sesuai dengan kueri.
```
queriedProducts := session.Query(
    findQuery, 
    &category,
).Consistency(gocql.All).IterContext(ctx).Scanner()
```

Next Gunakan fungsi dan Scan untuk melakukan iterasi atas hasil kueri dan tetapkan properti dari setiap hasil ke variabel dalamqueriedProduct.

for queriedProducts.Next() {
    var queriedProduct Product
    queriedProducts.Scan(
        &queriedProduct.id,
        &queriedProduct.name,
        &queriedProduct.category,
        &queriedProduct.quantity,
        &queriedProduct.clearance,
    )
    // Do something here with each result
}

Menjalankan kode

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

go run .

Membersihkan sumber daya