快速入門：適用於 Python 的適用於 Apache Gremlin 的 Azure Cosmos DB 連結庫

發行項
03/10/2024

適用於： Gremlin

適用於 Apache Gremlin 的 Azure Cosmos DB 是完全受控的圖形資料庫服務，使用 Gremlin 查詢語言實作熱門 Apache Tinkerpop的圖表運算架構。 Gremlin 的 API 可讓您以低摩擦的方式開始使用 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 鍵執行程式碼或命令。

設定

本節將逐步引導您建立 Gremlin 帳戶的 API，以及設定 Python 專案以使用連結庫來連線到帳戶。

建立 Gremlin 帳戶的 API

使用 Python 連結庫之前，應該先建立 Gremlin 帳戶的 API。此外，它也有助於建立資料庫和圖形。

建立 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 建立具有預設設定之 Gremlin 帳戶的新 API。
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
注意

每個 Azure 訂用帳戶最多可以有一個免費層 Azure Cosmos DB 帳戶，而且在建立帳戶時必須選擇加入。如果此命令無法套用免費層折扣，這表示訂用帳戶中的另一個帳戶已啟用免費層。

使用 az cosmosdb show取得帳戶的 Gremlin 端點名稱 API。

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
```
gremlinpython將套件從 Python 套件索引新增至需求檔案。
```
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 服務的應用程式要求都必須獲得授權。針對 Gremlin 的 API，請使用 本快速入門稍早取得的 NAME 和 URI 值。

開啟 app.py 檔案。

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

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 在 Gremlin 帳戶的 API 上執行命令伺服器端。使用下列屬性建立產品頂點：

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

使用下列屬性建立第二 個產品 頂點：

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

使用下列屬性建立第三 個產品 頂點：

	值
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產品。

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。

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
```

清除資源

當您不再需要 Gremlin 帳戶的 API 時，請刪除對應的資源群組。

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

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

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

az group delete \
    --name $resourceGroupName

後續步驟

使用適用於 Apache Gremlin 的 Azure Cosmos DB 建立和查詢數據