你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

快速入门:适用于 .NET 的 Azure Cosmos DB for Apache Gremlin 库

适用对象: Gremlin

Azure Cosmos DB for Apache Gremlin 是一种完全托管的图形数据库服务,用于实现常用的 Apache Tinkerpop(使用 Gremlin 查询语言的图形计算框架)。 API for Gremlin 为你提供了一种低摩擦方式来将 Gremlin 与服务结合使用,可通过最少的管理根据需要进行增长和横向扩展。

在本快速入门中,你会使用 Gremlin.Net 库连接到新建的 Azure Cosmos DB for Gremlin 帐户。

库源代码 | 包 (NuGet)

先决条件

Azure Cloud Shell

Azure 托管 Azure Cloud Shell(一个可通过浏览器使用的交互式 shell 环境)。 可以将 Bash 或 PowerShell 与 Cloud Shell 配合使用来使用 Azure 服务。 可以使用 Cloud Shell 预安装的命令来运行本文中的代码,而不必在本地环境中安装任何内容。

若要启动 Azure Cloud Shell,请执行以下操作:

选项 示例/链接
选择代码或命令块右上角的“试用”。 选择“试用”不会自动将代码或命令复制到 Cloud Shell。 显示 Azure Cloud Shell 的“试用”示例的屏幕截图。
转到 https://shell.azure.com 或选择“启动 Cloud Shell”按钮可在浏览器中打开 Cloud Shell。 用于启动 Azure Cloud Shell 的按钮。
选择 Azure 门户右上角菜单栏上的 Cloud Shell 按钮。 显示 Azure 门户中的 Cloud Shell 按钮的屏幕截图

若要使用 Azure Cloud Shell,请执行以下操作:

  1. 启动 Cloud Shell。

  2. 选择代码块(或命令块)上的“复制”按钮以复制代码或命令。

  3. 在 Windows 和 Linux 上选择 Ctrl+Shift+V,或在 macOS 上选择 Cmd+Shift+V 将代码或命令粘贴到 Cloud Shell 会话中。

  4. 选择“Enter”运行代码或命令。

设置

本部分会引导你创建 API for Gremlin 帐户并设置 .NET 项目以使用该库连接到帐户。

创建 API for Gremlin 帐户

在使用 .NET 库之前,应先创建 API for Gremlin 帐户。 此外,建立数据库和图表也很有帮助。

  1. 为 accountName、resourceGroupName 和 location 创建 shell 变量。

    # 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"
    
  2. 如果尚未登录到 Azure CLI,请使用 az login 登录。

  3. 使用 az group create 在订阅中创建新的资源组。

    az group create \
        --name $resourceGroupName \
        --location $location
    
  4. 使用 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 帐户,并且你必须在创建帐户时选择加入使用。 如果此命令无法用于应用免费层折扣的选项,这意味着订阅中的另一个帐户已启用免费层。

  5. 使用 az cosmosdb show 获取帐户的 API for Gremlin 终结点 NAME

    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $accountName \
        --query "name"
    
  6. 使用 az-cosmosdb-keys-list 从帐户的密钥列表中查找 KEY

    az cosmosdb keys list \
        --resource-group $resourceGroupName \
        --name $accountName \
        --type "keys" \
        --query "primaryMasterKey"
    
  7. 记录 NAMEKEY 的值。 稍后会使用这些凭据。

  8. 使用 az cosmosdb gremlin database create 创建名为“cosmicworks”的数据库

    az cosmosdb gremlin database create \
        --resource-group $resourceGroupName \
        --account-name $accountName \
        --name "cosmicworks"
    
  9. 使用 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 控制台应用程序。

  1. 在空文件夹中打开终端。

  2. 使用 dotnet new 命令指定 "console" 模板。

    dotnet new console
    

安装 NuGet 包

Gremlin.NET NuGet 包添加到 .NET 项目。

  1. 使用 dotnet add package 命令指定 Gremlin.Net NuGet 包。

    dotnet add package Gremlin.Net
    
  2. 使用 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)
    

配置环境变量

要使用本快速入门中前面获得的 NAMEURI 值,请将其保存到运行应用程序的本地计算机上的新环境变量。

  1. 要设置环境变量,请使用终端将值分别保留为“COSMOS_ENDPOINT”和“COSMOS_KEY”。

    export COSMOS_GREMLIN_ENDPOINT="<account-name>"
    export COSMOS_GREMLIN_KEY="<account-key>"
    
  2. 验证是否已正确设置环境变量。

    printenv COSMOS_GREMLIN_ENDPOINT
    printenv COSMOS_GREMLIN_KEY
    

代码示例

本文中的代码连接到名为“cosmicworks”的数据库和名为“products”的图形。 然后,代码在遍历添加的项之前,将顶点和边缘添加到图形。

验证客户端

对大多数 Azure 服务的应用程序请求必须获得授权。 对于 API for Gremlin,请使用本快速入门前面获取的名称URI 值。

  1. 打开 Program.cs 文件。

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

  3. Gremlin.Net.Driver 命名空间添加一个 using 块。

    using Gremlin.Net.Driver;
    
  4. 创建 accountNameaccountKey 字符串变量。 将 COSMOS_GREMLIN_ENDPOINTCOSMOS_GREMLIN_KEY 环境变量存储为每个相应变量的值。

    string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
    string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
    
  5. 使用帐户的凭据创建 GremlinServer 的新实例。

    var server = new GremlinServer(
        hostname: $"{accountName}.gremlin.cosmos.azure.com",
        port: 443,
        username: "/dbs/cosmicworks/colls/products",
        password: $"{accountKey}",
        enableSsl: true
    );
    
  6. 使用远程服务器凭据和 GraphSON 2.0 序列化程序创建 GremlinClient 的新实例。

    using var client = new GremlinClient(
        gremlinServer: server,
        messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
    );
    

创建顶点

现在,应用程序已连接到帐户,请使用标准 Gremlin 语法创建顶点。

  1. 使用“SubmitAsync”在 API for Gremlin 帐户的服务器端运行命令。 使用以下属性创建产品顶点:

    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')"
    );
    
  2. 使用以下属性创建第二个产品顶点:

    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')"
    );
    
  3. 使用以下属性创建第三个产品顶点:

    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 语法创建边缘,以定义顶点之间的关系。

  1. 创建从名为“替换”的 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>')

  2. 创建从同一产品到 Bondi Twin Surfboard 的另一个替换边缘。

    await client.SubmitAsync(
        requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518409']))"
    );
    

查询顶点和边缘

使用 Gremlin 语法遍历图形并发现顶点之间的关系。

  1. 遍历图形并查找 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()"
    );
    
  2. 将静态字符串 [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"]}");
    }
    

运行代码

运行应用程序以验证应用程序是否按预期工作。 应用程序执行时应没有错误或警告。 应用程序的输出包括有关创建项和查询项的数据。

  1. 在 .NET 项目文件夹中打开终端。

  2. 使用 dotnet run 运行应用程序。

    dotnet run
    
  3. 观察应用程序的输出。

    [CREATED PRODUCT]       68719518403
    [REPLACES PRODUCT]      68719518371
    [REPLACES PRODUCT]      68719518409
    

清理资源

当不再需要 API for Gremlin 帐户时,删除相应的资源组。

  1. 为 resourceGroupName 创建 shell 变量(如果尚不存在)。

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos-gremlin-quickstart"
    
  2. 使用 az group delete 删除资源组。

    az group delete \
        --name $resourceGroupName
    

下一步