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

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

库源代码 | 包 (PyPi)

Prerequisites

• Azure 订阅服务

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

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

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

• Python 3.12 或更高版本

设置

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

创建帐户

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

获取凭据

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

准备开发环境

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

1. 从空文件夹开始。

2. 从 Python 包索引（PyPI）导入gremlinpython包。

   pip install gremlinpython
   

3. 创建 app.py 文件。

对象模型

代码示例

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

对客户端进行身份验证

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

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

2. 从 gremlin_python.driver 库导入以下类型：

   • gremlin_python.driver.client
   • gremlin_python.driver.serializer

   from gremlin_python.driver import client, serializer
   

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

   hostname = "<host>"
   primary_key = "<key>"
   

4. Client使用在前面的步骤中创建的凭据和配置变量创建对象。 为变量 client 命名。

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

插入数据

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

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

   client.submit("g.V().drop()").all().result()
   

2. 创建添加顶点的 Gremlin 查询。

   insert_vertex_query = (
       "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. 为单个产品添加顶点。

   client.submit(
       message=insert_vertex_query,
       bindings={
           "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,
       },
   ).all().result()
   

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

   client.submit(
       message=insert_vertex_query,
       bindings={
           "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,
       },
   ).all().result()
   
   client.submit(
       message=insert_vertex_query,
       bindings={
           "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,
       },
   ).all().result()
   

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

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

6. 添加两个边缘。

   client.submit(
       message=insert_edge_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_target_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       },
   ).all().result()
   
   client.submit(
       message=insert_edge_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_source_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
           "prop_target_id": "cccccccc-2222-3333-4444-dddddddddddd",
       },
   ).all().result()
   

读取数据

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

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

   read_vertex_query = "g.V([prop_partition_key, prop_id])"
   

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

   matched_item = client.submit(
       message=read_vertex_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
       }
   ).one()
   

查询数据

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

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

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

2. 执行指定 Montau Turtle Surfboard 产品的查询。

   find_results = client.submit(
       message=find_vertices_query,
       bindings={
           "prop_partition_key": "gear-surf-surfboards",
           "prop_name": "Montau Turtle Surfboard",
       },
   ).all().result()
   

3. 迭代遍历查询结果。

   for result in find_results:
       # Do something here with each result
   

运行代码

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

python app.py

清理资源

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

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

后续步骤