Panduan Cepat: Azure Cosmos DB untuk pustaka klien Apache Gremlin di Python

• 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 menggunakan pustaka klien Azure Cosmos DB for Apache Gremlin di Python untuk menyimpan, mengelola, dan mengkueri data yang tidak terstruktur. Ikuti langkah-langkah dalam panduan ini untuk membuat akun baru, menginstal pustaka klien Python, menyambungkan ke akun, melakukan operasi umum, dan mengkueri data sampel akhir Anda.

Kode sumber pustaka | Paket (PyPi)

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 .

• Python 3.12 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. gremlinpython Impor paket dari Indeks Paket Python (PyPI).

   pip install gremlinpython
   

3. Buat file app.py.

Model objek

	Deskripsi
GremlinClient	Mewakili klien yang digunakan untuk menyambungkan dan berinteraksi dengan 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 app.py di lingkungan pengembangan terintegrasi (IDE) Anda.

2. Memasukkan jenis berikut ini dari pustaka gremlin_python.driver:

   • gremlin_python.driver.client
   • gremlin_python.driver.serializer

   from gremlin_python.driver import client, serializer
   

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

   hostname = "<host>"
   primary_key = "<key>"
   

4. Buat Client objek menggunakan kredensial dan variabel konfigurasi yang dibuat di langkah-langkah sebelumnya. Beri nama variabel client.

   client = client.Client(
       url=f"wss://{hostname}.gremlin.cosmos.azure.com:443/",
       traversal_source="g",
       username="/dbs/cosmicworks/colls/products",
       password=f"{primary_key}",
       message_serializer=serializer.GraphSONSerializersV2d0()
   )
   

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.

   client.submit("g.V().drop()").all().result()
   

2. Buat kueri Gremlin yang menambahkan vertex.

   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.

   client.submit(
       message=insert_vertex_query,
       bindings={
           "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,
       },
   ).all().result()
   

4. Tambahkan dua simpul lagi untuk dua produk tambahan.

   client.submit(
       message=insert_vertex_query,
       bindings={
           "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,
       },
   ).all().result()
   
   client.submit(
       message=insert_vertex_query,
       bindings={
           "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,
       },
   ).all().result()
   

5. Buat kueri Gremlin lain yang menambahkan tepi.

   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.

   client.submit(
       message=insert_edge_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_target_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       },
   ).all().result()
   
   client.submit(
       message=insert_edge_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_target_id": "cccccccc-2222-3333-4444-dddddddddddd",
       },
   ).all().result()
   

Baca data

Kemudian, baca data yang sebelumnya disisipkan ke dalam grafik.

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

   read_vertex_query = "g.V([prop_partition_key, prop_id])"
   

2. Kemudian, baca titik sudut dengan menyediakan parameter yang diperlukan.

   matched_item = client.submit(
       message=read_vertex_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
       }
   ).one()
   

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.

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

2. Jalankan kueri yang menentukan produk Montau Turtle Surfboard.

   find_results = client.submit(
       message=find_vertices_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_name": "Montau Turtle Surfboard",
       },
   ).all().result()
   

3. Lakukan iterasi terhadap hasil kueri.

   for result in find_results:
       # Do something here with each result
   

Menjalankan kode

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

python app.py

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.