Classe DynamoDBContext

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. Para ter mais informações, consulte Obtenção em lote: obter vários itens .

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. Para ter mais informações, consulte Gravação em lote: colocar e excluir vários itens .

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.

• Se você especificar um objeto no lado do cliente como um parâmetro e tiver habilitado o bloqueio otimista, a exclusão apenas será bem-sucedida se as versões no lado do cliente e no lado do servidor desse objeto corresponderem.

• Se você especificar somente o valor da chave primária como parâmetro, a exclusão será bem-sucedida, independentemente de você ter habilitado ou não o bloqueio otimista.

nota

Para realizar essa operação em segundo plano, use o método DeleteAsync em vez disso.

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.

nota

Para realizar essa operação em segundo plano, use o método ExecuteBatchGetAsync em vez disso.

Execute​Batch​Write

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

nota

Para realizar essa operação em segundo plano, use o método ExecuteBatchWriteAsync em vez disso.

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 .NET: modelo de documento.

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.

exemplo

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

nota

Se o objeto Document implementar a interface IEnumerable, você poderá usar o método FromDocuments em vez disso. Isso permite uma iteração sobre todas as instâncias da classe em Document.

FromQuery

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

nota

Para realizar essa operação em segundo plano, use o método FromQueryAsync em vez disso.

FromScan

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

nota

Para realizar essa operação em segundo plano, use o método FromScanAsync em vez disso.

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 leituras.

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.

nota

Para realizar essa operação em segundo plano, use o método LoadAsync em vez disso. Para ver um exemplo do uso do método LoadAsync para realizar operações CRUD de alto nível em uma tabela do DynamoDB, consulte o exemplo a seguir.

    /// <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. Para obter mais informações sobre a tabela Reply, consulte Criar tabelas e carregar dados para exemplos de código no DynamoDB.

exemplo

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.

nota

Para realizar essa operação em segundo plano, use o método QueryAsync em vez disso.

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 número de versão com o DynamoDB usando o modelo de persistência de objetos do AWS SDK for .NET.

nota

Para realizar essa operação em segundo plano, use o método SaveAsync em vez disso.

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.

exemplo

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.

nota

Para realizar essa operação em segundo plano, use o método ScanAsync em vez disso.

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 .NET: modelo de documento.

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.

exemplo

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.

• ConsistentRead: ao recuperar dados usando as operações Load, Query ou Scan, você pode opcionalmente adicionar esse parâmetro para solicitar os valores mais recentes dos dados.

• IgnoreNullValues: esse parâmetro instrui DynamoDBContext a ignorar valores nulos em atributos durante uma operação Save. Se esse parâmetro for false (ou se não estiver definido), um valor nulo será interpretado como uma diretiva para excluir o atributo específico.

• SkipVersionCheck: esse parâmetro instrui o DynamoDBContext a não comparar versões ao salvar ou excluir um item. Para obter mais informações sobre versionamento, consulte Bloqueio positivo usando número de versão com o DynamoDB usando o modelo de persistência de objetos do AWS SDK for .NET.

• TableNamePrefix: prefixa todos os nomes de tabelas com uma string específica. Se esse parâmetro for nulo (ou se não estiver definido), nenhum prefixo será usado.

• DynamoDBEntryConversion: especifica o esquema de conversão usado pelo cliente. Você pode definir esse parâmetro para a versão V1 ou V2. A versão padrão é V1.

  O comportamento desse parâmetro pode mudar com base na versão definida. Por exemplo:

  • Na V1, o tipo de dados bool é convertido no tipo numérico N, em que 0 representa falso e 1 representa verdadeiro. Na V2, bool é convertido em BOOL.

  • Na V2, listas e matrizes não são agrupadas com HashSets. Listas e matrizes de números, tipos baseados em strings e tipos baseados em binários são convertidos no tipo L (Lista), que pode ser enviado vazio para atualizar uma lista. Isso é diferente da V1, em que uma lista vazia não é enviada pela rede.

    Na V1, os tipos de coleção, como lista, HashSet e matrizes, são tratados da mesma forma. Lista, HashSet e matriz de números são convertidos no tipo NS (conjunto de números).

  O exemplo a seguir define a versão do esquema de conversão como V2, o que altera o comportamento de conversão entre os tipos .NET e os tipos de dados do DynamoDB.

  var config = new DynamoDBContextConfig
  {
      Conversion = DynamoDBEntryConversion.V2
  };
  var contextV2 = new DynamoDBContext(client, config);

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

exemplo

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.

exemplo

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.