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

適用対象: ✅ Apache Gremlin

Important

99.999% 可用性サービスレベルアグリーメント (SLA)、インスタント自動スケール、および複数のリージョン間の自動フェールオーバーを使用した 大規模 なシナリオ向けのデータベースソリューションをお探しですか? Azure Cosmos DB for NoSQL について考えてみましょう。

オンライン分析処理 (OLAP) グラフを実装するか、既存の Apache Gremlin アプリケーションを移行しますか? Microsoft Fabric で Graph を検討してください。

.NET 用 Azure Cosmos DB for Apache Gremlin クライアントライブラリを使用して、非構造化データの格納、管理、クエリを実行します。このガイドの手順に従って、新しいアカウントの作成、.NET クライアントライブラリのインストール、アカウントへの接続、一般的な操作の実行、最終的なサンプルデータのクエリを実行します。

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

前提条件

Azure サブスクリプション
- Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。

Azure Cloud Shell の Azure CLI の最新バージョン。
- CLI 参照コマンドをローカルで実行する場合は、 az login コマンドを使用して Azure CLI にサインインします。

.NET SDK 9.0 以降

設定

まず、このガイドのアカウントと開発環境を設定します。このセクションでは、アカウントの作成、資格情報の取得、開発環境の準備のプロセスについて説明します。

アカウントを作成する

まず、Apache Gremlin アカウント用の API を作成します。アカウントが作成されたら、データベースとグラフリソースを作成します。

Azure CLI
Azure Portal

ターゲットリソースグループがまだない場合は、 az group create コマンドを使用して、サブスクリプションに新しいリソースグループを作成します。
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

az cosmosdb create コマンドを使用して、既定の設定で新しい Azure Cosmos DB for Apache Gremlin アカウントを作成します。

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableGremlin"

az cosmosdb gremlin database createという名前のcosmicworksを使用して、新しいデータベースを作成します。

az cosmosdb gremlin database create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

az cosmosdb gremlin graph create コマンドを使用して、productsという名前の新しいグラフを作成します。

az cosmosdb gremlin graph create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category"

Azure portal (https://portal.azure.com) にサインインします。
グローバル検索バーに 「Azure Cosmos DB 」と入力します。
サービス内で、Azure Cosmos DB を選択します。
Azure Cosmos DB ペインで、[作成] を選択し、[その他] タブで Azure Cosmos DB for Apache Gremlin を選択します。

[基本情報] ウィンドウで、次のオプションを構成し、[レビュー + 作成] を選択します。

	値
ワークロードの種類	学習
サブスクリプション	Azure サブスクリプションを選択する
リソースグループ	新しいリソースグループを作成するか、既存のリソースグループを選択
アカウント名	グローバルに一意の名前を指定
アベイラビリティゾーン	無効にする
場所	サブスクリプションでサポートされている Azure リージョンを選択

ヒント

指定されていないオプションは、既定値のままでかまいません。アカウントの合計スループットを 1 秒あたり 1,000 要求ユニット (RU/秒) に制限するようにアカウントを構成したり、Free レベルを有効にしてコストを最小限に抑えたりすることもできます。

[レビュー + 作成] ウィンドウで、アカウントの検証が正常に完了するまで待ってから、[作成] を選択します。
Portal は自動的に [展開] ウィンドウに移動します。デプロイが完了するまで待ちます。
デプロイが完了したら、[ リソースに移動 ] を選択して、Apache Gremlin 用の新しい API アカウントに移動します。
リソースメニューで、[ データエクスプローラー ] オプションを選択します。
データエクスプローラーで、[ + 新しいグラフ] を選択します。

[ グラフの追加 ] ダイアログで、次のオプションを構成し、[ OK] を選択します。

	値
データベース	新規作成
データベース名	`cosmicworks`
グラフ名	`products`
パーティションキー	`/category`

ヒント

指定されていないオプションは、既定値のままでかまいません。

資格情報の取得

ここで、最近作成したアカウントへの接続を作成するために使用するクライアントライブラリのパスワードを取得します。

Azure CLI
Azure Portal

az cosmosdb showを使用して、アカウントのホストを取得します。

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{host:name}"

前のコマンドの出力の host プロパティの値を記録します。このプロパティの値は、このガイドの後半でライブラリを使用してアカウントに接続するために使用する ホスト です。

az cosmosdb keys listを使用して、アカウントのキーを取得します。

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

前のコマンドの出力の primaryMasterKey プロパティの値を記録します。このプロパティの値は、ライブラリを使用してアカウントに接続するために、このガイドの後半で使用するキーです。

開発環境の準備

次に、新しいプロジェクトとクライアントライブラリを使用して開発環境を構成します。この手順は、このガイドの残りの部分に進む前に必要な最後の前提条件です。

空のフォルダーから開始します。
新しい .NET コンソールアプリケーションを作成する
```
dotnet new console
```
NuGet から Gremlin.Net パッケージをインポートします。
```
dotnet add package Gremlin.Net
```
プロジェクトをビルドします。
```
dotnet build
```

オブジェクトモデル

	説明
`GremlinClient`	Gremlin サーバーの接続と対話に使用するクライアントを表します。
`GraphTraversalSource`	Gremlin トラバーサルの構築と実行に使用されます

クライアントの認証

まず、このガイドで前に収集した資格情報を使用してクライアントを認証します。

統合開発環境 (IDE) で Program.cs ファイルを開きます。
ファイル内に既存のコンテンツがあれば削除します。
ディレクティブを使用して次の名前空間のために追加します。
- Gremlin.Net.Driver
- Gremlin.Net.Structure.IO.GraphSON
```
using Gremlin.Net.Driver;
using Gremlin.Net.Structure.IO.GraphSON;
```
このガイドで前に収集した資格情報の文字列変数を作成します。変数に hostname と primaryKeyという名前を付けます。
```
string hostname = "<host>";
string primaryKey = "<key>";
```

前の手順で作成した資格情報と構成変数を使用して、 GremlinServer を作成します。変数に server という名前を付けます。

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

次に、GremlinClient変数とserver構成を使用してGraphSON2MessageSerializerを作成します。
```
GremlinClient client = new(
    server,
    new GraphSON2MessageSerializer()
);
```

データの挿入

次に、新しい頂点とエッジデータをグラフに挿入します。新しいデータを作成する前に、既存のデータのグラフをクリアします。

g.V().drop() クエリを実行して、グラフからすべての頂点とエッジをクリアします。
```
await client.SubmitAsync("g.V().drop()");
```

頂点を追加する Gremlin クエリを作成します。

string insertVertexQuery = """
    g.addV('product')
        .property('id', prop_id)
        .property('name', prop_name)
        .property('category', prop_category)
        .property('quantity', prop_quantity)
        .property('price', prop_price)
        .property('clearance', prop_clearance)
""";

製品ひとつに対して頂点を追加します。

await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
{
    ["prop_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    ["prop_name"] = "Yamba Surfboard",
    ["prop_category"] = "gear-surf-surfboards",
    ["prop_quantity"] = 12,
    ["prop_price"] = 850.00,
    ["prop_clearance"] = false
});

2 つの製品に対して、さらに頂点を 2 つ追加します。

await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
{
    ["prop_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
    ["prop_name"] = "Montau Turtle Surfboard",
    ["prop_category"] = "gear-surf-surfboards",
    ["prop_quantity"] = 5,
    ["prop_price"] = 600.00,
    ["prop_clearance"] = true
});

await client.SubmitAsync(insertVertexQuery, new Dictionary<string, object>
{
    ["prop_id"] = "cccccccc-2222-3333-4444-dddddddddddd",
    ["prop_name"] = "Noosa Surfboard",
    ["prop_category"] = "gear-surf-surfboards",
    ["prop_quantity"] = 31,
    ["prop_price"] = 1100.00,
    ["prop_clearance"] = false
});

エッジを追加する別の Gremlin クエリを作成します。

string insertEdgeQuery = """
    g.V([prop_partition_key, prop_source_id])
        .addE('replaces')
        .to(g.V([prop_partition_key, prop_target_id]))
""";

2 つのエッジを追加します。

await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
{
    ["prop_partition_key"] = "gear-surf-surfboards",
    ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
    ["prop_target_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
});

await client.SubmitAsync(insertEdgeQuery, new Dictionary<string, object>
{
    ["prop_partition_key"] = "gear-surf-surfboards",
    ["prop_source_id"] = "bbbbbbbb-1111-2222-3333-cccccccccccc",
    ["prop_target_id"] = "cccccccc-2222-3333-4444-dddddddddddd"
});

データの読み取り

次に、以前にグラフに挿入されたデータを読み取る。

一意識別子とパーティションキーの値を使用して、頂点を読み取るクエリを作成します。
```
string readVertexQuery = "g.V([prop_partition_key, prop_id])";
```

次に、必要なパラメーターを指定して頂点を読み取ります。

ResultSet<Dictionary<string, object>> readResults = await client.SubmitAsync<Dictionary<string, object>>(readVertexQuery, new Dictionary<string, object>
{
    ["prop_partition_key"] = "gear-surf-surfboards",
    ["prop_id"] = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
});

Dictionary<string, object> matchedItem = readResults.Single();

データのクエリを実行する

最後に、クエリを使用して、グラフ内の特定のトラバーサルまたはフィルターに一致するすべてのデータを検索します。

特定の頂点から走査するすべての頂点を検索するクエリを作成します。

string findVerticesQuery = """
    g.V().hasLabel('product')
        .has('category', prop_partition_key)
        .has('name', prop_name)
        .outE('replaces').inV()
""";

Montau Turtle Surfboard製品を指定してクエリを実行します。

ResultSet<Dictionary<string, object>> findResults = await client.SubmitAsync<Dictionary<string, object>>(findVerticesQuery, new Dictionary<string, object>
{
    ["prop_partition_key"] = "gear-surf-surfboards",
    ["prop_name"] = "Montau Turtle Surfboard"
});

クエリ結果を反復処理します。

foreach (Dictionary<string, object> result in findResults)
{
    // Do something here with each result
}

コードの実行

アプリケーションディレクトリのターミナルを使用して、新しく作成したアプリケーションを実行します。

dotnet run

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

アカウントが不要になったら、リソースを削除して Azure サブスクリプションからアカウント を削除 します。

Azure CLI
Azure Portal

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-30