クイック スタート: Node.js 用の Azure Cosmos DB for Apache Gremlin ライブラリ

  • [アーティクル]

適用対象: Gremlin

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

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

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

前提条件

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 を作成し、ライブラリを使用してアカウントに接続するように Node.js プロジェクトを設定する手順について説明します。

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

Node.js ライブラリを使用する前に、Gremlin アカウント用の API を作成する必要があります。 さらに、データベースとグラフを配置するのにも役立ちます。

  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

新しい Node.js コンソール アプリケーションを作成する

任意のターミナルを使用して、空のフォルダーに Node.js コンソール アプリケーションを作成します。

  1. 空のフォルダーでターミナルを開いてください。

  2. 新しいモジュールを初期化する

    npm init es6 --yes

  3. app.js ファイルを作成する

    touch app.js

npm パッケージのインストール

gremlin npm パッケージを Node.js プロジェクトに追加します。

  1. package.json ファイルを開き、内容をこの JSON 構成に置き換えます。

    {
  "main": "app.js",
  "type": "module",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "gremlin": "^3.*"
  }
}

  2. npm install コマンドを使用して、package.json ファイルで指定されたすべてのパッケージをインストールしてください。

    npm install

環境変数を構成する

このクイックスタートで、先ほど取得した 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 の場合は、このクイックスタートで先ほど取得した NAME と URI の値を使用します。

  1. app.js ファイルを開いてください。

  2. gremlin モジュールをインポートします。

    import gremlin from 'gremlin'

  3. accountName 変数と accountKey 変数を作成します。 各変数の値として、 COSMOS_GREMLIN_ENDPOINT と COSMOS_GREMLIN_KEY 環境変数を格納します。

    const accountName = process.env.COSMOS_GREMLIN_ENDPOINT
const accountKey = process.env.COSMOS_GREMLIN_KEY

  4. PlainTextSaslAuthenticator を使用して、アカウントの資格情報の新しいオブジェクトを作成します。

    const credentials = new gremlin.driver.auth.PlainTextSaslAuthenticator(
  '/dbs/cosmicworks/colls/products',
  `${accountKey}`
)

  5. Client を使用して、リモート サーバーの資格情報と GraphSON 2.0 シリアライザーを使用して接続します。 次に、Open を使用してサーバーへの新しい接続を作成してください。

    const client = new gremlin.driver.Client(
  `wss://${accountName}.gremlin.cosmos.azure.com:443/`,
  {
    credentials,
    traversalsource: 'g',
    rejectUnauthorized: true,
    mimeType: 'application/vnd.gremlin-v2.0+json'
  }
)

client.open()

頂点を作成する

アプリケーションがアカウントに接続されたので、標準の Gremlin 構文を使用して頂点を作成します。

  1. submit を使って、サーバー側の Gremlin 用 API アカウントでコマンドを実行します。 次のプロパティを使って、プロダクト 頂点を作成します:

    値
    label product
    id 68719518371
    name Kiama classic surfboard
    price 285.55
    category surfboards 
    await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    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 
    await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    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 
    await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518409',
    prop_name: 'Bondi Twin Surfboard',
    prop_price: 585.50,
    prop_partition_key: 'surfboards'
  }
)

エッジを作成する

Gremlin 構文を使用してエッジを作成し、頂点間のリレーションシップを定義します。

  1. 置換 という名前の Montau Turtle Surfboard プロダクトから Kiama classic surfboard プロダクトへのエッジを作成します。

    await client.submit(
  'g.V([prop_partition_key, prop_source_id]).addE(\'replaces\').to(g.V([prop_partition_key, prop_target_id]))', {
    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 に別の 置換 エッジを作成してください。

    await client.submit(
  'g.V([prop_partition_key, prop_source_id]).addE(\'replaces\').to(g.V([prop_partition_key, prop_target_id]))', {
    prop_partition_key: 'surfboards',
    prop_source_id: '68719518403',
    prop_target_id: '68719518409'
  }
)

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

グラフを走査し、頂点間のリレーションシップを検出するには、Gremlin 構文を使用します。

  1. グラフを走査し、Montau Turtle Surfboard が置換するすべての頂点を見つけます。

    const result = await client.submit(
  'g.V().hasLabel(\'product\').has(\'category\', prop_partition_key).has(\'name\', prop_name).outE(\'replaces\').inV()', {
    prop_partition_key: 'surfboards',
    prop_name: 'Montau Turtle Surfboard'
  }
)

  2. この走査の結果をコンソールに書き込んでください。

    console.dir(result)

コードの実行

アプリケーションを実行して、アプリケーションが期待どおりに動作することを検証します。 アプリケーションは、エラーや警告なしで実行する必要があります。 アプリケーションの出力には、作成された項目とクエリされた項目に関するデータが含まれます。

  1. Node.js プロジェクト フォルダー内のターミナルを開きます。

  2. npm <script> を使用してアプリケーションを実行してください。 アプリケーションからの出力を確認します。

    npm start

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

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 を使用してデータを作成してクエリを実行する