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

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

库源代码 | 包 (NuGet)

先决条件

• Azure 订阅

  • 如果没有 Azure 订阅，请在开始前创建 试用版 。

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

• .NET SDK 9.0 或更高版本

设置

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

创建帐户

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

获取凭据

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

准备开发环境

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

1. 从空文件夹中开始。

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

   dotnet new console
   

3. Gremlin.Net从 NuGet 导入包。

   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.cn",
       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>"

下一步