.NET オブジェクト永続性モデルからの DynamoDBContext クラス

DynamoDBContext クラスは Amazon DynamoDB データベースのエントリポイントです。このクラスから DynamoDB に接続して、各種のテーブル内のデータにアクセスし、さまざまな CRUD オペレーションとクエリを実行することができます。DynamoDBContext クラスでは次のメソッドを使用できます。

Create​MultiTable​BatchGet

複数の個々の MultiTableBatchGet オブジェクトで構成される BatchGet オブジェクトを作成します。これらの各 BatchGet オブジェクトは、単一の DynamoDB テーブルから項目を取り出す場合に使用します。

1 つ以上のテーブルから項目を取得するには、ExecuteBatchGet メソッドを使用し、MultiTableBatchGet オブジェクトをパラメータとして渡します。

Create​MultiTable​BatchWrite

複数の個々の MultiTableBatchWrite オブジェクトで構成される BatchWrite オブジェクトを作成します。これらの各 BatchWrite オブジェクトは、単一の DynamoDB テーブルに項目を書き込んだり、それを削除したりするために使用します。

テーブルに書き込むには、ExecuteBatchWrite メソッドを使用し、MultiTableBatchWrite オブジェクトをパラメータとして渡します。

CreateBatchGet

テーブルから複数の項目を取り出すために使用できる BatchGet オブジェクトを作成します。

CreateBatchWrite

テーブルに複数の項目を入力する、またはテーブルから複数の項目を削除するために使用できる BatchWrite オブジェクトを作成します。

Delete

テーブルから項目を削除します。このメソッドでは、削除する項目のプライマリキーが必要になります。プライマリキーの値、またはこのメソッドのパラメータとしてプライマリキーの値を使用するクライアント側オブジェクトを入力できます。

Dispose

すべてのマネージドリソースとアンマネージドリソースを破棄します。

Execute​Batch​Get

1 つ以上のテーブルからデータを読み込みます。BatchGet 内のすべての MultiTableBatchGet オブジェクトを処理します。

Execute​Batch​Write

1 つ以上のテーブルにデータを書き込むまたは削除します。BatchWrite 内のすべての MultiTableBatchWrite オブジェクトを処理します。

FromDocument

Document のインスタンスと仮定すると、FromDocument メソッドは、クライアント側のクラスのインスタンスを返します。

これは、オブジェクト永続性モデルと合わせてドキュメントモデルクラスを使用してデータオペレーションを行う場合に役立ちます。AWS SDK for .NET で使用されるドキュメントモデルクラスの詳細については、「DynamoDB での .NET ドキュメントの操作」を参照してください。

Document という名前の doc オブジェクトがあり、Forum 項目の表現を含んでいるとします。(このオブジェクトの構成方法については、下の ToDocument メソッドの説明を参照してください)。次の C# サンプルコードに示すように、FromDocument を使用して Forum から Document 項目を取得することができます。

forum101 = context.FromDocument<Forum>(101);

FromQuery

QueryOperationConfig オブジェクトに定義されたクエリパラメータを使用して、Query オペレーションを実行します。

FromScan

ScanOperationConfig オブジェクトに定義されたスキャンパラメータを使用して、Scan オペレーションを実行します。

Get​Target​Table

指定した型のターゲットテーブルを取り出します。これは、任意データを DynamoDB テーブルにマッピングするためのカスタムコンバーターを記述していて、カスタムデータ型に関連付けられているテーブルを特定する必要がある場合に役立ちます。

Load

テーブルから項目を取り出します。このメソッドでは、取り出す項目のプライマリキーだけが必要になります。

DynamoDB のデフォルトでは、結果整合性のある値が含まれる項目が返されます。結果整合性モデルの詳細については、「DynamoDB の読み取り整合性」を参照してください。

Load または LoadAsync メソッドは GetItem オペレーションを呼び出します。このオペレーションでは、テーブルのプライマリキーを指定する必要があります。GetItem は IndexName パラメータを無視するため、インデックスのパーティションまたはソートキーを使用して項目を読み込むことはできません。そのため、テーブルのプライマリキーを使用して項目を読み込む必要があります。

    /// <summary>
    /// Shows how to perform high-level CRUD operations on an Amazon DynamoDB
    /// table.
    /// </summary>
    public class HighLevelItemCrud
    {
        public static async Task Main()
        {
            var client = new AmazonDynamoDBClient();
            DynamoDBContext context = new DynamoDBContext(client);
            await PerformCRUDOperations(context);
        }

        public static async Task PerformCRUDOperations(IDynamoDBContext context)
        {
            int bookId = 1001; // Some unique value.
            Book myBook = new Book
            {
                Id = bookId,
                Title = "object persistence-AWS SDK for.NET SDK-Book 1001",
                Isbn = "111-1111111001",
                BookAuthors = new List<string> { "Author 1", "Author 2" },
            };

            // Save the book to the ProductCatalog table.
            await context.SaveAsync(myBook);

            // Retrieve the book from the ProductCatalog table.
            Book bookRetrieved = await context.LoadAsync<Book>(bookId);

            // Update some properties.
            bookRetrieved.Isbn = "222-2222221001";

            // Update existing authors list with the following values.
            bookRetrieved.BookAuthors = new List<string> { " Author 1", "Author x" };
            await context.SaveAsync(bookRetrieved);

            // Retrieve the updated book. This time, add the optional
            // ConsistentRead parameter using DynamoDBContextConfig object.
            await context.LoadAsync<Book>(bookId, new DynamoDBContextConfig
            {
                ConsistentRead = true,
            });

            // Delete the book.
            await context.DeleteAsync<Book>(bookId);

            // Try to retrieve deleted book. It should return null.
            Book deletedBook = await context.LoadAsync<Book>(bookId, new DynamoDBContextConfig
            {
                ConsistentRead = true,
            });

            if (deletedBook == null)
            {
                Console.WriteLine("Book is deleted");
            }
        }
    }

Query

指定したクエリパラメータに基づいてテーブルのクエリが実行されます。

複合プライマリキー (パーティションキーおよびソートキー) が存在する場合にのみ、テーブルにクエリを実行できます。クエリを実行する場合は、パーティションキーと、ソートキーに適用される条件を指定する必要があります。

ここで、クライアント側の Reply クラスが、DynamoDB の Reply テーブルにマッピングされている場合を考えてみます。次の C# サンプルコードでは、Reply テーブルのクエリを実行し、過去 15 日間に投稿されたフォーラムスレッドの返信を検索しています。Reply テーブルには、Id パーティションキーと ReplyDateTime ソートキーを持つプライマリキーがあります。

DynamoDBContext context = new DynamoDBContext(client);

string replyId = "DynamoDB#DynamoDB Thread 1"; //Partition key
DateTime twoWeeksAgoDate = DateTime.UtcNow.Subtract(new TimeSpan(14, 0, 0, 0)); // Date to compare.
IEnumerable<Reply> latestReplies = context.Query<Reply>(replyId, QueryOperator.GreaterThan, twoWeeksAgoDate);

これにより、Reply オブジェクトのコレクションが返されます。

Query メソッドでは、「遅延ロード」された IEnumerable コレクションが返ります。最初に結果が 1 ページのみ返され、必要に応じて、さらに次ページを要求するサービス呼び出しが行われます。一致する項目をすべて取得するには、IEnumerable を反復的に処理します。

テーブルにシンプルなプライマリキー (パーティションキー) がある場合は、Query メソッドを使用できません。代わりに Load メソッドを使用して、パーティションキーを入力して項目を取り出すことができます。

保存

指定したオブジェクトがテーブルに保存されます。入力オブジェクトで指定されたプライマリキーがテーブル内に存在しない場合は、このメソッドによって新しい項目がテーブルに追加されます。プライマリキーが存在する場合は、このメソッドによって既存の項目が更新されます。

オプティミスティックロックを設定している場合には、クライアント側とサーバー側で項目のバージョンが一致する場合のみ、更新が正常に実行されます。詳細については、「DynamoDB と AWS SDK for .NET のオブジェクト永続性モデルを使用した楽観的ロック」を参照してください。

Scan

テーブル全体のスキャンを実行します。

スキャン結果をフィルタリングするには、スキャン条件を指定します。この条件は、テーブル内の任意の属性に適用することができます。例えば、クライアント側の Book クラスが、DynamoDB の ProductCatalog テーブルにマッピングされているとします。次の C# コード例では、テーブルがスキャンされ、価格が 0 未満の書籍項目だけが返されています。

IEnumerable<Book> itemsWithWrongPrice = context.Scan<Book>(
                    new ScanCondition("Price", ScanOperator.LessThan, price),
                    new ScanCondition("ProductCategory", ScanOperator.Equal, "Book")
      );

Scan メソッドでは、「遅延ロード」された IEnumerable コレクションが返ります。最初に結果が 1 ページのみ返され、必要に応じて、さらに次ページを要求するサービス呼び出しが行われます。一致するすべての項目は、IEnumerable を反復的に処理するだけで取得できます。

パフォーマンス上の理由から、テーブルについてはスキャンを避け、クエリを行うようにしてください。

ToDocument

クラスインスタンスから、Document ドキュメントモデルクラスのインスタンスが返されます。

これは、オブジェクト永続性モデルと合わせてドキュメントモデルクラスを使用してデータオペレーションを行う場合に役立ちます。AWS SDK for .NET で使用されるドキュメントモデルクラスの詳細については、「DynamoDB での .NET ドキュメントの操作」を参照してください。

クライアント側のクラスが Forum サンプルテーブルにマッピングされているとします。その場合は次の C# サンプルコードに示すように、DynamoDBContext を使用して、Document テーブルから項目を Forum オブジェクトとして取得することができます。

DynamoDBContext context = new DynamoDBContext(client);

Forum forum101 = context.Load<Forum>(101); // Retrieve a forum by primary key.
Document doc = context.ToDocument<Forum>(forum101);

DynamoDBContext でのオプションパラメータの指定

オブジェクト永続性モデルを使用する場合は、DynamoDBContext に次のオプションパラメータを指定できます。

次の C# サンプルコードでは、前述のオプションパラメータのうち 2 つ (ConsistentRead と SkipVersionCheck) を指定して、新しい DynamoDBContext を作成します。

AmazonDynamoDBClient client = new AmazonDynamoDBClient();
...
DynamoDBContext context =
       new DynamoDBContext(client, new DynamoDBContextConfig { ConsistentRead = true, SkipVersionCheck = true});

DynamoDBContext では、このコンテキストを使用して送信した各リクエストに、これらのオプションパラメータが含められます。

次の C# サンプルコードに示すように、これらのパラメータを DynamoDBContext レベルで設定する代わりに、DynamoDBContext を使用して実行するオペレーションに対して個別に指定することもできます。この例では特定の書籍項目がロードされています。DynamoDBContext の Load メソッドでは、オプションパラメータとして ConsistentRead と SkipVersionCheck を指定します。

AmazonDynamoDBClient client = new AmazonDynamoDBClient();
...
DynamoDBContext context = new DynamoDBContext(client);
Book bookItem = context.Load<Book>(productId,new DynamoDBContextConfig{ ConsistentRead = true, SkipVersionCheck = true });

この場合 DynamoDBContext には、Get リクエストを送信する場合のみ、これらのパラメータが含まれます。