前提条件ステップ 1: プロジェクトを設定するステップ 2: ドライバーを初期化するステップ 3: テーブルとインデックスを作成するステップ 4: ドキュメントを挿入するステップ 5: ドキュメントにクエリを実行するステップ 6: ドキュメントを更新する完全なアプリケーションの実行

.NET 用 Amazon QLDB ドライバー — クイックスタートチュートリアル

このチュートリアルでは、.NET 用 Amazon QLDB ドライバーを使用して単純なアプリケーションを設定する方法について説明します。このガイドには、ドライバのインストール手順と、作成、読み取り、更新、削除 (CRUD) の基本的なオペレーションを実行する短いコード例が含まれています。

前提条件

作業を始める前に、次の操作を実行してください。

.NET ドライバー用の「前提条件」を完了します (まだ完了していない場合)。これには、AWS へのサインアップ、開発のためのプログラムによるアクセスの許可、.NET Core SDK のインストールが含まれます。
quick-start という名前の台帳を作成します。

台帳の作成方法については、「Amazon QLDB 台帳の基本的なオペレーション」、または「コンソールの開始方法」の「ステップ 1: 新しい台帳を作成する」を参照してください。

ステップ 1: プロジェクトを設定する

まず、.NET プロジェクトをセットアップします。

テンプレートアプリケーションを作成して実行するには、bash、PowerShell、コマンドプロンプトなどのターミナルで、次の dotnet コマンドを入力します。
```
$ dotnet new console --output Amazon.QLDB.QuickStartGuide
$ dotnet run --project Amazon.QLDB.QuickStartGuide
```
このテンプレートによって、Amazon.QLDB.QuickStartGuide という名前のフォルダが作成されます。そのフォルダに、同じ名前でプロジェクトが作成され、Program.cs という名前でファイルが作成されます。プログラムには、出力 Hello World! を表示するコードが含まれています。
NuGet パッケージマネージャーを使用して、.NET 用 QLDB ドライバーをインストールします。プロジェクトに依存関係を追加するには、Visual Studio または任意の IDE を使用することをお勧めします。ドライバーのパッケージ名は、Amazon.QLDB.Driver です。
- 例えば、Visual Studio では、[Tools] (ツール) メニューの [NuGet Package Manager Console] (NuGet パッケージマネージャーコンソール) を開きます。次に、PM> プロンプトで以下のコマンドを入力します。
```
PM> Install-Package Amazon.QLDB.Driver
```
- または、ターミナルで以下のコマンドを入力できます。
```
$ cd Amazon.QLDB.QuickStartGuide
$ dotnet add package Amazon.QLDB.Driver
```
ドライバーをインストールすると、AWS SDK for .NET や Amazon Ion ライブラリなどの依存関係もインストールされます。
ドライバーのシリアル化ライブラリをインストールします。
```
PM> Install-Package Amazon.QLDB.Driver.Serialization
```
Program.cs ファイルを開きます。

次に、以下のステップのコード例を段階的に追加し、いくつかの基本的な CRUD オペレーションを試します。または、ステップバイステップのチュートリアルをスキップして、代わりに完全なアプリケーションを実行することもできます。

注記

同期 API と非同期 API の選択 – このドライバーでは、同期 API と非同期 API を利用できます。ブロックせずに複数のリクエストを処理する需要の高いアプリケーションの場合、パフォーマンス向上のために非同期 API の使用をお勧めします。同期 API を利用すると、同期的に記述した既存のコードベースの利便性を高めることができます。

このチュートリアルでは、同期コードと非同期コードの両方の例を示します。API の詳細については、API ドキュメントに記載された「IQldbDriver」と「IAsyncQldbDriver」の各インターフェイスを参照してください。
Amazon Ion データの処理 – このチュートリアルでは、デフォルトで Ion オブジェクトマッパーを使用して Amazon Ion データを処理するコード例を紹介します。QLDB は、.NET ドライバーのバージョン 1.3.0 で Ion オブジェクトマッパーを導入しました。このチュートリアルでは、該当する場合、標準の Ion ライブラリを代替として使用するコード例も提供しています。詳細については、「Amazon Ion の操作」を参照してください。

ステップ 2: ドライバーを初期化する

quick-start という名前の台帳に接続するドライバーのインスタンスを初期化します。以下のコードを Program.cs ファイルに追加します。

ステップ 3: テーブルとインデックスを作成する

このチュートリアルの残りの部分 (ステップ 6 まで) では、前のコード例に次のコード例を追加する必要があります。

このステップの次のコードは、CREATE TABLE および CREATE INDEX ステートメントの実行方法を示しています。これにより、Person という名前のテーブルと、そのテーブルの firstName フィールドのインデックスが作成されます。クエリのパフォーマンスを最適化し、オプティミスティック同時実行制御 (OCC) 競合例外を制限するために、インデックスが必要です。

ステップ 4: ドキュメントを挿入する

次のコード例は、INSERT ステートメントの実行方法を示しています。QLDB は PartiQL クエリ言語 (SQL 互換) と Amazon Ion データ形式 (JSON のスーパーセット) をサポートします。

Person テーブルにドキュメントを挿入する以下のコードを追加します。

ヒント

次のように Ion リスト型パラメータをステートメントに渡すと、1 つの INSERT ステートメントを使用して複数のドキュメントを挿入できます。


// people is an Ion list
txn.Execute("INSERT INTO Person ?", people);

Ion リストを渡すときには、変数プレースホルダー (?) を二重山括弧 (<<...>>) で囲まないでください。マニュアルの PartiQL ステートメントでは、二重山括弧はバッグと呼ばれる順序付けされていないコレクションを表します。

ステップ 5: ドキュメントにクエリを実行する

次のコード例は、SELECT ステートメントの実行方法を示しています。

Person テーブルからドキュメントをクエリする以下のコードを追加します。

この例では、疑問符 (?) を変数プレースホルダーとして使用して、ドキュメント情報をステートメントに渡します。プレースホルダーを使用する場合、IonValue 型の値を渡す必要があります。

ステップ 6: ドキュメントを更新する

次のコード例は、UPDATE ステートメントの実行方法を示しています。

age を 42 に変更して Person テーブルのドキュメントを更新する以下のコードを追加します。

ドキュメントを再度クエリして、更新された値を確認します。

アプリケーションを実行するには、Amazon.QLDB.QuickStartGuide プロジェクトディレクトリの親ディレクトリから以下のコマンドを入力します。
```
$ dotnet run --project Amazon.QLDB.QuickStartGuide
```

age を 42 に変更して Person テーブルのドキュメントを更新する以下のコードを追加します。

ドキュメントを再度クエリして、更新された値を確認します。

アプリケーションを実行するには、Amazon.QLDB.QuickStartGuide プロジェクトディレクトリの親ディレクトリから以下のコマンドを入力します。
```
$ dotnet run --project Amazon.QLDB.QuickStartGuide
```

完全なアプリケーションの実行

以下のコード例は、Program.cs アプリケーションの完全なバージョンです。上のステップを個別に実行する代わりに、このコード例を最初から最後までコピーして実行することもできます。このアプリケーションは、quick-start という名前の台帳に対するいくつかの基本的な CRUD オペレーションを実行します。

注記

このコードを実行する前に、quick-start 台帳に Person という名前のアクティブなテーブルが存在しないことを確認してください。

Async


using Amazon.QLDB.Driver;
using Amazon.QLDB.Driver.Generic;
using Amazon.QLDB.Driver.Serialization;

namespace Amazon.QLDB.QuickStartGuide
{
    class Program
    {
        public class Person
        {
            public string FirstName { get; set; }

            public string LastName { get; set; }

            public int Age { get; set; }

            public override string ToString()
            {
                return FirstName + ", " + LastName + ", " + Age.ToString();
            }
        }

        static async Task Main(string[] args)
        {
            Console.WriteLine("Create the async QLDB driver");
            IAsyncQldbDriver driver = AsyncQldbDriver.Builder()
                .WithLedger("quick-start")
                .WithSerializer(new ObjectSerializer())
                .Build();

            Console.WriteLine("Creating the table and index");

            // Creates the table and the index in the same transaction.
            // Note: Any code within the lambda can potentially execute multiple times due to retries.
            // For more information, see: https://docs.aws.amazon.com/qldb/latest/developerguide/driver-retry-policy
            await driver.Execute(async txn =>
            {
                await txn.Execute("CREATE TABLE Person");
                await txn.Execute("CREATE INDEX ON Person(firstName)");
            });

            Console.WriteLine("Inserting a document");

            Person myPerson = new Person {
                FirstName = "John",
                LastName = "Doe",
                Age = 32
            };

            await driver.Execute(async txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("INSERT INTO Person ?", myPerson);
                await txn.Execute(myQuery);
            });

            Console.WriteLine("Querying the table");

            // The result from driver.Execute() is buffered into memory because once the
            // transaction is committed, streaming the result is no longer possible.
            IAsyncResult<Person> selectResult = await driver.Execute(async txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("SELECT * FROM Person WHERE FirstName = ?", "John");
                return await txn.Execute(myQuery);
            });

            await foreach (Person person in selectResult)
            {
                Console.WriteLine(person);
                // John, Doe, 32
            }

            Console.WriteLine("Updating the document");

            await driver.Execute(async txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("UPDATE Person SET Age = ? WHERE FirstName = ?", 42, "John");
                await txn.Execute(myQuery);
            });

            Console.WriteLine("Querying the table for the updated document");

            IAsyncResult<Person> updateResult = await driver.Execute(async txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("SELECT * FROM Person WHERE FirstName = ?", "John");
                return await txn.Execute(myQuery);
            });

            await foreach (Person person in updateResult)
            {
                Console.WriteLine(person);
                // John, Doe, 42
            }
        }
    }
}

Sync


using Amazon.QLDB.Driver;
using Amazon.QLDB.Driver.Generic;
using Amazon.QLDB.Driver.Serialization;

namespace Amazon.QLDB.QuickStartGuide
{
    class Program
    {
        public class Person
        {
            public string FirstName { get; set; }

            public string LastName { get; set; }

            public int Age { get; set; }

            public override string ToString()
            {
                return FirstName + ", " + LastName + ", " + Age.ToString();
            }
        }

        static void Main(string[] args)
        {
            Console.WriteLine("Create the sync QLDB driver");
            IQldbDriver driver = QldbDriver.Builder()
                .WithLedger("quick-start")
                .WithSerializer(new ObjectSerializer())
                .Build();

            Console.WriteLine("Creating the table and index");

            // Creates the table and the index in the same transaction.
            // Note: Any code within the lambda can potentially execute multiple times due to retries.
            // For more information, see: https://docs.aws.amazon.com/qldb/latest/developerguide/driver-retry-policy
            driver.Execute(txn =>
            {
                txn.Execute("CREATE TABLE Person");
                txn.Execute("CREATE INDEX ON Person(firstName)");
            });

            Console.WriteLine("Inserting a document");

            Person myPerson = new Person {
                FirstName = "John",
                LastName = "Doe",
                Age = 32
            };

            driver.Execute(txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("INSERT INTO Person ?", myPerson);
                txn.Execute(myQuery);
            });

            Console.WriteLine("Querying the table");

            // The result from driver.Execute() is buffered into memory because once the
            // transaction is committed, streaming the result is no longer possible.
            IResult<Person> selectResult = driver.Execute(txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("SELECT * FROM Person WHERE FirstName = ?", "John");
                return txn.Execute(myQuery);
            });

            foreach (Person person in selectResult)
            {
                Console.WriteLine(person);
                // John, Doe, 32
            }

            Console.WriteLine("Updating the document");

            driver.Execute(txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("UPDATE Person SET Age = ? WHERE FirstName = ?", 42, "John");
                txn.Execute(myQuery);
            });

            Console.WriteLine("Querying the table for the updated document");

            IResult<Person> updateResult = driver.Execute(txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("SELECT * FROM Person WHERE FirstName = ?", "John");
                return txn.Execute(myQuery);
            });

            foreach (Person person in updateResult)
            {
                Console.WriteLine(person);
                // John, Doe, 42
            }

        }
    }
}

Async


using System;
using System.Threading.Tasks;
using Amazon.IonDotnet.Tree;
using Amazon.IonDotnet.Tree.Impl;
using Amazon.QLDB.Driver;
using IAsyncResult = Amazon.QLDB.Driver.IAsyncResult;

namespace Amazon.QLDB.QuickStartGuide
{
    class Program
    {
        static IValueFactory valueFactory = new ValueFactory();

        static async Task Main(string[] args)
        {
            Console.WriteLine("Create the async QLDB driver");
            IAsyncQldbDriver driver = AsyncQldbDriver.Builder()
                .WithLedger("quick-start")
                .Build();

            Console.WriteLine("Creating the table and index");

            // Creates the table and the index in the same transaction.
            // Note: Any code within the lambda can potentially execute multiple times due to retries.
            // For more information, see: https://docs.aws.amazon.com/qldb/latest/developerguide/driver-retry-policy
            await driver.Execute(async txn =>
            {
                await txn.Execute("CREATE TABLE Person");
                await txn.Execute("CREATE INDEX ON Person(firstName)");
            });

            Console.WriteLine("Inserting a document");

            // This is one way of creating Ion values. We can also use an IonLoader.
            // For more details, see: https://docs.aws.amazon.com/qldb/latest/developerguide/driver-cookbook-dotnet.html#cookbook-dotnet.ion
            IIonValue ionPerson = valueFactory.NewEmptyStruct();
            ionPerson.SetField("firstName", valueFactory.NewString("John"));
            ionPerson.SetField("lastName", valueFactory.NewString("Doe"));
            ionPerson.SetField("age", valueFactory.NewInt(32));

            await driver.Execute(async txn =>
            {
                await txn.Execute("INSERT INTO Person ?", ionPerson);
            });

            Console.WriteLine("Querying the table");

            IIonValue ionFirstName = valueFactory.NewString("John");

            // The result from driver.Execute() is buffered into memory because once the
            // transaction is committed, streaming the result is no longer possible.
            IAsyncResult selectResult = await driver.Execute(async txn =>
            {
                return await txn.Execute("SELECT * FROM Person WHERE firstName = ?", ionFirstName);
            });

            await foreach (IIonValue row in selectResult)
            {
                Console.WriteLine(row.GetField("firstName").StringValue);
                Console.WriteLine(row.GetField("lastName").StringValue);
                Console.WriteLine(row.GetField("age").IntValue);
            }

            Console.WriteLine("Updating the document");

            IIonValue ionIntAge = valueFactory.NewInt(42);
            IIonValue ionFirstName2 = valueFactory.NewString("John");

            await driver.Execute(async txn =>
            {
                await txn.Execute("UPDATE Person SET age = ? WHERE firstName = ?", ionIntAge, ionFirstName2);
            });

            Console.WriteLine("Querying the table for the updated document");

            IIonValue ionFirstName3 = valueFactory.NewString("John");

            IAsyncResult updateResult = await driver.Execute(async txn =>
            {
                return await txn.Execute("SELECT * FROM Person WHERE firstName = ?", ionFirstName3);
            });

            await foreach (IIonValue row in updateResult)
            {
                Console.WriteLine(row.GetField("firstName").StringValue);
                Console.WriteLine(row.GetField("lastName").StringValue);
                Console.WriteLine(row.GetField("age").IntValue);
            }
        }
    }
}

Sync


using System;
using Amazon.IonDotnet.Tree;
using Amazon.IonDotnet.Tree.Impl;
using Amazon.QLDB.Driver;

namespace Amazon.QLDB.QuickStartGuide
{
    class Program
    {
        static IValueFactory valueFactory = new ValueFactory();

        static void Main(string[] args)
        {
            Console.WriteLine("Create the sync QLDB Driver");
            IQldbDriver driver = QldbDriver.Builder()
                .WithLedger("quick-start")
                .Build();

            Console.WriteLine("Creating the tables and index");

            // Creates the table and the index in the same transaction.
            // Note: Any code within the lambda can potentially execute multiple times due to retries.
            // For more information, see: https://docs.aws.amazon.com/qldb/latest/developerguide/driver-retry-policy
            driver.Execute(txn =>
            {
                txn.Execute("CREATE TABLE Person");
                txn.Execute("CREATE INDEX ON Person(firstName)");
            });

            Console.WriteLine("Inserting a document");

            // This is one way of creating Ion values. We can also use an IonLoader.
            // For more details, see: https://docs.aws.amazon.com/qldb/latest/developerguide/driver-cookbook-dotnet.html#cookbook-dotnet.ion
            IIonValue ionPerson = valueFactory.NewEmptyStruct();
            ionPerson.SetField("firstName", valueFactory.NewString("John"));
            ionPerson.SetField("lastName", valueFactory.NewString("Doe"));
            ionPerson.SetField("age", valueFactory.NewInt(32));

            driver.Execute(txn =>
            {
                txn.Execute("INSERT INTO Person ?", ionPerson);
            });

            Console.WriteLine("Querying the table");

            IIonValue ionFirstName = valueFactory.NewString("John");

            // The result from driver.Execute() is buffered into memory because once the
            // transaction is committed, streaming the result is no longer possible.
            IResult selectResult = driver.Execute(txn =>
            {
                return txn.Execute("SELECT * FROM Person WHERE firstName = ?", ionFirstName);
            });

            foreach (IIonValue row in selectResult)
            {
                Console.WriteLine(row.GetField("firstName").StringValue);
                Console.WriteLine(row.GetField("lastName").StringValue);
                Console.WriteLine(row.GetField("age").IntValue);
            }

            Console.WriteLine("Updating a document");

            IIonValue ionIntAge = valueFactory.NewInt(42);
            IIonValue ionFirstName2 = valueFactory.NewString("John");

            driver.Execute(txn =>
            {
                txn.Execute("UPDATE Person SET age = ? WHERE firstName = ?", ionIntAge, ionFirstName2);
            });

            Console.WriteLine("Querying the table for the updated document");

            IIonValue ionFirstName3 = valueFactory.NewString("John");

            IResult updateResult = driver.Execute(txn =>
            {
                return txn.Execute("SELECT * FROM Person WHERE firstName = ?", ionFirstName3);
            });

            foreach (IIonValue row in updateResult)
            {
                Console.WriteLine(row.GetField("firstName").StringValue);
                Console.WriteLine(row.GetField("lastName").StringValue);
                Console.WriteLine(row.GetField("age").IntValue);
            }
        }
    }
}

アプリケーション全体を実行するには、Amazon.QLDB.QuickStartGuide プロジェクトディレクトリの親ディレクトリから以下のコマンドを入力します。


$ dotnet run --project Amazon.QLDB.QuickStartGuide

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

.NET ドライバー

クックブックリファレンス