クイックスタート: Python 用 Azure Cosmos DB for Apache Gremlin ライブラリ

[アーティクル]
08/15/2024

適用対象: Gremlin

Azure Cosmos DB for Apache Gremlin は、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 では、ブラウザーを介して使用できる対話型のシェル環境、Azure Cloud Shell がホストされています。 Cloud Shell で Bash または PowerShell を使用して、Azure サービスを操作できます。ローカル環境に何もインストールしなくても、Cloud Shell にプレインストールされているコマンドを使用して、この記事のコードを実行できます。

Azure Cloud Shell を開始するには、以下のようにします。

オプション	例とリンク
コードまたはコマンドブロックの右上隅にある [使ってみる] を選択します。 [使ってみる] を選択しても、コードまたはコマンドは Cloud Shell に自動的にはコピーされません。
https://shell.azure.com に移動するか、[Cloud Shell を起動する] ボタンを選択して、ブラウザーで Cloud Shell を開きます。
Azure portal の右上にあるメニューバーの [Cloud Shell] ボタンを選択します。

Azure Cloud Shell を使用するには、以下のようにします。

Cloud Shell を開始します。
コードブロック (またはコマンドブロック) の [コピー] ボタンを選択し、コードまたはコマンドをコピーします。
Windows と Linux では Ctrl+Shift+V キーを選択し、macOS では Cmd+Shift+V キーを選択して、コードまたはコマンドを Cloud Shell セッションに貼り付けます。
Enter キーを選択して、コードまたはコマンドを実行します。

設定

このセクションでは、Gremlin 用 API アカウントを作成し、ライブラリを使ってアカウントに接続するように Python プロジェクトを設定する手順について説明します。

Gremlin 用 API アカウントを作成する

Gremlin 用 API アカウントは、Python ライブラリを使う前に作成する必要があります。さらに、これはデータベースとグラフの設定にも役立ちます。

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

Azure サブスクリプションにつき所有できる Free レベルの Azure Cosmos DB アカウントは 1 つまでです。また、アカウントの作成時にオプトインする必要があります。このコマンドで無料レベル割引を適用できない場合は、サブスクリプション内の別のアカウントが無料枠で既に有効になっていることを意味します。
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 の場合は、このクイックスタートで前に取得した "名前" と 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"]
```

アカウントの資格情報と GraphSON 2.0 シリアライザーを使って接続するには、Client を使ってください。

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

次のプロパティを使って、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 構文を使用してエッジを作成し、頂点間のリレーションシップを定義します。

置換という名前の 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
```

次のステップ

Azure Cosmos DB for Apache Gremlin を使用してデータを作成してクエリを実行する

次の方法で共有

クイックスタート: Python 用 Azure Cosmos DB for Apache Gremlin ライブラリ

前提条件

Azure Cloud Shell

設定

Gremlin 用 API アカウントを作成する

新しい Python コンソールアプリケーションを作成します

PyPI パッケージをインストールする

環境変数を構成する

コード例

クライアントを認証する

頂点を作成する

エッジを作成する

頂点とエッジのクエリを実行する

コードの実行

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

次の方法で共有

クイック スタート: Python 用 Azure Cosmos DB for Apache Gremlin ライブラリ

前提条件

Azure Cloud Shell

設定

Gremlin 用 API アカウントを作成する

新しい Python コンソール アプリケーションを作成します

PyPI パッケージをインストールする

環境変数を構成する

コード例

クライアントを認証する

頂点を作成する

エッジを作成する

頂点とエッジのクエリを実行する

コードの実行

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

クイックスタート: Python 用 Azure Cosmos DB for Apache Gremlin ライブラリ

新しい Python コンソールアプリケーションを作成します