Classe DynamoDBContext do modelo de persistência de objetos do .NET

A classe DynamoDBContext é o ponto de entrada para do banco de dados do Amazon DynamoDB. Ela fornece uma conexão com o DynamoDB e permite que você acesse seus dados em várias tabelas, realize várias operações CRUD e execute consultas. A classe DynamoDBContext fornece os seguintes métodos:

Create​MultiTable​BatchGet

Cria um objeto MultiTableBatchGet formado por vários objetos BatchGet individuais. Cada um desses objetos BatchGet pode ser usado para recuperar itens de uma única tabela do DynamoDB.

Para recuperar os itens das tabelas, use o método ExecuteBatchGet, passando o objeto MultiTableBatchGet como um parâmetro.

Create​MultiTable​BatchWrite

Cria um objeto MultiTableBatchWrite formado por vários objetos BatchWrite individuais. Cada um desses objetos BatchWrite pode ser usado para gravar ou excluir itens em uma única tabela do DynamoDB.

Para gravar nas tabelas, use o método ExecuteBatchWrite, passando o objeto MultiTableBatchWrite como um parâmetro.

CreateBatchGet

Cria um objeto BatchGet que você pode usar para recuperar vários itens de uma tabela.

CreateBatchWrite

Cria um objeto BatchWrite que você pode usar para inserir vários itens em uma tabela ou para excluir vários itens de uma tabela.

Delete

Exclui um item da tabela. O método requer a chave primária do item que você deseja excluir. É possível fornecer o valor da chave primária ou um objeto no lado do cliente que contém um valor de chave primária como um parâmetro para esse método.

Descartar

Descarta todos os recursos gerenciados e não gerenciados.

Execute​Batch​Get

Lê dados de uma ou mais tabelas, processando todos os objetos BatchGet em um MultiTableBatchGet.

Execute​Batch​Write

Grava ou exclui dados em uma ou mais tabelas, processando todos os objetos BatchWrite em um MultiTableBatchWrite.

FromDocument

Considerando uma instância de Document, o método FromDocument retorna uma instância de uma classe no lado do cliente.

Isso será útil se você quiser usar as classes de modelo de documento junto com o modelo de persistência de objetos para realizar qualquer operação de dados. Para obter mais informações sobre as classes do modelo de documento fornecidas pelo AWS SDK for .NET, consulte Trabalhar com o modelo de documento do .NET no DynamoDB.

Suponha que você tenha um objeto Document denominado doc que contém uma representação de um item Forum. (Para ver como construir esse objeto, consulte a descrição do método ToDocument mais adiante neste tópico.) Você pode usar FromDocument para recuperar o item Forum de Document, conforme mostrado no exemplo de código C# a seguir.

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

FromQuery

Executa uma operação Query, com os parâmetros de consulta definidos em um objeto QueryOperationConfig.

FromScan

Executa uma operação Scan, com os parâmetros de verificação definidos em um objeto ScanOperationConfig.

Get​Target​Table

Recupera a tabela de destino para o tipo especificado. Isso é útil quando você está escrevendo um conversor personalizado para o mapeamento de dados arbitrários para uma tabela do DynamoDB e precisa determinar qual tabela está associada a um tipo de dados personalizado.

Carregar

Recupera um item de uma tabela. O método requer somente a chave primária do item que você deseja recuperar.

Por padrão, o DynamoDB retorna o item com valores finais consistentes. Para obter informações sobre o modelo final consistente, consulte Consistência de leitura do DynamoDB.

O método Load ou LoadAsync chama a operação GetItem, que exige que você especifique a chave primária para a tabela. Como GetItem ignora o parâmetro IndexName, você não pode carregar um item usando a partição ou a chave de classificação de um índice. Portanto, é necessário usar a chave primária da tabela para carregar um item.

    /// <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");
            }
        }
    }

Consulta

Consulta uma tabela com base em parâmetros de consulta que você fornece.

Você poderá consultar uma tabela somente se ela tiver uma chave primária composta (chave de partição e chave de classificação). Ao consultar, você deve especificar uma chave de partição e uma condição que se aplique à chave de classificação.

Suponha que você tenha uma classe Reply no lado do cliente mapeada na tabela Reply no DynamoDB. O exemplo de código C# a seguir consulta a tabela Reply para encontrar respostas de tópicos de fórum postadas nos últimos 15 dias. A tabela Reply tem uma chave primária com a chave de partição Id e a chave de classificação 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);

Isso retorna uma coleção de objetos Reply.

Por padrão, o método Query retorna uma coleção IEnumerable de "carregamento preguiçoso". Ele inicialmente retorna apenas uma página de resultados e, em seguida, faz uma chamada de serviço para a próxima página, se necessário. Para obter todos os itens correspondentes, você só precisa fazer uma iteração na coleção IEnumerable.

Se a sua tabela tiver uma chave primária simples (chave de partição), você não poderá usar o método Query. Em vez disso, poderá usar o método Load e fornecer a chave de partição para recuperar o item.

Save (Salvar)

Salva o objeto especificado na tabela. Se a chave primária especificada no objeto de entrada não existir na tabela, o método adicionará um novo item à tabela. Se a chave primária existir, o método atualizará o item existente.

Se você tiver o bloqueio otimista configurado, a atualização será bem-sucedida apenas se as versões do item no lado do cliente e no lado do servidor corresponderem. Para ter mais informações, consulte Bloqueio positivo usando o DynamoDB e o modelo de persistência de objetos do AWS SDK for .NET.

Verificar

Realiza uma verificação de tabela inteira.

Você pode filtrar o resultado da verificação especificando uma condição de verificação. A condição pode ser avaliada em qualquer atributo da tabela. Suponha que você tenha uma classe Book no lado do cliente mapeada na tabela ProductCatalog no DynamoDB. O exemplo de código C# a seguir verifica a tabela e retorna apenas os itens de livro com preços inferiores a 0.

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

Por padrão, o método Scan retorna uma coleção IEnumerable de "carregamento preguiçoso". Ele inicialmente retorna apenas uma página de resultados e, em seguida, faz uma chamada de serviço para a próxima página, se necessário. Para obter todos os itens correspondentes, basta fazer uma iteração na coleção IEnumerable.

Por motivos de performance, você deve consultar suas tabelas e evitar uma verificação de tabela.

ToDocument

Retorna uma instância da classe de modelo de documento Document da sua instância de classe.

Isso será útil se você quiser usar as classes de modelo de documento junto com o modelo de persistência de objetos para realizar qualquer operação de dados. Para obter mais informações sobre as classes do modelo de documento fornecidas pelo AWS SDK for .NET, consulte Trabalhar com o modelo de documento do .NET no DynamoDB.

Suponha que você tenha uma classe de cliente mapeada na tabela de exemplo Forum. É possível usar um DynamoDBContext para obter um item, como um objeto Document da tabela Forum, conforme mostrado no exemplo de código C# a seguir.

DynamoDBContext context = new DynamoDBContext(client);

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

Especificar parâmetros opcionais para DynamoDBContext

Ao usar o modelo de persistência de objeto, você pode especificar os seguintes parâmetros opcionais para DynamoDBContext.

O exemplo de código C# a seguir cria um DynamoDBContext especificando dois dos parâmetros opcionais anteriores, ConsistentRead e SkipVersionCheck.

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

DynamoDBContext inclui esses parâmetros opcionais com cada solicitação enviada usando esse contexto.

Em vez de definir esses parâmetros no nível de DynamoDBContext, é possível especificá-los para operações individuais que você executa usando DynamoDBContext, conforme mostrado no exemplo de código C# a seguir. O exemplo carrega um item de livro específico. O método Load de DynamoDBContext especifica os parâmetros ConsistentRead e SkipVersionCheck opcionais.

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

Nesse caso, DynamoDBContext inclui esses parâmetros somente ao enviar a solicitação Get.