Mulai cepat: Membangun aplikasi Java untuk mengelola data Azure Cosmos DB for Apache Cassandra (Driver v4)

  • Artikel

BERLAKU UNTUK: Cassandra

Dalam mulai cepat ini, Anda membuat akun Azure Cosmos DB for Apache Cassandra, dan menggunakan aplikasi Cassandra Java yang dikloning dari GitHub untuk membuat database dan kontainer Cassandra menggunakan driver v4.x Apache Cassandra untuk Java. 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.

Prasyarat

Catatan

Ini adalah mulai cepat sederhana yang menggunakan versi 4 driver Apache Cassandra sumber terbuka untuk Java. Dalam kebanyakan kasus, Anda harus dapat menghubungkan aplikasi Java dependen Apache Cassandra yang ada ke Azure Cosmos DB untuk Apache Cassandra tanpa perubahan apa pun pada kode yang ada. Namun, sebaiknya tambahkan ekstensi Java kustom kami, yang mencakup kebijakan coba lagi dan penyeimbangan beban kustom, serta pengaturan koneksi yang direkomendasikan, untuk pengalaman keseluruhan yang lebih baik. Hal ini untuk menangani pembatasan laju dan failover tingkat aplikasi di Azure Cosmos DB jika diperlukan. Anda dapat menemukan sampel komprehensif yang mengimplementasikan ekstensi di sini.

Membuat akun database

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

  1. Dari menu portal Microsoft Azure atau Beranda, pilih Buat sumber daya.

  2. Pada halaman Baru, cari dan pilih Azure Cosmos DB.

  3. Pada halaman Azure Cosmos DB, pilih Buat.

  4. 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.

  5. 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 disediakan untuk membuat akun dalam mode throughput yang disediakan. 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

  6. 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 zona 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

  7. 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.

  8. Pilih Tinjau + buat.

  9. Ulas pengaturan akun, lalu pilih Buat. Dibutuhkan beberapa menit untuk membuat akun. Tunggu halaman portal untuk menampilkan Penyebaran Anda selesai.

    Panel Pemberitahuan portal Microsoft Azure

  10. Pilih Buka sumber daya untuk masuk ke halaman akun Azure Cosmos DB.

Buat klon sampel aplikasi

Sekarang mari kita beralih bekerja dengan kode. Mari kita mengkloning aplikasi Cassandra dari GitHub, mengatur string koneksi, dan menjalankannya. Anda akan melihat betapa mudahnya bekerja dengan data secara terprogram.

  1. Buka prompt perintah. Buat folder baru bernama git-samples. Kemudian, tutup prompt perintah.

    md "C:\git-samples"

  2. Buka jendela terminal git, seperti git bash, dan gunakan perintah cd untuk mengubah ke folder baru untuk menginstal aplikasi sampel.

    cd "C:\git-samples"

  3. 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-java-getting-started-v4.git

Mengulas kode

Langkah ini bersifat opsional. Jika Anda tertarik untuk mempelajari bagaimana kode membuat sumber daya database, Anda bisa meninjau cuplikan berikut. Jika tidak, Anda dapat melompatinya untuk Memperbarui string koneksi Anda. Cuplikan ini semuanya diambil dari file src/main/java/com/azure/cosmosdb/cassandra/util/CassandraUtils.java.

  • CqlSession menyambungkan ke Azure Cosmos DB for Apache Cassandra dan mengembalikan sesi untuk diakses (Cluster objek dari driver v3 sekarang sudah usang). Host Cassandra Host, Port, Nama pengguna, dan kata sandi diatur menggunakan halaman string koneksi di portal Microsoft Azure.

        this.session = CqlSession.builder().withSslContext(sc)
            .addContactPoint(new InetSocketAddress(cassandraHost, cassandraPort)).withLocalDatacenter(region)
            .withAuthCredentials(cassandraUsername, cassandraPassword).build();

Cuplikan berikut berasal dari file src/main/java/com/azure/cosmosdb/cassandra/repository/UserRepository.java.

  • Hilangkan ruang kunci jika sudah ada dari run sebelumnya.

    public void dropKeyspace() {
    String query = "DROP KEYSPACE IF EXISTS "+keyspace+"";
    session.execute(query);
    LOGGER.info("dropped keyspace '"+keyspace+"'");
}

  • Ruang kunci baru dibuat.

    public void createKeyspace() {
    String query = "CREATE KEYSPACE "+keyspace+" WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }";
    session.execute(query);
    LOGGER.info("Created keyspace '"+keyspace+"'");
}

  • Tabel baru dibuat.

      public void createTable() {
      String query = "CREATE TABLE "+keyspace+"."+table+" (user_id int PRIMARY KEY, user_name text, user_bcity text)";
      session.execute(query);
      LOGGER.info("Created table '"+table+"'");
  }

  • Entitas pengguna disisipkan menggunakan objek pernyataan yang disiapkan.

    public String prepareInsertStatement() {
    final String insertStatement = "INSERT INTO  "+keyspace+"."+table+" (user_id, user_name , user_bcity) VALUES (?,?,?)";
    return insertStatement;
}

public void insertUser(String preparedStatement, int id, String name, String city) {
    PreparedStatement prepared = session.prepare(preparedStatement);
    BoundStatement bound = prepared.bind(id, city, name).setIdempotent(true);
    session.execute(bound);
}

  • Kueri untuk mendapatkan semua informasi Pengguna.

    public void selectAllUsers() {
    final String query = "SELECT * FROM "+keyspace+"."+table+"";
    List<Row> rows = session.execute(query).all();

    for (Row row : rows) {
        LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
    }
}

  • Kueri untuk mendapatkan informasi Pengguna tunggal.

    public void selectUser(int id) {
    final String query = "SELECT * FROM "+keyspace+"."+table+" where user_id = 3";
    Row row = session.execute(query).one();

    LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
}

Memperbarui string koneksi Anda

Sekarang kembali ke portal Microsoft Azure untuk mendapatkan informasi string koneksi Anda dan menyalinnya ke dalam aplikasi. Detail string koneksi memungkinkan aplikasi Anda berkomunikasi dengan database yang dihosting.

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

    Tampilkan dan salin nama pengguna dari portal Microsoft Azure, halaman String Koneksi

  2. Gunakan tombol di sisi kanan layar untuk menyalin nilai CONTACT POINT.

  3. Buka file config.properties dari folder C:\git-samples\azure-cosmosdb-cassandra-java-getting-started\java-examples\src\main\resources.

  4. Tempelkan nilai CONTACT POINT dari portal di atas <Cassandra endpoint host> pada baris 2.

    Baris 2 dari config.properties sekarang harus terlihat mirip dengan

    cassandra_host=cosmos-db-quickstart.cassandra.cosmosdb.azure.com

  5. Kembali ke portal dan salin nilai USERNAME. Tempelkan nilai CONTACT POINT dari portal di atas <cassandra endpoint username> pada baris 4.

    Baris 4 dari config.properties sekarang harus terlihat mirip dengan

    cassandra_username=cosmos-db-quickstart

  6. Kembali ke portal dan salin nilai PASSWORD. Tempelkan nilai PASSWORD dari portal di atas <cassandra endpoint password> pada baris 5.

    Baris 5 dari config.properties sekarang harus terlihat mirip dengan

    cassandra_password=2Ggkr662ifxz2Mg...==

  7. Pada baris 6, jika Anda ingin menggunakan sertifikat TLS/SSL tertentu, maka ganti <SSL key store file location> dengan lokasi sertifikat TLS/SSL. Jika nilai tidak diberikan, sertifikat JDK yang diinstal dalam <JAVA_HOME>/jre/lib/security/cacerts akan digunakan.

  8. Jika Anda mengubah baris 6 untuk menggunakan sertifikat TLS/SSL tertentu, perbarui baris 7 untuk menggunakan kata sandi untuk sertifikat tersebut.

  9. Perhatikan bahwa Anda harus menambahkan wilayah default (misalnya West US) untuk titik kontak, misalnya.

    region=West US

    Ini karena driver v.4x hanya memungkinkan satu DC lokal dipasangkan dengan titik kontak. Jika Anda ingin menambahkan wilayah selain default (yang merupakan wilayah yang diberikan saat akun Azure Cosmos DB pertama kali dibuat), Anda harus menggunakan akhiran regional saat menambahkan titik kontak, misalnya host-westus.cassandra.cosmos.azure.com.

  10. Simpan file config.properties.

Jalankan aplikasi Java

  1. Di jendela terminal git, cd ke folder azure-cosmosdb-cassandra-java-getting-started-v4.

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

  2. Di jendela terminal git, gunakan perintah berikut untuk membuat file cosmosdb-cassandra-examples.jar.

    mvn clean install

  3. Di jendela terminal git, jalankan perintah berikut untuk memulai aplikasi Java.

    java -cp target/cosmosdb-cassandra-examples.jar com.azure.cosmosdb.cassandra.examples.UserProfile

    Jendela terminal menampilkan pemberitahuan bahwa keyspace dan tabel telah dibuat. Jendela terminal lalu memilih dan menampilkan semua pengguna dalam tabel dan menampilkan output, lalu memilih baris menurut ID dan menampilkan nilainya.

    Tekan Ctrl+C untuk menghentikan eksekusi program dan menutup jendela konsol.

  4. Di portal Microsoft Azure, buka Data Explorer untuk membuat kueri, memodifikasi, dan bekerja dengan data baru ini.

    Menampilkan data di Data Explorer - Azure Cosmos DB

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:

  1. Pilih Metrik di menu navigasi akun Azure Cosmos DB Anda.

  2. Pilih tab seperti Latensi, dan pilih jangka waktu di sebelah kanan. Bandingkan garis Aktual dan SLA pada bagan.

    Rangkaian metrik Azure Cosmos DB

  3. 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:

  1. Di portal Azure, cari dan pilih Grup sumber daya.

  2. Dari daftar, pilih grup sumber daya yang Anda buat untuk mulai cepat ini.

    Pilih grup sumber daya yang akan dihapus

  3. Di panel Gambaran umum grup sumber daya, pilih Hapus grup sumber daya.

    Menghapus grup sumber daya

  4. 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 Cassandra Java yang membuat database dan kontainer Cassandra. Kini Anda dapat mengimpor data tambahan ke akun Azure Cosmos DB.

Mengimpor data Cassandra ke Azure Cosmos DB