次の方法で共有


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

適用対象: Gremlin

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

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

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

前提条件

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 アカウントを作成し、ライブラリを使ってアカウントに接続するように .NET プロジェクトを設定する方法を説明します。

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

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

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

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

  1. 空のフォルダーでターミナルを開きます。

  2. コンソール テンプレート を指定する dotnet new コマンドを使用します。

    dotnet new console
    

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

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

  1. dotnet add package コマンドを使い、Gremlin.Net NuGet パッケージを指定します。

    dotnet add package Gremlin.Net
    
  2. 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 の値を使用するには、アプリケーションを実行しているローカル コンピューター上の新しい環境変数にそれらを永続化します。

  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 の場合は、このクイックスタートで前に取得した "名前" と URI の値を使います。

  1. Program.cs ファイルを開きます。

  2. ファイル内に既存のコンテンツがあれば削除します。

  3. Gremlin.Net.Driver 名前空間の using ブロックを追加します。

    using Gremlin.Net.Driver;
    
  4. 文字列変数 accountNameaccountKey を作成します。 COSMOS_GREMLIN_ENDPOINT および COSMOS_GREMLIN_KEY 環境変数を、それぞれの変数の値として格納します。

    string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
    string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;
    
  5. アカウントの資格情報を使って、GremlinServer の新しいインスタンスを作成します。

    var server = new GremlinServer(
        hostname: $"{accountName}.gremlin.cosmos.azure.com",
        port: 443,
        username: "/dbs/cosmicworks/colls/products",
        password: $"{accountKey}",
        enableSsl: true
    );
    
  6. リモート サーバーの資格情報と GraphSON 2.0 シリアライザーを使って、GremlinClient のインスタンスを作成します。

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

頂点を作成する

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

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

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

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

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

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

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

  1. グラフを走査して、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()"
    );
    
  2. 固定の文字列 [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"]}");
    }
    

コードの実行

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

  1. .NET プロジェクト フォルダーでターミナルを開きます。

  2. dotnet run を使ってアプリケーションを実行します。

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

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

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

Gremlin 用 API アカウントが必要なくなったら、対応するリソース グループを削除します。

  1. resourceGroupName のシェル変数がまだ存在しない場合は作成します。

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos-gremlin-quickstart"
    
  2. az group delete を使ってリソース グループを削除します。

    az group delete \
        --name $resourceGroupName
    

次のステップ