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

適用於: ✅ Apache Gremlin

這很重要

您是否正在尋找一種適用於高擴展性場景的資料庫解決方案，且具有 99.999% 可用性的服務等級協定（SLA）、即時自動擴展，以及跨多個區域的自動容錯切換？請考慮適用於 NoSQL 的 Azure Cosmos DB。

您是否想要實作線上分析處理（OLAP）圖表或移轉現有的 Apache Gremlin 應用程式？考慮使用 Microsoft Fabric 中的 Graph。

開始使用適用於 .NET 的 Azure Cosmos DB for Apache Gremlin 用戶端程式庫，以儲存、管理和查詢非結構化資料。請依照本指南中的步驟建立新帳戶、安裝 .NET 用戶端程式庫、連線到帳戶、執行一般作業，以及查詢最終範例資料。

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

先決條件

Azure 訂用帳戶
- 如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。

Azure Cloud Shell 中最新版的 Azure CLI。
- 如果您想要在本機執行 CLI 參考命令，請使用 az login 命令登入 Azure CLI。

.NET SDK 9.0 或更新版本

設定

首先，設定本指南的帳號和開發環境。本節將引導您進行創建帳戶、獲取其憑證，然後準備開發環境。

建立帳戶

首先建立 Apache Gremlin 帳戶的 API。建立帳戶之後，請建立資料庫和圖形資源。

Azure CLI
Azure 入口網站

如果您還沒有目標資源群組，請使用命令 az group create 在訂用帳戶中建立新的資源群組。
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

使用命令 az cosmosdb create 來建立具有預設設定的新 Azure Cosmos DB for Apache Gremlin 帳戶。

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

使用az cosmosdb gremlin database create建立新的資料庫，命名為cosmicworks。

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

使用指令 az cosmosdb gremlin graph create 來建立名為的新圖形 products。

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

登入 Azure 入口網站 (https://portal.azure.com)。
在頂端的 [全域搜尋] 方塊中，輸入 Azure Cosmos DB。
在 [服務] 中，選取 [Azure Cosmos DB]。
在 Azure Cosmos DB 窗格中，選取建立，然後在其他索引標籤內選取 適用於 Apache Gremlin 的 Azure Cosmos DB。

在 [基本] 窗格中，設定下列選項，然後選取 [檢閱 + 建立]：

	值
工作負載類型	學習
訂閱	選取您的 Azure 訂用帳戶
資源群組	建立新的資源群組，或選取現有的資源群組
客戶名稱	提供全域唯一名稱
可用性區域	禁用
地點	為您的訂用帳戶選取支援的 Azure 區域

秘訣

您可以將任何未指定的選項保留為預設值。您也可以將帳戶設定為將帳戶總輸送量限制為每秒 1,000 個要求單位（RU/秒），或啟用免費層以將成本降到最低。

在 [檢閱 + 建立] 窗格中，等候您的帳戶驗證順利完成，然後選取 [建立]。
入口網站會自動流覽至 [部署] 窗格。等候部署完成。
部署完成後，請選取 [ 移至資源 ] 以導覽至新的 API for Apache Gremlin 帳戶。
在資源功能表中，選取 [資料總管 ] 選項。
在資料總管中，選取 [+ 新增圖形]。
在 [ 新增圖形 ] 對話方塊中，設定下列選項，然後選取 [ 確定]：

值

資料庫 新建

資料庫名稱 cosmicworks

圖形名稱 products

分區鍵 /category

秘訣

您可以將任何未指定的選項保留為預設值。

	值
資料庫	新建
資料庫名稱	`cosmicworks`
圖形名稱	`products`
分區鍵	`/category`

取得認證

現在，取得客戶端程式庫所需的密碼，以建立與最近創建的帳戶的連接。

Azure CLI
Azure 入口網站

使用 az cosmosdb show 來取得帳戶的主機。

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

記錄先前命令輸出中屬性 host 的值。此屬性的值是您稍後在本指南中用來連線到具有程式庫的帳戶的主機。

使用 az cosmosdb keys list 可獲得帳戶的金鑰。

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

記錄先前命令輸出中屬性 primaryMasterKey 的值。此屬性的值是您在本指南稍後用來使用程式庫連接至帳戶的金鑰。

準備開發環境

然後，使用新專案和用戶端程式庫來設定您的開發環境。此步驟是繼續本指南其餘部分之前的最後一個必要先決條件。

從空白資料夾中開始。
建立新的 .NET 主控台應用程式
```
dotnet new console
```
從 NuGet 匯入 Gremlin.Net 套件。
```
dotnet add package Gremlin.Net
```
建置專案。
```
dotnet build
```

物件模型

	說明
`GremlinClient`	代表用來連線 Gremlin 伺服器並與之互動的用戶端
`GraphTraversalSource`	用來建構和執行 Gremlin 周遊

驗證用戶端

首先，使用本指南稍早收集的認證來驗證用戶端。

在整合開發環境（IDE）中開啟 Program.cs 檔案。
刪除檔案內的任何現有內容。
為下列命名空間新增 using 指示詞：
- Gremlin.Net.Driver
- Gremlin.Net.Structure.IO.GraphSON
```
using Gremlin.Net.Driver;
using Gremlin.Net.Structure.IO.GraphSON;
```
為本指南稍早收集的認證建立字串變數。將變數 hostname 命名為 primaryKey和。
```
string hostname = "<host>";
string primaryKey = "<key>";
```

使用先前步驟中建立的認證和組態變數建立一個GremlinServer。將變數 server命名為。

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

現在，使用GremlinClient變數和server配置建立GraphSON2MessageSerializer。
```
GremlinClient client = new(
    server,
    new GraphSON2MessageSerializer()
);
```

插入數據

接下來，將新的頂點和邊緣資料插入到圖形中。在建立新資料之前，請清除任何現有資料的圖表。

執行 g.V().drop() 查詢以清除圖形中的所有頂點和邊緣。
```
await client.SubmitAsync("g.V().drop()");
```

建立可新增頂點的 Gremlin 查詢。

string insertVertexQuery = """
    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)
""";

新增單一產品的頂點。

await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
{
    ["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
});

再新增兩個頂點，即可獲得兩個額外的產品。

await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
{
    ["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.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
{
    ["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
});

建立另一個新增邊緣的 Gremlin 查詢。

string insertEdgeQuery = """
    g.V([prop_partition_key, prop_source_id])
        .addE('replaces')
        .to(g.V([prop_partition_key, prop_target_id]))
""";

新增兩個邊緣。

await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
{
    ["prop_partition_key"] = "gear-surf-surfboards",
    ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
    ["prop_target_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
});

await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
{
    ["prop_partition_key"] = "gear-surf-surfboards",
    ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
    ["prop_target_id"] = "cccccccc-2222-3333-4444-dddddddddddd"
});

讀取資料

然後，讀取先前插入圖表的資料。

建立查詢，使用唯一識別碼和分區鍵值來讀取頂點。
```
string readVertexQuery = "g.V([prop_partition_key, prop_id])";
```

然後，透過提供必要的參數來讀取頂點。

ResultSet<Dictionary<string, object>> readResults = await client.SubmitAsync<Dictionary<string, object>>(readVertexQuery, new Dictionary<string, object>
{
    ["prop_partition_key"] = "gear-surf-surfboards",
    ["prop_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
});

Dictionary<string, object> matchedItem = readResults.Single();

查詢數據

最後，使用查詢來尋找與圖形中特定遍歷或篩選器相符的所有資料。

撰寫查詢以找出從特定頂點延伸出去的所有頂點。

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

執行指定 Montau Turtle Surfboard 產品的查詢。

ResultSet<Dictionary<string, object>> findResults = await client.SubmitAsync<Dictionary<string, object>>(findVerticesQuery, new Dictionary<string, object>
{
    ["prop_partition_key"] = "gear-surf-surfboards",
    ["prop_name"] = "Montau Turtle Surfboard"
});

逐一查看查詢結果。

foreach (Dictionary<string, object> result in findResults)
{
    // Do something here with each result
}

執行程式碼

使用應用程式目錄中的終端機執行新建立的應用程式。

dotnet run

清除資源

當您不再需要帳戶時，請從 Azure 訂用帳戶中移除帳戶，方法是刪除該資源。

Azure CLI
Azure 入口網站

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

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-30