クイック スタート: 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 に自動的にはコピーされません。 Azure Cloud Shell の [使ってみる] の例を示すスクリーンショット。
https://shell.azure.com に移動するか、[Cloud Shell を起動する] ボタンを選択して、ブラウザーで Cloud Shell を開きます。 Azure Cloud Shell を起動するボタン。
Azure portal の右上にあるメニュー バーの [Cloud Shell] ボタンを選択します。 Azure portal の [Cloud Shell] ボタンを示すスクリーンショット

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. accountNameresourceGroupName、および 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. NAMEKEY 値 を記録します。 これらの資格情報は後で使用します。

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

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

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

    import gremlin from 'gremlin'
    
  3. accountName 変数と accountKey 変数を作成します。 各変数の値として、 COSMOS_GREMLIN_ENDPOINTCOSMOS_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
    

次のステップ