快速入門:適用於 .NET 的適用於 Apache Gremlin 的 Azure Cosmos DB 連結庫
適用於: Gremlin
適用於 Apache Gremlin 的 Azure Cosmos DB 是完全受控的圖形資料庫服務,使用 Gremlin 查詢語言實作熱門 Apache Tinkerpop
的圖表運算架構。 Gremlin 的 API 可讓您以低摩擦的方式開始使用 Gremlin 與服務,以盡可能減少管理的需求來擴增和相應放大。
在本快速入門中,您會使用連結 Gremlin.Net
庫連線到新建立的 Azure Cosmos DB for Gremlin 帳戶。
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。
- 沒有 Azure 訂用帳戶? 註冊免費的 Azure 帳戶。
- 不想要 Azure 訂用帳戶嗎? 您可以 免費試用 Azure Cosmos DB,而不需要訂用帳戶。
- .NET (LTS)
- 尚未安裝 .NET? 請在 GitHub Codespaces 中試用本快速入門。
- Azure 命令列介面 (CLI)
Azure Cloud Shell
Azure Cloud Shell 是裝載於 Azure 中的互動式殼層環境,可在瀏覽器中使用。 您可以使用 Bash 或 PowerShell 搭配 Cloud Shell,與 Azure 服務共同使用。 您可以使用 Cloud Shell 預先安裝的命令,執行本文提到的程式碼,而不必在本機環境上安裝任何工具。
要啟動 Azure Cloud Shell:
選項 | 範例/連結 |
---|---|
選取程式碼或命令區塊右上角的 [試試看]。 選取 [試試看] 並不會自動將程式碼或命令複製到 Cloud Shell 中。 | |
請前往 https://shell.azure.com,或選取 [啟動 Cloud Shell] 按鈕,在瀏覽器中開啟 Cloud Shell。 | |
選取 Azure 入口網站右上方功能表列上的 [Cloud Shell] 按鈕。 |
若要使用 Azure Cloud Shell:
啟動 Cloud Shell。
選取程式碼區塊 (或命令區塊) 上的 [複製] 按鈕以複製程式碼或命令。
透過在 Windows 和 Linux 上選取 Ctrl+Shift+V;或在 macOS 上選取 Cmd+Shift+V,將程式碼或命令貼到 Cloud Shell 工作階段中。
選取 Enter 鍵執行程式碼或命令。
設定
本節將逐步引導您建立 Gremlin 帳戶的 API,並設定 .NET 專案以使用連結庫來聯機到帳戶。
建立 Gremlin 帳戶的 API
使用 .NET 連結庫之前,應該先建立 Gremlin 帳戶的 API。 此外,它也有助於建立資料庫和圖形。
建立 accountName、resourceGroupName 和 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"
如果您尚未登入,請使用
az login
登入 Azure CLI。使用
az group create
在您的訂用帳戶中建立新的資源群組。az group create \ --name $resourceGroupName \ --location $location
使用
az cosmosdb create
建立具有預設設定之 Gremlin 帳戶的新 API。az cosmosdb create \ --resource-group $resourceGroupName \ --name $accountName \ --capabilities "EnableGremlin" \ --locations regionName=$location \ --enable-free-tier true
注意
每個 Azure 訂用帳戶最多可以有一個免費層 Azure Cosmos DB 帳戶,而且在建立帳戶時必須選擇加入。 如果此命令無法套用免費層折扣,這表示訂用帳戶中的另一個帳戶已啟用免費層。
使用
az cosmosdb show
取得帳戶的 Gremlin 端點名稱 API。az cosmosdb show \ --resource-group $resourceGroupName \ --name $accountName \ --query "name"
從具有
az-cosmosdb-keys-list
的帳戶金鑰清單中尋找 KEY。az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "keys" \ --query "primaryMasterKey"
記錄 NAME 和 KEY 值。 您稍後會使用這些認證。
使用
az cosmosdb gremlin database create
建立名為cosmicworks
的資料庫。az cosmosdb gremlin database create \ --resource-group $resourceGroupName \ --account-name $accountName \ --name "cosmicworks"
使用
az cosmosdb gremlin graph create
建立圖形。 將圖形products
命名為 ,然後將輸送量設定為400
,最後將分割區索引鍵路徑設定為/category
。az cosmosdb gremlin graph create \ --resource-group $resourceGroupName \ --account-name $accountName \ --database-name "cosmicworks" \ --name "products" \ --partition-key-path "/category" \ --throughput 400
建立新的 .NET 主控台應用程式
使用您慣用的終端機,在空白資料夾中建立 .NET 控制台應用程式。
在空白資料夾中開啟您的終端機。
dotnet new
使用指定主控台範本的命令。dotnet new console
安裝 NuGet 套件
將 Gremlin.NET
NuGet 套件新增至 .NET 專案。
dotnet add package
使用指定 NuGet 套件的Gremlin.Net
命令。dotnet add package Gremlin.Net
使用
dotnet build
建置 .NET 專案。dotnet build
請確定建置成功,且沒有任何錯誤。 組建的預期輸出看起來應像這樣:
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)
設定環境變數
若要使用 本快速入門稍早取得的 NAME 和 URI 值,請將這些值保存在執行應用程式的本機電腦上新的環境變數。
若要設定環境變數,請使用終端機將值分別保留為
COSMOS_ENDPOINT
和COSMOS_KEY
。export COSMOS_GREMLIN_ENDPOINT="<account-name>" export COSMOS_GREMLIN_KEY="<account-key>"
驗證已正確設定環境變數。
printenv COSMOS_GREMLIN_ENDPOINT printenv COSMOS_GREMLIN_KEY
程式碼範例
本文中的程式代碼會連線到名為 cosmicworks
的資料庫,以及名為 products
的圖表。 然後,程式代碼會在周遊新增的專案之前,將頂點和邊緣新增至圖形。
驗證用戶端
對大部分 Azure 服務的應用程式要求都必須獲得授權。 針對 Gremlin 的 API,請使用 本快速入門稍早取得的 NAME 和 URI 值。
開啟 Program.cs 檔案。
刪除檔案內的任何現有內容。
為命名空間新增using區塊
Gremlin.Net.Driver
。using Gremlin.Net.Driver;
建立
accountName
和accountKey
字串變數。 將COSMOS_GREMLIN_ENDPOINT
和COSMOS_GREMLIN_KEY
環境變數儲存為每個個別變數的值。string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!; string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
使用帳戶的認證建立 的新實例
GremlinServer
。var server = new GremlinServer( hostname: $"{accountName}.gremlin.cosmos.azure.com", port: 443, username: "/dbs/cosmicworks/colls/products", password: $"{accountKey}", enableSsl: true );
使用遠端伺服器認證和 GraphSON 2.0 串行化程式,建立的新實例
GremlinClient
。using var client = new GremlinClient( gremlinServer: server, messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer() );
建立頂點
既然應用程式已連線到帳戶,請使用標準 Gremlin 語法來建立頂點。
使用
SubmitAsync
在 Gremlin 帳戶的 API 上執行命令伺服器端。 使用下列屬性建立 產品 頂點:值 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')" );
使用下列屬性建立第二 個產品 頂點:
值 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')" );
使用下列屬性建立第三 個產品 頂點:
值 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')" );
建立邊緣
使用 Gremlin 語法建立邊緣,以定義頂點之間的關聯性。
從名為 的產品建立
Montau Turtle Surfboard
邊緣,取代為Kiama classic surfboard
產品。await client.SubmitAsync( requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))" );
提示
此邊緣定義會使用
g.V(['<partition-key>', '<id>'])
語法。 或者,您可以使用g.V('<id>').has('category', '<partition-key>')
。建立另一個 取代 相同產品的邊緣到
Bondi Twin Surfboard
。await client.SubmitAsync( requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518409']))" );
查詢頂點和邊緣
使用 Gremlin 語法來周遊圖表,並探索頂點之間的關聯性。
周遊圖表並尋找取代的所有頂點
Montau Turtle Surfboard
。var results = await client.SubmitAsync<Dictionary<string, object>>( requestScript: "g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()" );
寫入主控台靜態字串
[CREATED PRODUCT]\t68719518403
。 然後,使用迴圈逐一foreach
查看每個相符頂點,並將開頭[REPLACES PRODUCT]
為的訊息寫入主控台,並包含相符的產品id
字段作為後綴。Console.WriteLine($"[CREATED PRODUCT]\t68719518403"); foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>()) { Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}"); }
執行程式碼
執行應用程式來驗證您的應用程式是否如預期般運作。 應用程式應該不會執行任何錯誤或警告。 應用程式的輸出包含已建立和查詢專案的相關數據。
開啟 .NET 項目資料夾中的終端機。
使用
dotnet run
來執行應用程式。dotnet run
觀察應用程式的輸出。
[CREATED PRODUCT] 68719518403 [REPLACES PRODUCT] 68719518371 [REPLACES PRODUCT] 68719518409
清除資源
當您不再需要 Gremlin 帳戶的 API 時,請刪除對應的資源群組。
如果 resourceGroupName 不存在,請建立殼層變數。
# Variable for resource group name resourceGroupName="msdocs-cosmos-gremlin-quickstart"
使用
az group delete
來刪除資源群組。az group delete \ --name $resourceGroupName