共用方式為


快速入門:適用於 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 Cloud Shell 是裝載於 Azure 中的互動式殼層環境,可在瀏覽器中使用。 您可以使用 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 帳戶,並設定 Python 專案以使用程式庫連線至該帳戶。

建立 API for Gremlin 帳戶

使用 Python 程式庫之前,請先建立 API for Gremlin 帳戶。 此外,該帳戶還有助於建立資料庫和圖形。

  1. 建立 accountNameresourceGroupNamelocation 的殼層變數。

    # 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. 如果您尚未登入,請使用 az login 登入 Azure CLI。

  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_ENDPOINTCOSMOS_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,請使用本快速入門前面所取得的 NAMEURI 值。

  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 帳戶上執行伺服器端命令。 建立具有以下屬性的 product 頂點:

    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. 建立具有下列屬性的第二個 product 頂點:

    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. 建立具有下列屬性的第三個 product 頂點:

    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 產品且名為 replaces 的邊緣。

    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 的另一個 replaces 邊緣。

    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 不存在,請建立其殼層變數。

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos-gremlin-quickstart"
    
  2. 使用 az group delete 來刪除資源群組。

    az group delete \
        --name $resourceGroupName
    

後續步驟