快速入门：适用于 .NET 的 Azure Cosmos DB for Apache Gremlin 客户端库

适用于 .NET 的 Azure Cosmos DB for Apache Gremlin 客户端库入门，用于存储、管理和查询非结构化数据。 按照本指南中的步骤创建新帐户、安装 .NET 客户端库、连接到帐户、执行常见作以及查询最终示例数据。

库源代码 | 包 (NuGet)

Prerequisites

• Azure 订阅服务

  • 如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

• Azure Cloud Shell 中最新版本的 Azure CLI。

  • 如果想要在本地运行 CLI 引用命令，请使用 az login 该命令登录到 Azure CLI。

• .NET SDK 9.0 或更高版本

设置

首先，为本指南设置帐户和开发环境。 本部分将指导你完成创建帐户、获取其凭据以及准备开发环境的过程。

创建帐户

首先创建用于 Apache Gremlin 帐户的 API。 创建帐户后，创建数据库和图形资源。

获取凭据

现在，获取用于创建与最近创建的帐户的连接的客户端库的密码。

准备开发环境

然后，使用新项目和客户端库配置开发环境。 在转到本指南的其余部分之前，此步骤是最后一个必需的先决条件。

1. 从空文件夹开始。

2. 创建新的 .NET 控制台应用程序

   dotnet new console
   

3. 从 NuGet 导入Gremlin.Net包。

   dotnet add package Gremlin.Net
   

4. 构建项目。

   dotnet build
   

对象模型

代码示例

• 对客户端进行身份验证
• 插入数据
• 读取数据
• 查询数据

对客户端进行身份验证

首先，使用本指南前面收集的凭据对客户端进行身份验证。

1. 在集成开发环境（IDE）中打开 Program.cs 文件。

2. 删除文件中的任何现有内容。

3. 为以下命名空间添加 using 指令：

   • Gremlin.Net.Driver
   • Gremlin.Net.Structure.IO.GraphSON

   using Gremlin.Net.Driver;
   using Gremlin.Net.Structure.IO.GraphSON;
   

4. 为本指南前面收集的凭据创建字符串变量。 命名变量 hostname 和 primaryKey.

   string hostname = "<host>";
   string primaryKey = "<key>";
   

5. 使用在前面步骤中创建的凭据和配置变量来创建 GremlinServer。 为变量 server 命名。

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

6. 现在，使用server变量和GraphSON2MessageSerializer配置创建一个GremlinClient。

   GremlinClient client = new(
       server,
       new GraphSON2MessageSerializer()
   );
   

插入数据

接下来，在图形中插入新的顶点和边缘数据。 创建新数据之前，请清除任何现有数据的图形。

1. g.V().drop()运行查询以清除图形中的所有顶点和边缘。

   await client.SubmitAsync("g.V().drop()");
   

2. 创建添加顶点的 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)
   """;
   

3. 为单个产品添加顶点。

   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
   });
   

4. 为两个额外产品再添加两个顶点。

   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
   });
   

5. 创建另一个用于添加边的 Gremlin 查询。

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

6. 添加两个边缘。

   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"
   });
   

读取数据

然后，读取以前插入到图形中的数据。

1. 创建使用唯一标识符和分区键值读取顶点的查询。

   string readVertexQuery = "g.V([prop_partition_key, prop_id])";
   

2. 然后，通过提供所需的参数来读取顶点。

   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();
   

查询数据

最后，使用查询查找与图中特定遍历或筛选器匹配的所有数据。

1. 创建一个查询，用于查找从特定顶点遍历的所有顶点。

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

2. 执行指定 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"
   });
   

3. 遍历查询结果。

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

运行代码

使用应用程序目录中的终端运行新创建的应用程序。

dotnet run

清理资源

如果不再需要此帐户，请通过删除资源来从 Azure 订阅中删除该帐户。

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

后续步骤