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

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

適用対象: Gremlin

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

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

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

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。
- Azure サブスクリプションがない場合。無料の Azure アカウントにサインアップします。
- Azure サブスクリプションを希望しませんか? サブスクリプションは不要で、Azure Cosmos DB を無料で試すことができます。
Node.js (LTS)
- Node.js がインストールされていませんか? このクイックスタートを GitHub Codespaces.codespaces.new/github/codespaces-blank?quickstart=1) でお試しください
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 を作成し、ライブラリを使用してアカウントに接続するように Node.js プロジェクトを設定する手順について説明します。

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

Node.js ライブラリを使用する前に、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
```
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
```

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

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

空のフォルダーでターミナルを開いてください。
新しいモジュールを初期化する
```
npm init es6 --yes
```
app.js ファイルを作成する
```
touch app.js
```

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

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

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

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

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

環境変数を構成する

このクイックスタートで、先ほど取得した 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.js ファイルを開いてください。
gremlin モジュールをインポートします。
```
import gremlin from 'gremlin'
```
accountName 変数と accountKey 変数を作成します。各変数の値として、 COSMOS_GREMLIN_ENDPOINT と COSMOS_GREMLIN_KEY 環境変数を格納します。
```
const accountName = process.env.COSMOS_GREMLIN_ENDPOINT
const accountKey = process.env.COSMOS_GREMLIN_KEY
```

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

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

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 構文を使用して頂点を作成します。

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 つ目の プロダクト 頂点を作成します:

	値
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 つ目の プロダクト 頂点を作成します:

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

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

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

グラフを走査し、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'
  }
)

この走査の結果をコンソールに書き込んでください。
```
console.dir(result)
```

コードの実行

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

Node.js プロジェクトフォルダー内のターミナルを開きます。
npm <script> を使用してアプリケーションを実行してください。アプリケーションからの出力を確認します。
```
npm start
```

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

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

次の方法で共有

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

前提条件

Azure Cloud Shell

設定

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

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

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

環境変数を構成する

コード例

クライアントを認証する

頂点を作成する

エッジを作成する

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

コードの実行

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

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

前提条件

Azure Cloud Shell

設定

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

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

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

環境変数を構成する

コード例

クライアントを認証する

頂点を作成する

エッジを作成する

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

コードの実行

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

次のステップ

フィードバック

その他のリソース

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

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