Mulai cepat: Pustaka Azure Cosmos DB for Apache Gremlin untuk .NET

BERLAKU UNTUK: Gremlin

• Konsol
• Python
• Node.js
• .NET

Azure Cosmos DB for Apache Gremlin adalah layanan database grafik yang dikelola sepenuhnya yang mengimplementasikan kerangka kerja komputasi grafik yang populer Apache Tinkerpopmenggunakan bahasa kueri Gremlin. API untuk Gremlin memberi Anda cara gesekan rendah untuk mulai menggunakan Gremlin dengan layanan yang dapat tumbuh dan meluaskan skala sebanyak yang Anda butuhkan dengan manajemen minimal.

Dalam mulai cepat ini, Anda menggunakan Gremlin.Net pustaka untuk menyambungkan ke akun Azure Cosmos DB for Gremlin yang baru dibuat.

Kode sumber pustaka | Paket (NuGet)

Prasyarat

• Akun Azure dengan langganan aktif.
  • Tidak ada langganan Azure? Daftar untuk akun Azure gratis.
  • Tidak ingin langganan Azure? Anda dapat mencoba Azure Cosmos DB gratis tanpa memerlukan langganan.
• .NET (LTS)
  • Belum menginstal .NET? Coba mulai cepat ini di GitHub Codespaces.
• Azure Command-Line Interface (CLI)

Azure Cloud Shell

Azure meng-hosting Azure Cloud Shell, lingkungan shell interaktif yang dapat Anda gunakan melalui browser. Anda dapat menggunakan Bash atau PowerShell dengan Cloud Shell untuk bekerja dengan layanan Azure. Anda dapat menggunakan perintah Cloud Shell yang telah diinstal sebelumnya untuk menjalankan kode dalam artikel ini tanpa harus menginstal apa-apa di lingkungan lokal Anda.

Untuk memulai Azure Cloud Shell:

Opsi	Contoh/Tautan
Pilih Coba di pojok kanan atas blok kode atau perintah. Memilih Coba tidak otomatis menyalin kode atau perintah ke Cloud Shell.
Buka https://shell.azure.com, atau pilih tombol Luncurkan Cloud Shell untuk membuka Cloud Shell di browser Anda.
Pilih tombol Cloud Shell pada bilah menu di kanan atas di portal Microsoft Azure.

Untuk menggunakan Azure Cloud Shell:

1. Mulai Cloud Shell.

2. Pilih tombol Salin pada blok kode (atau blok perintah) untuk menyalin kode atau perintah.

3. Tempel kode atau perintah ke dalam sesi Cloud Shell dengan memilih Ctrl+Shift+V di Windows dan Linux, atau dengan memilih Cmd+Shift+V di macOS.

4. Pilih Masukkan untuk menjalankan kode atau perintah.

Menyiapkan

Bagian ini memandikan Anda membuat API untuk akun Gremlin dan menyiapkan proyek .NET untuk menggunakan pustaka untuk menyambungkan ke akun.

Membuat API untuk akun Gremlin

API untuk akun Gremlin harus dibuat sebelum menggunakan pustaka .NET. Selain itu, ini membantu juga memiliki database dan grafik di tempat.

1. Buat variabel shell untuk accountName, resourceGroupName, dan location.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos-gremlin-quickstart"
   location="westus"
   
   # Variable for account name with a randomly generated suffix
   
   let suffix=$RANDOM*$RANDOM
   accountName="msdocs-gremlin-$suffix"
   

2. Jika Anda belum melakukannya, masuk ke Azure CLI menggunakan az login.

3. Gunakan az group create untuk membuat grup sumber daya baru di langganan Anda.

   az group create \
       --name $resourceGroupName \
       --location $location
   

4. Gunakan az cosmosdb create untuk membuat API baru untuk akun Gremlin dengan pengaturan default.

   az cosmosdb create \
       --resource-group $resourceGroupName \
       --name $accountName \
       --capabilities "EnableGremlin" \
       --locations regionName=$location \
       --enable-free-tier true
   

   Catatan

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

5. Dapatkan API untuk NAMA titik akhir Gremlin untuk akun menggunakan az cosmosdb show.

   az cosmosdb show \
       --resource-group $resourceGroupName \
       --name $accountName \
       --query "name"
   

6. Temukan KEY dari daftar kunci untuk akun dengan az-cosmosdb-keys-list.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "keys" \
       --query "primaryMasterKey"
   

7. Catat nilai NAME dan KEY . Anda menggunakan kredensial ini nanti.

8. Buat database bernama cosmicworks menggunakan az cosmosdb gremlin database create.

   az cosmosdb gremlin database create \
       --resource-group $resourceGroupName \
       --account-name $accountName \
       --name "cosmicworks"
   

9. Buat grafik menggunakan az cosmosdb gremlin graph create. Beri nama grafik products, lalu atur throughput ke 400, dan akhirnya atur jalur kunci partisi ke /category.

   az cosmosdb gremlin graph create \
       --resource-group $resourceGroupName \
       --account-name $accountName \
       --database-name "cosmicworks" \
       --name "products" \
       --partition-key-path "/category" \
       --throughput 400
   

Membuat aplikasi konsol .NET baru

Buat aplikasi konsol .NET di folder kosong menggunakan terminal pilihan Anda.

1. Buka terminal Anda di folder kosong.

2. Gunakan perintah dotnet new yang menentukan templat konsol.

   dotnet new console
   

Instal paket NuGet

Gremlin.NET Tambahkan paket NuGet ke proyek .NET.

1. dotnet add package Gunakan perintah yang menentukan Gremlin.Net paket NuGet.

   dotnet add package Gremlin.Net
   

2. Buat proyek .NET menggunakan dotnet build.

   dotnet build
   

   Pastikan pembuatan berhasil tanpa kesalahan. Output yang diharapkan dari build akan terlihat seperti ini:

   Determining projects to restore...
     All projects are up-to-date for restore.
     dslkajfjlksd -> \dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll
   
   Build succeeded.
       0 Warning(s)
       0 Error(s)
   

Mengonfigurasi variabel lingkungan

Untuk menggunakan nilai NAME dan URI yang diperoleh sebelumnya dalam mulai cepat ini, pertahankan ke variabel lingkungan baru pada komputer lokal yang menjalankan aplikasi.

1. Untuk mengatur variabel lingkungan, gunakan terminal Anda untuk mempertahankan nilai sebagai COSMOS_ENDPOINT dan COSMOS_KEY masing-masing.

   export COSMOS_GREMLIN_ENDPOINT="<account-name>"
   export COSMOS_GREMLIN_KEY="<account-key>"
   

2. Validasi bahwa variabel lingkungan diatur dengan benar.

   printenv COSMOS_GREMLIN_ENDPOINT
   printenv COSMOS_GREMLIN_KEY
   

Contoh kode

• Autentikasi klien
• Membuat simpul
• Membuat tepi
• Simpul kueri & tepi

Kode dalam artikel ini tersambung ke database bernama cosmicworks dan grafik bernama products. Kode kemudian menambahkan simpul dan tepi ke grafik sebelum melintas item yang ditambahkan.

Mengautentikasi klien

Permintaan aplikasi ke sebagian besar layanan Azure harus diotorisasi. Untuk API untuk Gremlin, gunakan nilai NAME dan URI yang diperoleh sebelumnya dalam mulai cepat ini.

1. Buka file Program.cs.

2. Hapus konten yang ada dalam file.

3. Tambahkan blok penggunaan untuk Gremlin.Net.Driver namespace layanan.

   using Gremlin.Net.Driver;
   

4. Membuat accountName variabel string dan accountKey . COSMOS_GREMLIN_ENDPOINT Simpan variabel lingkungan dan COSMOS_GREMLIN_KEY sebagai nilai untuk setiap variabel masing-masing.

   string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
   string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
   

5. Buat instans baru menggunakan GremlinServer kredensial akun.

   var server = new GremlinServer(
       hostname: $"{accountName}.gremlin.cosmos.azure.com",
       port: 443,
       username: "/dbs/cosmicworks/colls/products",
       password: $"{accountKey}",
       enableSsl: true
   );
   

6. Buat instans baru menggunakan GremlinClient kredensial server jarak jauh dan serializer GraphSON 2.0 .

   using var client = new GremlinClient(
       gremlinServer: server,
       messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
   );
   

Membuat simpul

Sekarang setelah aplikasi terhubung ke akun, gunakan sintaks Gremlin standar untuk membuat simpul.

1. Gunakan SubmitAsync untuk menjalankan sisi server perintah di API untuk akun Gremlin. Buat vertex produk dengan properti berikut:

   	Nilai
   label	product
   id	68719518371
   name	Kiama classic surfboard
   price	285.55
   category	surfboards

   await client.SubmitAsync(
       requestScript: "g.addV('product').property('id', '68719518371').property('name', 'Kiama classic surfboard').property('price', 285.55).property('category', 'surfboards')"
   );
   

2. Buat verteks produk kedua dengan properti ini:

   	Nilai
   label	product
   id	68719518403
   name	Montau Turtle Surfboard
   price	600.00
   category	surfboards

   await client.SubmitAsync(
       requestScript: "g.addV('product').property('id', '68719518403').property('name', 'Montau Turtle Surfboard').property('price', 600.00).property('category', 'surfboards')"
   );
   

3. Buat verteks produk ketiga dengan properti ini:

   	Nilai
   label	product
   id	68719518409
   name	Bondi Twin Surfboard
   price	585.50
   category	surfboards

   await client.SubmitAsync(
       requestScript: "g.addV('product').property('id', '68719518409').property('name', 'Bondi Twin Surfboard').property('price', 585.50).property('category', 'surfboards')"
   );
   

Membuat tepi

Buat tepi menggunakan sintaks Gremlin untuk menentukan hubungan antar simpul.

1. Buat tepi dari Montau Turtle Surfboard produk bernama menggantikan ke Kiama classic surfboard produk.

   await client.SubmitAsync(
       requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))"
   );
   

   Tip

   Penentuan tepi ini menggunakan g.V(['<partition-key>', '<id>']) sintaks. Atau, Anda dapat menggunakan g.V('<id>').has('category', '<partition-key>').

2. Buat yang lain menggantikan tepi dari produk yang sama ke Bondi Twin Surfboard.

   await client.SubmitAsync(
       requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518409']))"
   );
   

Simpul kueri & tepi

Gunakan sintaks Gremlin untuk melintasi grafik dan menemukan hubungan antar simpul.

1. Melintasi grafik dan menemukan semua simpul yang Montau Turtle Surfboard menggantikan.

   var results = await client.SubmitAsync<Dictionary<string, object>>(
       requestScript: "g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()"
   );
   

2. Tulis ke konsol string [CREATED PRODUCT]\t68719518403statis . Kemudian, iterasi setiap vertex yang cocok menggunakan perulangan foreach dan tulis ke konsol pesan yang dimulai dengan [REPLACES PRODUCT] dan menyertakan bidang produk id yang cocok sebagai akhiran.

   Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
   foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
   {
       Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
   }
   

Menjalankan kode

Validasi bahwa aplikasi Anda berfungsi seperti yang diharapkan dengan menjalankan aplikasi. Aplikasi harus dijalankan tanpa kesalahan atau peringatan. Output aplikasi mencakup data tentang item yang dibuat dan dikueri.

1. Buka terminal di folder proyek .NET.

2. Gunakan dotnet run untuk menjalankan aplikasi.

   dotnet run
   

3. Amati output dari aplikasi.

   [CREATED PRODUCT]       68719518403
   [REPLACES PRODUCT]      68719518371
   [REPLACES PRODUCT]      68719518409
   

Membersihkan sumber daya

Ketika Anda tidak lagi memerlukan API untuk akun Gremlin, hapus grup sumber daya yang sesuai.

1. Buat variabel shell untuk resourceGroupName jika belum ada.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos-gremlin-quickstart"
   

2. Gunakan az group delete untuk menghapus grup sumber daya.

   az group delete \
       --name $resourceGroupName
   

Langkah selanjutnya

Membuat dan mengkueri data menggunakan Azure Cosmos DB untuk Apache Gremlin