快速入門：適用於 Python 的 Azure Cosmos DB for Apache Gremlin 程式庫

發行項
08/15/2024

適用於： Gremlin

Azure Cosmos DB for Apache Gremlin 是一項完全受控的圖形資料庫服務，會實作熱門的 Apache Tinkerpop (這是一種使用 Gremlin 查詢語言的圖形運算架構)。 API for Gremlin 讓使用 Gremlin 更為平順，該服務可根據您的需求以最少的管理方式進行拓展與擴增。

在本快速入門中，您將使用 gremlinpython 程式庫連線至新建立的 Azure Cosmos DB for Gremlin 帳戶。

程式庫原始程式碼 | 套件 (PyPi)

必要條件

具有有效訂用帳戶的 Azure 帳戶。
- 沒有 Azure 訂閱嗎？註冊免費 Azure 帳戶。
- 不想要 Azure 訂用帳戶？您不妨免費試用 Azure Cosmos DB，而不需要訂用帳戶。
Python (最新版本)
- 未安裝 Python？請在 GitHub Codespaces 中試用本快速入門。
Azure 命令列介面 (CLI)

Azure Cloud Shell

Azure Cloud Shell 是裝載於 Azure 中的互動式殼層環境，可在瀏覽器中使用。您可以使用 Bash 或 PowerShell 搭配 Cloud Shell，與 Azure 服務共同使用。您可以使用 Cloud Shell 預先安裝的命令，執行本文提到的程式碼，而不必在本機環境上安裝任何工具。

要啟動 Azure Cloud Shell：

選項	範例/連結
選取程式碼或命令區塊右上角的 [試試看]。選取 [試試看] 並不會自動將程式碼或命令複製到 Cloud Shell 中。
請前往 https://shell.azure.com，或選取 [啟動 Cloud Shell] 按鈕，在瀏覽器中開啟 Cloud Shell。
選取 Azure 入口網站右上方功能表列上的 [Cloud Shell] 按鈕。

若要使用 Azure Cloud Shell：

啟動 Cloud Shell。
選取程式碼區塊 (或命令區塊) 上的 [複製] 按鈕以複製程式碼或命令。
透過在 Windows 和 Linux 上選取 Ctrl+Shift+V；或在 macOS 上選取 Cmd+Shift+V，將程式碼或命令貼到 Cloud Shell 工作階段中。
選取 Enter 鍵執行程式碼或命令。

設定

本節將逐步引導您建立 API for Gremlin 帳戶，並設定 Python 專案以使用程式庫連線至該帳戶。

建立 API for Gremlin 帳戶

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

建立 accountName、resourceGroupName 和 location 的殼層變數。

# 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"

如果您尚未登入，請使用 az login 登入 Azure CLI。

使用 az group create 在您的訂用帳戶中建立新的資源群組。

az group create \
    --name $resourceGroupName \
    --location $location

使用 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 帳戶，而且必須在建立帳戶時選擇加入。如果該命令無法套用免費階層折扣，這表示訂用帳戶中的另一個帳戶已啟用免費階層。

使用 az cosmosdb show 取得該帳戶的 API for Gremlin 端點 NAME。

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "name"

使用 az-cosmosdb-keys-list 在帳戶的金鑰清單中尋找 KEY。

az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

記下 NAME 和 KEY 值。稍後將使用這些認證。

使用 az cosmosdb gremlin database create 建立名為 cosmicworks 的資料庫。

az cosmosdb gremlin database create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --name "cosmicworks"

使用 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 主控台應用程式。

在空資料夾中開啟終端機。
建立 app.py 檔案。
```
touch app.py
```

安裝 PyPI 套件

將 gremlinpython PyPI 套件新增至 Python 專案。

建立 requirements.txt 檔案。
```
touch requirements.txt
```
將 Python 套件索引中的 gremlinpython 套件新增至需求檔案。
```
gremlinpython==3.7.0
```
將所有需求安裝至專案中。
```
python install -r requirements.txt
```

設定環境變數

若要使用本快速入門前面所取得的 NAME 和 URI 值，請將這些值保存在執行應用程式的本機電腦上的新環境變數中。

若要設定環境變數，請使用終端機將值分別保存為 COSMOS_ENDPOINT 和 COSMOS_KEY。
```
export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"
```

驗證環境變數已正確設定。

printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY

本文中的程式代碼會連線至名為 cosmicworks 的資料庫，以及名為 products 的圖形。然後，程式碼會在遍訪新增項目之前，將頂點和邊緣新增至圖形中。

驗證用戶端

大部分 Azure 服務的應用程式要求都必須獲得授權。若為 API for Gremlin，請使用本快速入門前面所取得的 NAME 和 URI 值。

開啟 app.py 檔案。

從 gremlin_python.driver 模組匯入 client 和 serializer。

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())

建立 ACCOUNT_NAME 和 ACCOUNT_KEY 變數。將 COSMOS_GREMLIN_ENDPOINT 和 COSMOS_GREMLIN_KEY 環境變數儲存為每個個別變數的值。
```
ACCOUNT_NAME = os.environ["COSMOS_GREMLIN_ENDPOINT"]
ACCOUNT_KEY = os.environ["COSMOS_GREMLIN_KEY"]
```

使用 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 語法來建立頂點。

使用 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",
    },
)

建立具有下列屬性的第二個 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",
    },
)

建立具有下列屬性的第三個 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 語法建立邊緣，以定義頂點之間的關聯性。

建立從 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>')。

建立從相同產品到 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 語法周遊圖形，並探索頂點之間的關聯性。

周遊圖形並尋找所有被 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",
    },
)

將此遍訪結果寫入主控台。
```
print(result)
```

執行程式碼

透過執行應用程式來驗證您的應用程式是否如預期運作。應用程式執行時應該沒有任何錯誤或警告。應用程式的輸出包含已建立和已查詢項目的相關資料。

在 Python 專案資料夾中開啟終端機。
使用 python <filename> 執行應用程式。觀察應用程式的輸出。
```
python app.py
```

清除資源

如果不再需要 API for Gremlin 帳戶，請刪除對應的資源群組。

如果 resourceGroupName 不存在，請建立其殼層變數。

# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"

使用 az group delete 來刪除資源群組。

az group delete \
    --name $resourceGroupName

後續步驟

使用 Azure Cosmos DB for Apache Gremlin 建立和查詢資料

共用方式為