快速入門：適用於 .NET 的 Azure Cosmos DB for Apache Gremlin 程式庫

發行項
08/15/2024

適用於： Gremlin

Azure Cosmos DB for Apache Gremlin 是一項完全受控的圖形資料庫服務，會實作熱門的 Apache Tinkerpop (這是一種使用 Gremlin 查詢語言的圖形運算架構)。 API for Gremlin 讓使用 Gremlin 更為平順，該服務可根據您的需求以最少的管理方式進行拓展與擴增。

在本快速入門中，您將使用 Gremlin.Net 程式庫連線至新建立的 Azure Cosmos DB for Gremlin 帳戶。

程式庫原始程式碼 | 套件 (NuGet)

必要條件

具有有效訂用帳戶的 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 鍵執行程式碼或命令。

設定

本節將逐步引導您建立 API for Gremlin 帳戶，並設定 .NET 專案以使用程式庫連線至該帳戶。

建立 API for Gremlin 帳戶

使用 .NET 程式庫之前，請先建立 API for Gremlin 帳戶。此外，它還有助於建立資料庫和圖形。

建立 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 建立新的且具有預設設定的 API for Gremlin 帳戶。
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
注意

每個 Azure 訂用帳戶最多可以有一個免費層的 Azure Cosmos DB 帳戶，而且必須在建立帳戶時選擇加入。如果該命令無法套用免費階層折扣，這表示訂用帳戶中的另一個帳戶已啟用免費階層。

使用 az cosmosdb show 取得該帳戶的 API for Gremlin 端點 NAME。

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 專案。

使用指定 Gremlin.Net NuGet 套件的 dotnet add package 命令。
```
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 服務的應用程式要求都必須獲得授權。若為 API for Gremlin，請使用本快速入門前面所取得的 NAME 和 URI 值。

開啟 Program.cs 檔案。
刪除檔案內的任何現有內容。
為 Gremlin.Net.Driver 命名空間新增 using 區塊。
```
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 在 API for Gremlin 帳戶上執行伺服器端命令。建立具有以下屬性的 product 頂點：

	值
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')"
);

建立具有下列屬性的第二個 product 頂點：

	值
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')"
);

建立具有下列屬性的第三個 product 頂點：

	值
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 產品且名為 replaces 的邊緣。
```
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 的另一個 replaces 邊緣。

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

清除資源

如果不再需要 API for Gremlin 帳戶，請刪除對應的資源群組。

如果 resourceGroupName 不存在，請建立其殼層變數。

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

使用 az group delete 來刪除資源群組。

az group delete \
    --name $resourceGroupName

後續步驟

使用 Azure Cosmos DB for Apache Gremlin 建立和查詢資料

共用方式為