Mulai cepat: Membangun aplikasi Go dengan `gocql` klien untuk mengelola data Azure Cosmos DB for Apache Cassandra

Artikel
08/15/2024

BERLAKU UNTUK: Cassandra

Azure Cosmos DB adalah layanan database multi-model yang memungkinkan Anda membuat dan kueri dokumen, tabel, nilai-kunci, dan database grafik dengan kemampuan distribusi global dan skala horizontal dengan cepat. Dalam mulai cepat ini, Anda akan mulai dengan membuat akun Azure Cosmos DB for Apache Cassandra. Anda kemudian akan menjalankan aplikasi Go untuk membuat keyspace Cassandra, tabel, dan menjalankan beberapa operasi. Aplikasi Go ini menggunakan gocql,yang merupakan klien Cassandra untuk bahasa Go.

Prasyarat

Akun Azure dengan langganan aktif. Buat akun gratis. Atau coba Azure Cosmos DB secara gratis tanpa langganan Azure.
Go terinstal di komputer Anda, dan pengetahuan kerja tentang Go.
Git.

Buat akun database

Sebelum Anda dapat membuat database, Anda perlu membuat akun Cassandra dengan Azure Cosmos DB.

Pada menu portal Microsoft Azure atau halaman Beranda, pilih Buat sumber daya.
Pada halaman Baru, cari dan pilih Azure Cosmos DB.
Pada bilah Azure Cosmos DB, pilih Buat.
Pada halaman API , pilih Buat di bawah bagian Cassandra .

API akan menentukan jenis akun yang akan dibuat. Azure Cosmos DB menyediakan lima API: NoSQL untuk database dokumen, Gremlin untuk database grafik, MongoDB untuk database dokumen, Azure Table, dan Cassandra. Anda harus membuat akun terpisah untuk setiap API.

Pilih Cassandra, karena dalam mulai cepat ini Anda membuat tabel yang berfungsi dengan API untuk Cassandra.

Pelajari selengkapnya tentang API untuk Cassandra.

Di halaman Buat Akun Azure Cosmos DB, masukkan pengaturan dasar untuk akun Azure Cosmos DB baru.

Pengaturan	Nilai	Deskripsi
Langganan	Langganan Anda	Pilih langganan Azure yang ingin Anda gunakan untuk akun Azure Cosmos DB ini.
Grup Sumber Daya	Buat baru Lalu masukkan nama yang sama dengan Nama Akun	Pilih Buat baru. Lalu masukkan nama grup sumber daya baru untuk akun Anda. Agar lebih sederhana, gunakan nama yang sama dengan nama akun Azure Cosmos DB Anda.
Nama Akun	Masukkan nama yang unik	Masukkan nama unik untuk mengidentifikasi akun Azure Cosmos DB Anda. URI akun Anda akan cassandra.cosmos.azure.com ke nama akun unik Anda. Nama akun hanya dapat menggunakan huruf kecil, angka, dan tanda hubung (-), dan panjangnya harus antara 3 dan 31 karakter.
Lokasi	Wilayah yang paling dekat dengan pengguna Anda	Pilih lokasi geografis untuk menghosting akun Azure Cosmos DB Anda. Gunakan lokasi yang paling dekat dengan pengguna Anda untuk memberi mereka akses tercepat ke data.
Mode kapasitas	Throughput yang disediakan atau Tanpa server	Pilih Throughput yang Tersedia untuk membuat akun dalam mode throughput yang tersedia. Pilih Tanpa server untuk membuat akun dalam mode tanpa server.
Terapkan diskon tingkat gratis Azure Cosmos DB	Terapkan atau Jangan terapkan	Dengan tingkat gratis Azure Cosmos DB, Anda akan mendapatkan 1000 RU/dtk pertama dan penyimpanan 25 GB secara gratis pada akun. Pelajari lebih lanjut tentang tingkat gratis.
Membatasi throughput akun total	Pilih untuk membatasi throughput akun	Ini berguna jika Anda ingin membatasi total throughput akun ke nilai tertentu.

Catatan

Anda dapat memiliki hingga satu akun Azure Cosmos DB tingkat gratis per langganan Azure dan harus ikut serta saat membuat akun. Jika Anda tidak melihat opsi untuk menerapkan diskon tingkat gratis, ini berarti akun lain dalam langganan telah diaktifkan dengan tingkat gratis.

Halaman akun baru untuk Azure Cosmos DB untuk Apache Cassandra

Pada tab Distribusi Global, konfigurasikan detail berikut. Anda dapat membiarkan nilai default untuk tujuan quickstart ini:

Pengaturan	Nilai	Deskripsi
Redundansi Geografis	Nonaktifkan	Aktifkan atau nonaktifkan distribusi global di akun Anda dengan memasangkan wilayah Anda dengan wilayah pasangan. Anda dapat menambahkan lebih banyak wilayah ke akun Anda nanti.
Tulisan Multiwilayah	Nonaktifkan	Kemampuan tulisan multiwilayah memungkinkan Anda untuk mengambil keuntungan dari throughput terprovisi untuk database dan kontainer Anda di seluruh dunia.
Zona Ketersediaan	Nonaktifkan	Zona Ketersediaan adalah lokasi terisolasi dalam wilayah Azure. Setiap zonanya terdiri dari satu atau beberapa pusat data yang dilengkapi dengan daya, pendinginan, dan jaringan yang independen.

Catatan

Opsi berikut ini tidak tersedia jika Anda memilih Tanpa Server sebagai mode Kapasitas:

Terapkan Diskon Tingkat Gratis
Redundansi geografis
Tulisan Multiwilayah

Secara opsional, Anda dapat mengonfigurasi detail tambahan di tab berikut:
- Jaringan - Konfigurasikan akses dari jaringan virtual.
- Kebijakan Pencadangan - Konfigurasikan kebijakan pencadangan berkala atau berkelanjutan.
- Enkripsi - Gunakan kunci yang dikelola layanan atau kunci yang dikelola pelanggan.
- Tag - Tag adalah pasangan nama/nilai yang memungkinkan Anda mengategorikan sumber daya dan melihat tagihan gabungan dengan menerapkan tag yang sama ke beberapa sumber daya dan grup sumber daya.
Pilih Tinjau + buat.
Ulas pengaturan akun, lalu pilih Buat. Dibutuhkan beberapa menit untuk membuat akun. Tunggu halaman portal untuk menampilkan Penyebaran Anda selesai.
Pilih Buka sumber daya untuk masuk ke halaman akun Azure Cosmos DB.

Buat klon sampel aplikasi

Mulailah dengan mengkloning aplikasi dari GitHub.

Buka prompt perintah dan buat folder bernama git-samples.
```
md "C:\git-samples"
```
Buka jendela terminal git, seperti git bash. Gunakan cdperintah untuk mengubah ke folder baru dan memasang aplikasi sampel.
```
cd "C:\git-samples"
```
Jalankan perintah berikut untuk mengkloning repositori sampel. Perintah ini membuat salinan aplikasi sampel di komputer Anda.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git
```

Mengulas kode

Langkah ini bersifat opsional. Jika Anda tertarik untuk mempelajari bagaimana kode membuat sumber daya database, Anda bisa meninjau cuplikan kode berikut. Jika tidak, Anda dapat melewati ke depan untuk Menjalankan aplikasi

Fungsi GetSession (bagian dari utils\utils.go) menampilkan *gocql.Session yang digunakan untuk menjalankan operasi kluster seperti menyisipkan, menemukan, dll.

func GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword string) *gocql.Session {
    clusterConfig := gocql.NewCluster(cosmosCassandraContactPoint)
    port, err := strconv.Atoi(cosmosCassandraPort)
    
    clusterConfig.Authenticator = gocql.PasswordAuthenticator{Username: cosmosCassandraUser, Password: cosmosCassandraPassword}
    clusterConfig.Port = port
    clusterConfig.SslOpts = &gocql.SslOptions{Config: &tls.Config{MinVersion: tls.VersionTLS12}}
    clusterConfig.ProtoVersion = 4
    
    session, err := clusterConfig.CreateSession()
    ...
    return session
}

Host Azure Cosmos DB Cassandra diteruskan ke gocql.NewCluster fungsi untuk mendapatkan *gocql.ClusterConfig struktur yang kemudian dikonfigurasi untuk menggunakan nama pengguna, kata sandi, port, dan versi TLS yang sesuai (persyaratan Keamanan enkripsi HTTPS/SSL/TLS)

GetSession Fungsi ini kemudian dipanggil dari main fungsi (main.go ).

func main() {
    session := utils.GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword)
    defer session.Close()
    ...
}

Informasi konektivitas dan kredensial diterima dalam bentuk variabel lingkungan (diselesaikan dalam init metode)

func init() {
    cosmosCassandraContactPoint = os.Getenv("COSMOSDB_CASSANDRA_CONTACT_POINT")
    cosmosCassandraPort = os.Getenv("COSMOSDB_CASSANDRA_PORT")
    cosmosCassandraUser = os.Getenv("COSMOSDB_CASSANDRA_USER")
    cosmosCassandraPassword = os.Getenv("COSMOSDB_CASSANDRA_PASSWORD")

    if cosmosCassandraContactPoint == "" || cosmosCassandraUser == "" || cosmosCassandraPassword == "" {
        log.Fatal("missing mandatory environment variables")
    }
}

Kemudian digunakan untuk menjalankan berbagai operasi (bagian operations\setup.go dari) pada Azure Cosmos DB dimulai dengan keyspace dan table penciptaan.

Seperti namanya, fungsi DropKeySpaceIfExists menghilangkan keyspace hanya jika ada.

const dropKeyspace = "DROP KEYSPACE IF EXISTS %s"

func DropKeySpaceIfExists(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(dropKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to drop keyspace", err)
    }
    log.Println("Keyspace dropped")
}

CreateKeySpace fungsi digunakan untuk membuat keyspace (user_profile)

const createKeyspace = "CREATE KEYSPACE %s WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }"

func CreateKeySpace(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(createKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to create keyspace", err)
    }
    log.Println("Keyspace created")
}

Ini diikuti dengan pembuatan tabel (user) yang diurus CreateUserTable fungsinya

const createTable = "CREATE TABLE %s.%s (user_id int PRIMARY KEY, user_name text, user_bcity text)"

func CreateUserTable(keyspace, table string, session *gocql.Session) {
    err := session.Query(fmt.Sprintf(createTable, keyspace, table)).Exec()
    if err != nil {
        log.Fatal("failed to create table ", err)
    }
    log.Println("Table created")
}

Setelah ruang kunci dan tabel dibuat, kami memanggil operasi CRUD (bagian dari operations\crud.go).

InsertUser digunakan untuk membuat User. Ini mengatur info pengguna (ID, nama, dan kota) sebagai argumen kueri menggunakan Bind

const createQuery = "INSERT INTO %s.%s (user_id, user_name , user_bcity) VALUES (?,?,?)"

func InsertUser(keyspace, table string, session *gocql.Session, user model.User) {
    err := session.Query(fmt.Sprintf(createQuery, keyspace, table)).Bind(user.ID, user.Name, user.City).Exec()
    if err != nil {
        log.Fatal("Failed to create user", err)
    }
    log.Println("User created")
}

FindUser digunakan untuk mencari pengguna (model\user.go) menggunakan ID pengguna tertentu sedangkan Scan mengikat atribut pengguna (ditampilkan oleh Cassandra) ke variabel individual (userid, name, city) -itu hanya salah satu cara yang mana Anda dapat menggunakan hasil yang diperoleh sebagai hasil kueri pencarian

const selectQuery = "SELECT * FROM %s.%s where user_id = ?"

func FindUser(keyspace, table string, id int, session *gocql.Session) model.User {
    var userid int
    var name, city string
    err := session.Query(fmt.Sprintf(selectQuery, keyspace, table)).Bind(id).Scan(&userid, &name, &city)

    if err != nil {
        if err == gocql.ErrNotFound {
            log.Printf("User with id %v does not exist\n", id)
        } else {
            log.Printf("Failed to find user with id %v - %v\n", id, err)
        }
    }
    return model.User{ID: userid, Name: name, City: city}
}

FindAllUsers digunakan untuk mengambil semua pengguna. SliceMap digunakan sebagai singkatan untuk mendapatkan semua info pengguna dalam bentuk sepotong map. Pikirkan masing-masing map sebagai pasangan nilai kunci di mana nama kolom (misalnya, user_id ) adalah kunci bersama dengan nilainya masing-masing.

const findAllUsersQuery = "SELECT * FROM %s.%s"

func FindAllUsers(keyspace, table string, session *gocql.Session) []model.User {
    var users []model.User
    results, _ := session.Query(fmt.Sprintf(findAllUsersQuery, keyspace, table)).Iter().SliceMap()

    for _, u := range results {
        users = append(users, mapToUser(u))
    }
    return users
}

Setiap map info pengguna dikonversi menjadi User menggunakan mapToUser fungsi yang hanya mengekstrak nilai dari kolom masing-masing dan menggunakannya untuk membuat contoh User struct

func mapToUser(m map[string]interface{}) model.User {
    id, _ := m["user_id"].(int)
    name, _ := m["user_name"].(string)
    city, _ := m["user_bcity"].(string)

    return model.User{ID: id, Name: name, City: city}
}

Jalankan aplikasi

Seperti yang disebutkan sebelumnya, aplikasi menerima konektivitas dan kredensial dalam bentuk variabel lingkungan.

Di akun Azure Cosmos DB Anda di portal Microsoft Azure, pilih String Koneksi.

Salin nilai untuk atribut berikut (CONTACT POINT, PORT, USERNAME, dan PRIMARY PASSWORD) dan atur mereka ke variabel lingkungan masing-masing

set COSMOSDB_CASSANDRA_CONTACT_POINT=<value for "CONTACT POINT">
set COSMOSDB_CASSANDRA_PORT=<value for "PORT">
set COSMOSDB_CASSANDRA_USER=<value for "USERNAME">
set COSMOSDB_CASSANDRA_PASSWORD=<value for "PRIMARY PASSWORD">

Di jendela terminal, ubah ke folder yang benar. Contohnya:

cd "C:\git-samples\azure-cosmosdb-cassandra-go-getting-started"

Di terminal, jalankan perintah berikut untuk memulai aplikasi.

go run main.go

Jendela terminal menampilkan pemberitahuan untuk berbagai operasi termasuk ruang kunci dan pengaturan tabel, pembuatan pengguna, dll.
Di portal Microsoft Azure, buka Azure Data Explorer untuk membuat kueri, memodifikasi, dan bekerja dengan data baru ini.

Mengulas SLA di portal Microsoft Azure

portal Azure memantau throughput, penyimpanan, ketersediaan, latensi, dan konsistensi akun Azure Cosmos DB Anda. Bagan untuk metrik yang terkait dengan Service Level Agreement (SLA) Azure Cosmos DB menunjukkan nilai SLA dibandingkan dengan performa aktual. Rangkaian metrik ini membuat pemantauan SLA Anda transparan.

Untuk meninjau metrik dan SLA:

Pilih Metrik di menu navigasi akun Azure Cosmos DB Anda.
Pilih tab seperti Latensi, dan pilih jangka waktu di sebelah kanan. Bandingkan garis Aktual dan SLA pada bagan.
Tinjau metrik pada tab lain.

Membersihkan sumber daya

Setelah selesai dengan aplikasi dan akun Azure Cosmos DB, Anda dapat menghapus sumber daya Azure yang dibuat sehingga tidak dikenakan lebih banyak biaya. Untuk menghapus sumber daya:

Di portal Azure, cari dan pilih Grup sumber daya.
Dari daftar, pilih grup sumber daya yang Anda buat untuk panduan mulai cepat ini.
Di panel Gambaran umum grup sumber daya, pilih Hapus grup sumber daya.
Di jendela berikutnya, masukkan nama grup sumber daya yang akan dihapus, lalu pilih Hapus.

Langkah berikutnya

Dalam mulai cepat ini, Anda mempelajari cara membuat akun Azure Cosmos DB dengan API untuk Cassandra, dan menjalankan aplikasi Go yang membuat database dan kontainer Cassandra. Kini Anda dapat mengimpor data tambahan ke akun Azure Cosmos DB.

Mengimpor data Cassandra ke Azure Cosmos DB

Bagikan melalui

Mulai cepat: Membangun aplikasi Go dengan `gocql` klien untuk mengelola data Azure Cosmos DB for Apache Cassandra

Prasyarat

Buat akun database

Buat klon sampel aplikasi

Mengulas kode

Jalankan aplikasi

Mengulas SLA di portal Microsoft Azure

Membersihkan sumber daya

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Mulai cepat: Membangun aplikasi Go dengan gocql klien untuk mengelola data Azure Cosmos DB for Apache Cassandra

Prasyarat

Buat akun database

Buat klon sampel aplikasi

Mengulas kode

Jalankan aplikasi

Mengulas SLA di portal Microsoft Azure

Membersihkan sumber daya

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan:

Mulai cepat: Membangun aplikasi Go dengan `gocql` klien untuk mengelola data Azure Cosmos DB for Apache Cassandra