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

  • [アーティクル]

適用対象: Gremlin

Azure Cosmos DB for Apache Gremlin は、Gremlin クエリ言語を使用するグラフ コンピューティング フレームワークである一般的な Apache Tinkerpop を実装したフル マネージドのグラフ データベース サービスです。 Gremlin 用 API を使うと、最小限の管理で必要に応じて拡張したり、スケールアウトしたりできるサービスにより、それほど抵抗なく Gremlin を使い始めることができます。

このクイックスタートでは、gremlinpython ライブラリを使って、新しく作成された Azure Cosmos DB for Gremlin アカウントに接続します。

ライブラリのソース コード | パッケージ (PyPi)

前提条件

Azure Cloud Shell

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

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

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

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

  1. Cloud Shell を開始します。

  2. コード ブロック (またはコマンド ブロック) の [コピー] ボタンを選択し、コードまたはコマンドをコピーします。

  3. Windows と Linux では Ctrl+Shift+V キーを選択し、macOS では Cmd+Shift+V キーを選択して、コードまたはコマンドを Cloud Shell セッションに貼り付けます。

  4. Enter キーを選択して、コードまたはコマンドを実行します。

設定

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

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

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

  1. 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"

  2. まだサインインしていない場合は、 az login を使用して Azure CLI にサインインします。

  3. az group create を使って、サブスクリプションに新しいリソース グループを作成します。

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

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

  5. az cosmosdb showを使用して、アカウントに対する Gremlin 用 API エンドポイントの名前 を取得します。

    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. NAME と KEY 値 を記録します。 これらの資格情報は後で使用します。

  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. gremlinpython Python パッケージ インデックスから要件ファイルにパッケージを追加します。

    gremlinpython==3.7.0

  3. すべての要件をプロジェクトにインストールします。

    python install -r requirements.txt

環境変数を構成する

このクイックスタートで、先ほど取得した NAME および URI の値を使用するには、アプリケーションを実行しているローカル コンピューター上の新しい環境変数にそれらを永続化します。

  1. 環境変数を設定するには、ターミナルを使って値をそれぞれ COSMOS_ENDPOINT および COSMOS_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 サービスに対するアプリケーション要求は、承認される必要があります。 Gremlin 用 API の場合は、このクイックスタートで前に取得した "名前" と URI の値を使います。

  1. app.py ファイルを開きます。

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

  3. ACCOUNT_NAME および ACCOUNT_KEY 変数を作成します。 COSMOS_GREMLIN_ENDPOINT および COSMOS_GREMLIN_KEY 環境変数を、それぞれの変数の値として格納します。

    ACCOUNT_NAME = os.environ["COSMOS_GREMLIN_ENDPOINT"]
ACCOUNT_KEY = os.environ["COSMOS_GREMLIN_KEY"]

  4. アカウントの資格情報と 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 構文を使用して頂点を作成します。

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

  1. 置換 という名前の 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>') を使用することもできます。

  2. 同じプロダクトから 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 構文を使用します。

  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

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

Gremlin 用 API アカウントが必要なくなったら、対応するリソース グループを削除します。

  1. resourceGroupName のシェル変数がまだ存在しない場合は作成します。

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

  2. az group delete を使ってリソース グループを削除します。

    az group delete \
    --name $resourceGroupName

次のステップ

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