Panduan Cepat: Pustaka Klien Azure Cosmos DB untuk Apache Gremlin Node.js

• Python
• Node.js
• C#

Penting

Apakah Anda mencari solusi database untuk skenario skala tinggi dengan perjanjian tingkat layanan ketersediaan (SLA) 99,999%, skala otomatis instan, dan failover otomatis di beberapa wilayah? Pertimbangkan Azure Cosmos DB untuk NoSQL.

Apakah Anda ingin menerapkan grafik pemrosesan analitik online (OLAP) atau memigrasikan aplikasi Apache Gremlin yang ada? Pertimbangkan Graph di Microsoft Fabric.

Mulai memanfaatkan pustaka klien Azure Cosmos DB untuk Apache Gremlin Node.js guna menyimpan, mengelola, dan melakukan kueri 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.

Paket kode | sumber pustaka (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

Menyiapkan

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 Gremlin. Setelah akun dibuat, buat database dan sumber daya grafik.

Azure CLI

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

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

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

3. Buat database baru menggunakan az cosmosdb gremlin database create bernama cosmicworks.

   az cosmosdb gremlin database create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --name "cosmicworks"
   

4. az cosmosdb gremlin graph create Gunakan perintah untuk membuat grafik baru bernama products.

   az cosmosdb gremlin graph create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --database-name "cosmicworks" \
       --name "products" \
       --partition-key-path "/category"
   

Portal Microsoft Azure

1. Masuk ke portal Azure (https://portal.azure.com).

2. Masukkan Azure Cosmos DB di bilah pencarian global.

3. Dalam Layanan, pilih Azure Cosmos DB.

4. Di panel Azure Cosmos DB , pilih Buat, lalu Azure Cosmos DB untuk Apache Gremlin dalam tab Lainnya .

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

6. Pada panel Tinjau + buat , tunggu validasi akun Anda berhasil diselesaikan, lalu pilih Buat.

7. Portal secara otomatis menavigasi ke panel Penyebaran. Tunggu hingga penerapan selesai.

8. Setelah penyebaran selesai, pilih Buka sumber daya untuk menavigasi ke API baru untuk akun Apache Gremlin.

9. Di menu sumber daya, pilih opsi Data Explorer .

10. Di Data Explorer, pilih + Grafik Baru.

11. Dalam dialog Tambahkan Grafik , konfigurasikan opsi berikut, lalu pilih OK:

    	Nilai
    Database	Buat baru
    Nama database	cosmicworks
    Nama grafik	products
    kunci partisi	/category

    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

1. Gunakan az cosmosdb show untuk mendapatkan host untuk akun tersebut.

   az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "{host:name}"
   

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

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

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

Portal Microsoft Azure

1. Di menu sumber daya untuk akun, pilih opsi Gambaran Umum .

2. Catat nilai nama akun. Nilai properti ini adalah host yang Anda gunakan nanti dalam panduan ini untuk menyambungkan ke akun dengan pustaka.

3. Pada menu sumber daya akun yang sama, pilih opsi Koneksi String pada bagian Pengaturan.

4. Mengekspos dan merekam nilai bidang KUNCI PRIMER di halaman ini. Nilai properti ini adalah kunci 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.

1. Mulai dalam folder kosong.

2. Menginisialisasi modul baru.

   npm init es6 --yes
   

3. gremlin Instal paket dari Node Package Manager (npm).

   npm install --save gremlin
   

4. Buat file index.js .

1. Mulai dalam folder kosong.

2. Menginisialisasi modul baru.

   npm init es6 --yes
   

3. typescript Instal paket dari Node Package Manager (npm).

   npm install --save-dev typescript
   

4. tsx Instal paket dari npm.

   npm install --save-dev tsx
   

5. gremlin Instal paket dari npm.

   npm install --save gremlin
   

6. @types/node Instal paket dari npm.

   npm install --save-dev @types/node
   

7. @types/gremlin Instal paket dari npm.

   npm install --save-dev @types/gremlin
   

8. Inisialisasi proyek TypeScript menggunakan pengkompilasi (tsc).

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

9. Buat file index.ts .

Model objek

	Deskripsi
DriverRemoteConnection	Mewakili koneksi ke server Gremlin
GraphTraversalSource	Digunakan untuk membangun dan menjalankan traversal Gremlin

Contoh kode

• Mengautentikasi klien
• Sisipkan data
• Membaca data
• Kueri data

Mengautentikasi klien

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

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

2. Impor paket gremlin dan jenis yang diperlukan.

   import gremlin from 'gremlin';
   const { Client, auth } = gremlin.driver;
   const { PlainTextSaslAuthenticator } = auth;
   

3. Buat variabel string untuk kredensial yang dikumpulkan sebelumnya dalam panduan ini. Beri nama variabel hostname dan primaryKey.

   const hostname = '<host>';
   const primaryKey = '<key>';
   

4. Buat objek jenis PlainTextSaslAuthenticator menggunakan info masuk dan variabel konfigurasi yang dibuat di langkah-langkah sebelumnya. Simpan objek dalam variabel bernama authenticator.

   const authenticator = new PlainTextSaslAuthenticator(
       '/dbs/cosmicworks/colls/products',
       primaryKey
   );
   

5. Buat Client objek menggunakan variabel pengautentikasi. Beri nama variabel client.

   const client = new Client(
       `wss://${hostname}.gremlin.cosmos.azure.com:443/`,
       {
           authenticator,
           traversalsource: 'g',
           rejectUnauthorized: true,
           mimeType: 'application/vnd.gremlin-v2.0+json'
       }
   );
   

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

2. Impor paket gremlin dan jenis yang diperlukan.

   import gremlin from 'gremlin';
   const { Client, auth } = gremlin.driver;
   const { PlainTextSaslAuthenticator } = auth;
   

3. Buat variabel string untuk kredensial yang dikumpulkan sebelumnya dalam panduan ini. Beri nama variabel hostname dan primaryKey.

   const hostname: string = '<host>';
   const primaryKey: string = '<key>';
   

4. Buat objek jenis PlainTextSaslAuthenticator menggunakan info masuk dan variabel konfigurasi yang dibuat di langkah-langkah sebelumnya. Simpan objek dalam variabel bernama authenticator.

   const authenticator = new PlainTextSaslAuthenticator(
       '/dbs/cosmicworks/colls/products',
       primaryKey
   );
   

5. Buat Client objek menggunakan variabel pengautentikasi. Beri nama variabel client.

   const client = new Client(
       `wss://${hostname}.gremlin.cosmos.azure.com:443/`,
       {
           authenticator,
           traversalsource: 'g',
           rejectUnauthorized: true,
           mimeType: 'application/vnd.gremlin-v2.0+json'
       }
   );
   

Sisipkan data

Selanjutnya, sisipkan data vertex dan edge baru ke dalam grafik. Sebelum membuat data baru, hapus grafik data yang ada.

1. Jalankan g.V().drop() kueri untuk menghapus semua simpul dan tepi dari grafik.

   await client.submit('g.V().drop()');
   

2. Buat kueri Gremlin yang menambahkan vertex.

   const insert_vertex_query = `
       g.addV('product')
           .property('id', prop_id)
           .property('name', prop_name)
           .property('category', prop_category)
           .property('quantity', prop_quantity)
           .property('price', prop_price)
           .property('clearance', prop_clearance)
   `;
   

3. Tambahkan vertex untuk satu produk.

   await client.submit(insert_vertex_query, {
       prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
       prop_name: 'Yamba Surfboard',
       prop_category: 'gear-surf-surfboards',
       prop_quantity: 12,
       prop_price: 850.00,
       prop_clearance: false,
   });
   

4. Tambahkan dua simpul lagi untuk dua produk tambahan.

   await client.submit(insert_vertex_query, {
       prop_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
       prop_name: 'Montau Turtle Surfboard',
       prop_category: 'gear-surf-surfboards',
       prop_quantity: 5,
       prop_price: 600.00,
       prop_clearance: true,
   });
   
   await client.submit(insert_vertex_query, {
       prop_id: 'cccccccc-2222-3333-4444-dddddddddddd',
       prop_name: 'Noosa Surfboard',
       prop_category: 'gear-surf-surfboards',
       prop_quantity: 31,
       prop_price: 1100.00,
       prop_clearance: false,
   });
   

5. Buat kueri Gremlin lain yang menambahkan tepi.

   const insert_edge_query = `
       g.V([prop_partition_key, prop_source_id])
           .addE('replaces')
           .to(g.V([prop_partition_key, prop_target_id]))
   `;
   

6. Tambahkan dua tepi.

   await client.submit(insert_edge_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
       prop_target_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
   });
   
   await client.submit(insert_edge_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
       prop_target_id: 'cccccccc-2222-3333-4444-dddddddddddd',
   });
   

1. Jalankan g.V().drop() kueri untuk menghapus semua simpul dan tepi dari grafik.

   await client.submit('g.V().drop()');
   

2. Buat kueri Gremlin yang menambahkan vertex.

   const insert_vertex_query: string = `
       g.addV('product')
           .property('id', prop_id)
           .property('name', prop_name)
           .property('category', prop_category)
           .property('quantity', prop_quantity)
           .property('price', prop_price)
           .property('clearance', prop_clearance)
   `;
   

3. Tambahkan vertex untuk satu produk.

   await client.submit(insert_vertex_query, {
       prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
       prop_name: 'Yamba Surfboard',
       prop_category: 'gear-surf-surfboards',
       prop_quantity: 12,
       prop_price: 850.00,
       prop_clearance: false,
   });
   

4. Tambahkan dua simpul lagi untuk dua produk tambahan.

   await client.submit(insert_vertex_query, {
       prop_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
       prop_name: 'Montau Turtle Surfboard',
       prop_category: 'gear-surf-surfboards',
       prop_quantity: 5,
       prop_price: 600.00,
       prop_clearance: true,
   });
   
   await client.submit(insert_vertex_query, {
       prop_id: 'cccccccc-2222-3333-4444-dddddddddddd',
       prop_name: 'Noosa Surfboard',
       prop_category: 'gear-surf-surfboards',
       prop_quantity: 31,
       prop_price: 1100.00,
       prop_clearance: false,
   });
   

5. Buat kueri Gremlin lain yang menambahkan tepi.

   const insert_edge_query: string = `
       g.V([prop_partition_key, prop_source_id])
           .addE('replaces')
           .to(g.V([prop_partition_key, prop_target_id]))
   `;
   

6. Tambahkan dua tepi.

   await client.submit(insert_edge_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
       prop_target_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
   });
   
   await client.submit(insert_edge_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_source_id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
       prop_target_id: 'cccccccc-2222-3333-4444-dddddddddddd',
   });
   

Baca data

Kemudian, baca data yang sebelumnya disisipkan ke dalam grafik.

1. Buat kueri yang membaca vertex dengan menggunakan pengidentifikasi unik dan nilai kunci partisi.

   const read_vertex_query = 'g.V([prop_partition_key, prop_id])';
   

2. Kemudian, baca sebuah vertex dengan memberikan parameter yang diperlukan.

   let read_results = await client.submit(read_vertex_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
   });
   
   let matched_item = read_results._items[0];
   

1. Buat kueri yang membaca vertex dengan menggunakan pengidentifikasi unik dan nilai kunci partisi.

   const read_vertex_query: string = 'g.V([prop_partition_key, prop_id])';
   

2. Kemudian, baca sebuah vertex dengan memberikan parameter yang diperlukan.

   let read_results = await client.submit(read_vertex_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
   });
   
   let matched_item = read_results._items[0];
   

Mencari data

Terakhir, gunakan kueri untuk menemukan semua data yang cocok dengan traversal atau filter tertentu dalam grafik.

1. Buat kueri yang menemukan semua simpul yang melintasi keluar dari vertex tertentu.

   const find_vertices_query = `
       g.V().hasLabel('product')
           .has('category', prop_partition_key)
           .has('name', prop_name)
           .outE('replaces').inV()
   `;
   

2. Jalankan kueri dengan menentukan produk Montau Turtle Surfboard.

   let find_results = await client.submit(find_vertices_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_name: 'Montau Turtle Surfboard',
   });
   

3. Mengiterasi hasil kueri.

   for (const item of find_results._items) {
       // Do something here with each result
   }
   

1. Buat kueri yang menemukan semua simpul yang melintasi keluar dari vertex tertentu.

   const find_vertices_query: string = `
       g.V().hasLabel('product')
           .has('category', prop_partition_key)
           .has('name', prop_name)
           .outE('replaces').inV()
   `;
   

2. Jalankan kueri dengan menentukan produk Montau Turtle Surfboard.

   let find_results = await client.submit(find_vertices_query, {
       prop_partition_key: 'gear-surf-surfboards',
       prop_name: 'Montau Turtle Surfboard',
   });
   

3. Mengiterasi hasil kueri.

   for (const item of find_results._items) {
       // 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

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

Portal Microsoft Azure

1. Navigasikan ke sumber daya Azure Cosmos DB for Apache Gremlin yang sudah ada yang Anda buat sebelumnya dalam panduan ini.

2. Pada halaman sumber daya, pilih Hapus dari bilah menu.

3. Ikuti instruksi dalam dialog konfirmasi.