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

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

适用对象: Gremlin

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

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

库源代码 | 包 (PyPi)

先决条件

Azure Cloud Shell

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

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

选项 示例/链接
选择代码或命令块右上角的“试用”。 选择“试用”不会自动将代码或命令复制到 Cloud Shell。 Screenshot that shows an example of Try It for Azure Cloud Shell.
转到 https://shell.azure.com 或选择启动 Cloud Shell 按钮可在浏览器中打开 Cloud Shell。 Button to launch Azure Cloud Shell.
选择 Azure 门户右上角菜单栏上的 Cloud Shell 按钮。 Screenshot that shows the Cloud Shell button in the Azure portal

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

  1. 启动 Cloud Shell。

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

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

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

设置

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

创建 API for Gremlin 帐户

在使用 Python 库之前,应先创建 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
    

创建一个新的 Python 控制台应用程序

使用首选终端在空文件夹中创建一个 Python 控制台应用程序。

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

  2. 创建 app.py 文件。

    touch app.py
    

安装 PyPI 包

gremlinpython PyPI 包添加到 Python 项目。

  1. 创建 requirements.txt 文件。

    touch requirements.txt
    
  2. 将 Python 包索引中的 gremlinpython 包添加到要求文件。

    gremlinpython==3.7.0
    
  3. 为项目安装所有要求。

    python install -r requirements.txt
    

配置环境变量

要使用本快速入门中前面获得的 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. 打开 app.py 文件。

  2. gremlin_python.driver 模块导入 clientserializer

    import os
    from gremlin_python.driver import client, serializer
    

    警告

    根据 Python 的版本,可能还需要导入 asyncio 并替代事件循环策略:

    import asyncio
    import sys
    
    if sys.platform == "win32":
        asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
    
  3. 创建 ACCOUNT_NAMEACCOUNT_KEY 变量。 将 COSMOS_GREMLIN_ENDPOINTCOSMOS_GREMLIN_KEY 环境变量存储为每个相应变量的值。

    ACCOUNT_NAME = os.environ["COSMOS_GREMLIN_ENDPOINT"]
    ACCOUNT_KEY = os.environ["COSMOS_GREMLIN_KEY"]
    
  4. 使用 Client 通过帐户的凭据和 GraphSON 2.0 序列化程序进行连接。

    client = client.Client(
        url=f"wss://{ACCOUNT_NAME}.gremlin.cosmos.azure.com:443/",
        traversal_source="g",
        username="/dbs/cosmicworks/colls/products",
        password=f"{ACCOUNT_KEY}",
        message_serializer=serializer.GraphSONSerializersV2d0(),
    )
    

创建顶点

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

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

    label product
    id 68719518371
    name Kiama classic surfboard
    price 285.55
    category surfboards
    client.submit(
        message=(
            "g.addV('product')"
            ".property('id', prop_id)"
            ".property('name', prop_name)"
            ".property('price', prop_price)"
            ".property('category', prop_partition_key)"
        ),
        bindings={
            "prop_id": "68719518371",
            "prop_name": "Kiama classic surfboard",
            "prop_price": 285.55,
            "prop_partition_key": "surfboards",
        },
    )
    
  2. 使用以下属性创建第二个产品顶点:

    label product
    id 68719518403
    name Montau Turtle Surfboard
    price 600.00
    category surfboards
    client.submit(
        message=(
            "g.addV('product')"
            ".property('id', prop_id)"
            ".property('name', prop_name)"
            ".property('price', prop_price)"
            ".property('category', prop_partition_key)"
        ),
        bindings={
            "prop_id": "68719518403",
            "prop_name": "Montau Turtle Surfboard",
            "prop_price": 600.00,
            "prop_partition_key": "surfboards",
        },
    )
    
  3. 使用以下属性创建第三个产品顶点:

    label product
    id 68719518409
    name Bondi Twin Surfboard
    price 585.50
    category surfboards
    client.submit(
        message=(
            "g.addV('product')"
            ".property('id', prop_id)"
            ".property('name', prop_name)"
            ".property('price', prop_price)"
            ".property('category', prop_partition_key)"
        ),
        bindings={
            "prop_id": "68719518409",
            "prop_name": "Bondi Twin Surfboard",
            "prop_price": 585.50,
            "prop_partition_key": "surfboards",
        },
    )
    

创建边缘

使用 Gremlin 语法创建边缘,以定义顶点之间的关系。

  1. 创建从名为“替换”的 Montau Turtle Surfboard 产品到 Kiama classic surfboard 产品的边缘。

    client.submit(
        message=(
            "g.V([prop_partition_key, prop_source_id])"
            ".addE('replaces')"
            ".to(g.V([prop_partition_key, prop_target_id]))"
        ),
        bindings={
            "prop_partition_key": "surfboards",
            "prop_source_id": "68719518403",
            "prop_target_id": "68719518371",
        },
    )
    

    提示

    此边缘定义使用 g.V(['<partition-key>', '<id>']) 语法。 或者,也可使用 g.V('<id>').has('category', '<partition-key>')

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

    client.submit(
        message=(
            "g.V([prop_partition_key, prop_source_id])"
            ".addE('replaces')"
            ".to(g.V([prop_partition_key, prop_target_id]))"
        ),
        bindings={
            "prop_partition_key": "surfboards",
            "prop_source_id": "68719518403",
            "prop_target_id": "68719518409",
        },
    )
    

查询顶点和边缘

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

  1. 遍历图形并查找 Montau Turtle Surfboard 替换的所有顶点。

    result = client.submit(
        message=(
            "g.V().hasLabel('product')"
            ".has('category', prop_partition_key)"
            ".has('name', prop_name)"
            ".outE('replaces').inV()"
        ),
        bindings={
            "prop_partition_key": "surfboards",
            "prop_name": "Montau Turtle Surfboard",
        },
    )
    
  2. 将此遍历的结果写入控制台。

    print(result)
    

运行代码

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

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

  2. 使用 python <filename> 运行应用程序。 观察应用程序的输出。

    python app.py
    

清理资源

当不再需要 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
    

下一步