.NET を使って ScalarDB Cluster SQL をはじめよう

注記

このページは英語版のページが機械翻訳されたものです。英語版との間に矛盾または不一致がある場合は、英語版を正としてください。

このチュートリアルでは、.NET API を使用して ScalarDB Cluster SQL を使用するサンプルアプリケーションを作成する方法について説明します。

概要

このチュートリアルでは、ScalarDB を使用して、商品を注文し、与信枠を使用して支払うことができるサンプルの電子商取引アプリケーションを作成するプロセスを説明します。

注記

このサンプルアプリケーションの目的は ScalarDB を使用する方法を示すことにあるため、アプリケーション固有のエラーハンドリング、認証処理、および類似の機能はサンプルアプリケーションには含まれていません。例外処理の詳細については、ScalarDB Cluster .NET Client SDK における例外処理を参照してください。

以下の図は、サンプルアプリケーションのシステムアーキテクチャを示しています。

このサンプルアプリケーションで実行できること

サンプルアプリケーションは、次の種類のトランザクションをサポートしています:

• 顧客情報を取得します。
• 信用枠を使用して注文を行います。
  • 注文のコストが顧客の信用限度額を下回っているかどうかを確認します。
  • チェックが成功した場合は、注文履歴を記録し、顧客が支払った金額を更新します。
• 注文 ID で注文情報を取得します。
• 顧客 ID で注文情報を取得します。
• 支払いを行います。
  • 顧客が支払った金額を減らします。

このサンプルアプリケーションの前提条件

• .NET SDK 8.0
• Kubernetes クラスターで実行されている ScalarDB Cluster
  • ScalarDB Cluster をローカルにデプロイする方法の手順に従ってデプロイした Kubernetes クラスターで ScalarDB Cluster が実行されていることを前提としています。

注記

.NET SDK 8.0 は、このサンプルアプリケーションの作成に使用されたバージョンです。サポートされているすべてのバージョンについては、要件を参照してください。

ScalarDB Cluster のセットアップ

次のセクションでは、サンプルの電子商取引アプリケーションをセットアップする方法について説明します。

ScalarDB サンプルリポジトリのクローンを作成する

ターミナルを開き、次のコマンドを実行して ScalarDB サンプルリポジトリのクローンを作成します。

git clone https://github.com/scalar-labs/scalardb-samples

次に、以下のコマンドを実行して、サンプルアプリケーションが含まれているディレクトリに移動します。

cd scalardb-samples/scalardb-dotnet-samples/scalardb-cluster-sql-sample

ScalarDB.Client パッケージの参照バージョンを更新する

ScalarDB Cluster を使用するには、お好みのテキストエディターで ScalarDbClusterSample.csproj を開きます。その後、参照されている ScalarDB.Client パッケージのバージョンを、デプロイされている ScalarDB Cluster のバージョンに合わせて <MAJOR>.<MINOR> を置き換えて更新します。

<PackageReference Include="ScalarDB.Client" Version="<MAJOR>.<MINOR>.*" />

scalardb-options.json を変更する

ScalarDB Cluster に接続するには、scalardb-options.json も変更する必要があります。ただし、その前に、Envoy サービスリソース (scalardb-cluster-envoy) の EXTERNAL-IP アドレスを取得する必要があります。サービスリソースを取得するには、次のコマンドを実行します。

kubectl get svc scalardb-cluster-envoy

以下のような出力が表示されます（実際に表示される CLUSTER-IP、PORT(S)、AGE の値は異なります）。

NAME                     TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)           AGE
scalardb-cluster-envoy   LoadBalancer   10.105.121.51   localhost     60053:30641/TCP   16h

この場合、EXTERNAL-IP アドレスは localhost です。

次のコマンドを実行して scalardb-options.json を開きます。

vim scalardb-options.json

その後、以下のように scalardb-options.json を修正します。

{
    "ScalarDbOptions": {
        "Address": "http://localhost:60053"
    }
}

初期データをロードする

サンプルアプリケーションを実行する前に、次のコマンドを実行して初期データをロードする必要があります。

dotnet run LoadInitialData

スキーマの詳細

上記のコマンドを実行すると、スキーマも適用されます。すべてのテーブルは sample 名前空間に作成されます。

• sample.customers: 顧客情報を管理するテーブル
  • credit_limit: 貸し手が顧客に信用枠から支出を許可する最大金額
  • credit_total: 顧客が信用枠から支出した金額
• sample.orders: 注文情報を管理するテーブル
• sample.statements: 注文明細情報を管理するテーブル
• sample.items: 注文するアイテムの情報を管理するテーブル

スキーマのエンティティ関係図は次のとおりです。

初期データ

初期データがロードされたら、次のレコードがテーブルに保存されます。

sample.customers テーブル

customer_id	name	credit_limit	credit_total
1	Yamada Taro	10000	0
2	Yamada Hanako	10000	0
3	Suzuki Ichiro	10000	0

sample.items テーブル

item_id	name	price
1	Apple	1000
2	Orange	2000
3	Grape	2500
4	Mango	5000
5	Melon	3000

サンプルアプリケーションでトランザクションを実行し、データを取得する

次のセクションでは、サンプル電子商取引アプリケーションでトランザクションを実行し、データを取得する方法について説明します。

顧客情報を取得する

次のコマンドを実行して、ID が 1 である顧客に関する情報を取得することから始めます。

dotnet run GetCustomerInfo 1

次の出力が表示されます。

{
  "id": 1,
  "name": "Yamada Taro",
  "credit_limit": 10000,
  "credit_total": 0
}

注文する

次に、以下のコマンドを実行して、顧客 ID 1 にリンゴ3個とオレンジ2個を注文してもらいます。

注記

このコマンドの注文形式は dotnet run PlaceOrder <CUSTOMER_ID> <ITEM_ID>:<COUNT>,<ITEM_ID>:<COUNT>,..." です。

dotnet run PlaceOrder 1 1:3,2:2

以下のように、order_id の UUID が異なる、注文が成功したことを示す類似の出力が表示されます。

{
  "order_id": "5a22150b-1944-403f-b02c-77183e705d1b"
}

注文の詳細を確認する

次のコマンドを実行して注文の詳細を確認します。<ORDER_ID_UUID> は、前のコマンドを実行した後に表示される order_id の UUID に置き換えてください。

dotnet run GetOrder <ORDER_ID_UUID>

order_id と timestamp の UUID が異なる、以下のような出力が表示されます。

{
  "order": {
    "order_id": "5a22150b-1944-403f-b02c-77183e705d1b",
    "timestamp": 1743143358216,
    "customer_id": 1,
    "customer_name": "Yamada Taro",
    "statements": [
      {
        "item_id": 1,
        "item_name": "Apple",
        "price": 1000,
        "count": 3,
        "total": 3000
      },
      {
        "item_id": 2,
        "item_name": "Orange",
        "price": 2000,
        "count": 2,
        "total": 4000
      }
    ],
    "total": 7000
  }
}

別の注文をする

次のコマンドを実行して、顧客 ID 1 の credit_total の残額を使用してメロン1個を注文します。

dotnet run PlaceOrder 1 5:1

以下のように、order_id の UUID が異なる、注文が成功したことを示す類似の出力が表示されます。

{
  "order_id": "79fcd778-94ba-4e8b-b993-cdb88a6186a8"
}

注文履歴を確認する

次のコマンドを実行して、顧客 ID 1 のすべての注文履歴を取得します。

dotnet run GetOrders 1

order_id と timestamp の UUID が異なる以下のような出力が表示されます。これは、顧客 ID 1 のすべての注文履歴をタイムスタンプの降順で表示します。

{
  "orders": [
    {
      "order_id": "5a22150b-1944-403f-b02c-77183e705d1b",
      "timestamp": 1743143358216,
      "customer_id": 1,
      "customer_name": "Yamada Taro",
      "statements": [
        {
          "item_id": 1,
          "item_name": "Apple",
          "price": 1000,
          "count": 3,
          "total": 3000
        },
        {
          "item_id": 2,
          "item_name": "Orange",
          "price": 2000,
          "count": 2,
          "total": 4000
        }
      ],
      "total": 7000
    },
    {
      "order_id": "79fcd778-94ba-4e8b-b993-cdb88a6186a8",
      "timestamp": 1743143505436,
      "customer_id": 1,
      "customer_name": "Yamada Taro",
      "statements": [
        {
          "item_id": 5,
          "item_name": "Melon",
          "price": 3000,
          "count": 1,
          "total": 3000
        }
      ],
      "total": 3000
    }
  ]
}

クレジット合計の確認

次のコマンドを実行して、顧客 ID 1 のクレジット合計を取得します。

dotnet run GetCustomerInfo 1

次の出力が表示されます。これは、顧客 ID 1 が credit_total の credit_limit に達しており、これ以上注文できないことを示しています。

{
  "id": 1,
  "name": "Yamada Taro",
  "credit_limit": 10000,
  "credit_total": 10000
}

次のコマンドを実行して、ブドウ1個とマンゴー1個を注文してみます。

dotnet run PlaceOrder 1 3:1,4:1

次の出力が表示されます。これは、credit_total 金額が credit_limit 金額を超えたために注文が失敗したことを示しています。

Unhandled exception: System.Exception: Credit limit exceeded (17500 > 10000)
   at ScalarDbClusterSqlSample.Sample.PlaceOrder(Int32 customerId, IReadOnlyDictionary`2 itemCounts) in /scalar-labs/scalardb-samples/scalardb-dotnet-samples/scalardb-cluster-sql-sample/Sample.cs:line 237
   at ScalarDbClusterSqlSample.Commands.PlaceOrderCommand.<>c.<<Create>b__6_0>d.MoveNext() in /scalar-labs/scalardb-samples/scalardb-dotnet-samples/scalardb-cluster-sql-sample/Commands/PlaceOrderCommand.cs:line 47
--- End of stack trace from previous location ---
...

支払いを行う

注文を続行するには、顧客 ID 1 が支払いを行って credit_total の金額を減らす必要があります。

次のコマンドを実行して支払いを行います。

dotnet run Repayment 1 8000

次に、以下のコマンドを実行して、顧客 ID 1 の credit_total 金額を確認します。

dotnet run GetCustomerInfo 1

次の出力が表示されます。これは、顧客 ID 1 に支払いが適用され、credit_total の金額が減ったことを示しています。

{
  "id": 1,
  "name": "Yamada Taro",
  "credit_limit": 10000,
  "credit_total": 2000
}

顧客 ID 1 が支払いを済ませたので、次のコマンドを実行してブドウ1個とメロン1個を注文します。

dotnet run PlaceOrder 1 3:1,4:1

以下のように、order_id の UUID が異なる、注文が成功したことを示す類似の出力が表示されます。

{
  "order_id": "ecd68f46-e248-4f2e-b581-620e9019bf5b"
}

参照

.NET API で ScalarDB Cluster を使用するアプリケーションの開発の詳細については、以下を参照してください。

• ScalarDB Cluster .NET Client SDK の概要
• ScalarDB Cluster .NET Client SDK での分散 SQL トランザクションをはじめよう

ScalarDB Cluster gRPC API の詳細については、以下を参照してください。

• ScalarDB Cluster gRPC API ガイド
• ScalarDB Cluster SQL gRPC API ガイド