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

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

適用対象: Gremlin

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

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

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

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。
- Azure サブスクリプションがない場合。無料の Azure アカウントにサインアップします。
- Azure サブスクリプションを希望しませんか? Azure Cosmos DB を無料で試すことができます。サブスクリプションは必要ありません。
.NET (LTS)
- .NET がインストールされていませんか。 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 アカウントを作成し、ライブラリを使ってアカウントに接続するように .NET プロジェクトを設定する方法を説明します。

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

.NET ライブラリを使うには、その前に 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
```

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

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

空のフォルダーでターミナルを開きます。
コンソールテンプレート を指定する dotnet new コマンドを使用します。
```
dotnet new console
```

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

Gremlin.NET NuGet パッケージを .NET プロジェクトに追加します。

dotnet add package コマンドを使い、Gremlin.Net NuGet パッケージを指定します。
```
dotnet add package Gremlin.Net
```
dotnet build を使って .NET プロジェクトをビルドします。
```
dotnet build
```
エラーなしでビルドが成功したことを確認します。ビルドからの予想される出力は、次のようになります。
```
Determining projects to restore...
  All projects are up-to-date for restore.
  dslkajfjlksd -> \dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)
```

環境変数を構成する

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

Program.cs ファイルを開きます。
ファイル内に既存のコンテンツがあれば削除します。
Gremlin.Net.Driver 名前空間の using ブロックを追加します。
```
using Gremlin.Net.Driver;
```
文字列変数 accountName と accountKey を作成します。 COSMOS_GREMLIN_ENDPOINT および COSMOS_GREMLIN_KEY 環境変数を、それぞれの変数の値として格納します。
```
string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
```

アカウントの資格情報を使って、GremlinServer の新しいインスタンスを作成します。

var server = new GremlinServer(
    hostname: $"{accountName}.gremlin.cosmos.azure.com",
    port: 443,
    username: "/dbs/cosmicworks/colls/products",
    password: $"{accountKey}",
    enableSsl: true
);

リモートサーバーの資格情報と GraphSON 2.0 シリアライザーを使って、GremlinClient のインスタンスを作成します。

using var client = new GremlinClient(
    gremlinServer: server,
    messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
);

頂点を作成する

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

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

値

label product

id 68719518371

name Kiama classic surfboard

price 285.55

category surfboards
```
await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518371').property('name', 'Kiama classic surfboard').property('price', 285.55).property('category', 'surfboards')"
);
```

次のプロパティを使って、2 つ目の プロダクト 頂点を作成します:

	値
label	`product`
id	`68719518403`
`name`	`Montau Turtle Surfboard`
`price`	`600.00`
`category`	`surfboards`

await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518403').property('name', 'Montau Turtle Surfboard').property('price', 600.00).property('category', 'surfboards')"
);

次のプロパティを使って、3 つ目の プロダクト 頂点を作成します:

	値
label	`product`
id	`68719518409`
`name`	`Bondi Twin Surfboard`
`price`	`585.50`
`category`	`surfboards`

await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518409').property('name', 'Bondi Twin Surfboard').property('price', 585.50).property('category', 'surfboards')"
);

エッジを作成する

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

置換という名前の Montau Turtle Surfboard プロダクトから Kiama classic surfboard プロダクトへのエッジを作成します。
```
await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))"
);
```
ヒント

このエッジの定義では、g.V(['<partition-key>', '<id>']) 構文を使います。または、g.V('<id>').has('category', '<partition-key>') を使用することもできます。

同じプロダクトから Bondi Twin Surfboard に別の置換エッジを作成してください。

await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518409']))"
);

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

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

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

var results = await client.SubmitAsync<Dictionary<string, object>>(
    requestScript: "g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()"
);

固定の文字列 [CREATED PRODUCT]\t68719518403 をコンソールに書き込みます。次に、foreach ループを使って一致した各頂点を反復処理し、[REPLACES PRODUCT] で始まり、一致した製品の id フィールドをサフィックスとして含むメッセージを、コンソールに書き込みます。
```
Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
{
    Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
}
```

コードの実行

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

.NET プロジェクトフォルダーでターミナルを開きます。
dotnet run を使ってアプリケーションを実行します。
```
dotnet run
```

アプリケーションからの出力を確認します。

[CREATED PRODUCT]       68719518403
[REPLACES PRODUCT]      68719518371
[REPLACES PRODUCT]      68719518409

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

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

次の方法で共有

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

前提条件

Azure Cloud Shell

設定

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

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

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

環境変数を構成する

コード例

クライアントを認証する

頂点を作成する

エッジを作成する

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

コードの実行

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

次のステップ

フィードバック

その他のリソース

	値
label	`product`
id	`68719518371`
`name`	`Kiama classic surfboard`
`price`	`285.55`
`category`	`surfboards`

次の方法で共有

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

前提条件

Azure Cloud Shell

設定

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

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

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

環境変数を構成する

コード例

クライアントを認証する

頂点を作成する

エッジを作成する

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

コードの実行

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

次のステップ

フィードバック

その他のリソース

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

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