Trabalhar com itens no DynamoDB usando o modelo de documento do AWS SDK for .NET

Os exemplos de código a seguir demonstram como realizar diversas operações com o modelo de documento do AWS SDK for .NET. Você pode usar esses exemplos para realizar operações de CRUD, em lote e de transação.

Para realizar operações de dados usando o modelo de documento, você deve primeiro chamar o método Table.LoadTable, que cria uma instância da classe Table que representa uma tabela específica. O exemplo de código C# a seguir cria um objeto Table que representa a tabela ProductCatalog no Amazon DynamoDB.

exemplo

Table table = Table.LoadTable(client, "ProductCatalog");

nota

Em geral, você usa o método LoadTable uma vez no início da sua aplicação, pois ele faz uma chamada DescribeTableque adiciona o trajeto de ida e volta ao DynamoDB.

É possível usar o objeto Table para realizar várias operações de dados. Cada operação de dados tem dois tipos de sobrecargas: um que usa os parâmetros mínimos necessários, e o outro que usa informações de configuração opcionais específicas da operação. Por exemplo, para recuperar um item, é necessário fornecer o valor da chave primária da tabela. Nesse caso, é possível usar a seguinte sobrecarga de GetItem.

exemplo

// Get the item from a table that has a primary key that is composed of only a partition key.
Table.GetItem(Primitive partitionKey);
// Get the item from a table whose primary key is composed of both a partition key and sort key.
Table.GetItem(Primitive partitionKey, Primitive sortKey);

Também é possível transmitir parâmetros opcionais para esses métodos. Por exemplo, a GetItem anterior retorna o item inteiro, incluindo todos os seus atributos. Como opção, é possível especificar uma lista de atributos a serem recuperados. Nesse caso, use a seguinte sobrecarga de GetItem, que usa o parâmetro de objeto de configuração específico da operação.

exemplo

// Configuration object that specifies optional parameters.
GetItemOperationConfig config = new GetItemOperationConfig()
{
  AttributesToGet = new List<string>() { "Id", "Title" },
};
// Pass in the configuration to the GetItem method.
// 1. Table that has only a partition key as primary key.
Table.GetItem(Primitive partitionKey, GetItemOperationConfig config);
// 2. Table that has both a partition key and a sort key.
Table.GetItem(Primitive partitionKey, Primitive sortKey, GetItemOperationConfig config);

É possível usar o objeto de configuração para especificar vários parâmetros opcionais, como solicitar uma lista específica de atributos ou especificar o tamanho da página (número de itens por página). Cada método de operação de dados tem sua própria classe de configuração. Por exemplo é possível usar a classe GetItemOperationConfig para fornecer opções para a operação GetItem. É possível usar a classe PutItemOperationConfig a fim de fornecer parâmetros opcionais para a operação PutItem.

As seções a seguir discutem cada uma das operações de dados com suporte pela classe Table.

Colocando um item - Tabela. PutItem método

O método PutItem faz upload da instância Document de entrada na tabela. Se um item com uma chave primária especificada na entrada Document existir na tabela, a operação PutItem substituirá esse item inteiro. O novo item será idêntico ao objeto Document que você forneceu para o método PutItem. Se o seu item original tinha atributos extras, eles não estão mais presentes no novo item.

Veja a seguir as etapas para inserir um novo item em uma tabela usando o modelo de documento do AWS SDK for .NET.

1. Execute o método Table.LoadTable que fornece o nome da tabela na qual você deseja inserir um item.

2. Crie um objeto Document que tenha uma lista de nomes de atributos e seus valores.

3. Execute Table.PutItem fornecendo a instância Document como um parâmetro.

O exemplo de código C# a seguir demonstra as tarefas anteriores. O exemplo faz upload de um item para a tabela ProductCatalog.

exemplo

Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();
book["Id"] = 101;
book["Title"] = "Book 101 Title";
book["ISBN"] = "11-11-11-11";
book["Authors"] = new List<string> { "Author 1", "Author 2" };
book["InStock"] = new DynamoDBBool(true);
book["QuantityOnHand"] = new DynamoDBNull();

table.PutItem(book);

No exemplo anterior, a Document instância cria um item que tem Null atributos NumberString,String Set,Boolean, e. (Nullé usado para indicar que a origem QuantityOnHanddeste produto é desconhecida.) Para Boolean e Null, use os métodos de construtor DynamoDBBool e DynamoDBNull.

No DynamoDB, os tipos de dados List e Map podem conter elementos compostos por outros tipos de dados. Veja a seguir como mapear esses tipos de dados para a API do modelo de documento:

• List — use o construtor DynamoDBList.

• Map — use o construtor Document.

É possível modificar o exemplo anterior para adicionar um atributo List ao item. Para fazer isso, use um construtor DynamoDBList, conforme mostrado no exemplo de código a seguir.

exemplo

Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();
book["Id"] = 101;

/*other attributes omitted for brevity...*/

var relatedItems = new DynamoDBList();
relatedItems.Add(341);
relatedItems.Add(472);
relatedItems.Add(649);
book.Add("RelatedItems", relatedItems);

table.PutItem(book);

Para adicionar um atributo Map ao livro, defina outro Document. O exemplo de código a seguir ilustra como fazer isso.

exemplo

Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();
book["Id"] = 101;

/*other attributes omitted for brevity...*/

var pictures = new Document();
pictures.Add("FrontView", "http://example.com/products/101_front.jpg" );
pictures.Add("RearView", "http://example.com/products/101_rear.jpg" );

book.Add("Pictures", pictures);

table.PutItem(book);

Esses exemplos se baseiam no item mostrado em Especificar atributos de item ao usar expressões. O modelo de documento permite criar atributos complexos aninhados, como o atributo ProductReviews mostrado no estudo de caso.

Especificar parâmetros opcionais

É possível configurar parâmetros opcionais para a operação PutItem, adicionando o parâmetro PutItemOperationConfig. Para obter uma lista completa de parâmetros opcionais, consulte PutItem. O exemplo de código C# a seguir insere um item na tabela ProductCatalog. Ele especifica o parâmetro opcional a seguir:

• O parâmetro ConditionalExpression faz com que essa solicitação seja uma inserção condicional. O exemplo cria uma expressão que especifica que o atributo ISBN deve ter um valor específico, que precisa estar presente no item que você está substituindo.

exemplo

Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();
book["Id"] = 555;
book["Title"] = "Book 555 Title";
book["Price"] = "25.00";
book["ISBN"] = "55-55-55-55";
book["Name"] = "Item 1 updated";
book["Authors"] = new List<string> { "Author x", "Author y" };
book["InStock"] = new DynamoDBBool(true);
book["QuantityOnHand"] = new DynamoDBNull();

// Create a condition expression for the optional conditional put operation.
Expression expr = new Expression();
expr.ExpressionStatement = "ISBN = :val";
expr.ExpressionAttributeValues[":val"] = "55-55-55-55";

PutItemOperationConfig config = new PutItemOperationConfig()
{
  // Optional parameter.
     ConditionalExpression = expr
};

table.PutItem(book, config);

Obtendo um item - Tabela. GetItem

A operação GetItem recupera um item como uma instância de Document. É necessário fornecer a chave primária do item que você deseja recuperar, conforme mostrado no seguinte exemplo de código C#.

exemplo

Table table = Table.LoadTable(client, "ProductCatalog");
Document document = table.GetItem(101); // Primary key 101.

A operação GetItem retorna todos os atributos do item e realiza uma leitura eventualmente consistente (consulte Consistência de leituras) por padrão.

Especificar parâmetros opcionais

Você pode configurar opções adicionais para a operação GetItem, adicionando o parâmetro GetItemOperationConfig. Para obter uma lista completa de parâmetros opcionais, consulte GetItem. O exemplo de código do C# a seguir recupera um item da tabela ProductCatalog. Ele especifica a GetItemOperationConfig para fornecer os seguintes parâmetros opcionais:

• O parâmetro AttributesToGet para recuperar somente os atributos especificados.

• O parâmetro ConsistentRead para solicitar os valores mais recentes para todos os atributos especificados. Para saber mais sobre consistência de dados, consulte Consistência de leituras.

exemplo

Table table = Table.LoadTable(client, "ProductCatalog");

GetItemOperationConfig config = new GetItemOperationConfig()
{
  AttributesToGet = new List<string>() { "Id", "Title", "Authors", "InStock", "QuantityOnHand" },
  ConsistentRead = true
};
Document doc = table.GetItem(101, config);

Ao recuperar um item usando a API do modelo de documento, é possível acessar os elementos individuais dentro do objeto Document que é retornado, conforme mostrado no exemplo a seguir.

exemplo

int id = doc["Id"].AsInt();
string title = doc["Title"].AsString();
List<string> authors = doc["Authors"].AsListOfString();
bool inStock = doc["InStock"].AsBoolean();
DynamoDBNull quantityOnHand = doc["QuantityOnHand"].AsDynamoDBNull();

Para atributos que são do tipo List ou Map, veja a seguir como mapear esses atributos para a API do modelo de documento:

• List: use o método AsDynamoDBList.

• Map: use o método AsDocument.

O exemplo de código a seguir mostra como recuperar um List (RelatedItems) e um Map (Imagens) do Document objeto:

exemplo

DynamoDBList relatedItems = doc["RelatedItems"].AsDynamoDBList();

Document pictures = doc["Pictures"].AsDocument();

Excluindo um item - Tabela. DeleteItem

A operação DeleteItem exclui um item de uma tabela. Você pode transmitir a chave primária do item como um parâmetro. Ou, se você já tiver lido um item e tiver o objeto Document correspondente, será possível transmiti-lo como um parâmetro para o método DeleteItem, conforme mostrado no exemplo de código C# a seguir.

exemplo

Table table = Table.LoadTable(client, "ProductCatalog");

// Retrieve a book (a Document instance)
Document document = table.GetItem(111);

// 1) Delete using the Document instance.
 table.DeleteItem(document);

// 2) Delete using the primary key.
int partitionKey = 222;
table.DeleteItem(partitionKey)

Especificar parâmetros opcionais

Você pode configurar opções adicionais para a operação Delete, adicionando o parâmetro DeleteItemOperationConfig. Para obter uma lista completa de parâmetros opcionais, consulte DeleteTable. O exemplo de código C# a seguir especifica os dois parâmetros opcionais a seguir:

• O parâmetro ConditionalExpression, para garantir que o item de livro que está sendo excluído tenha um valor específico para o atributo ISBN.

• O parâmetro ReturnValues, para solicitar que o método Delete retorne o item excluído.

exemplo

Table table = Table.LoadTable(client, "ProductCatalog");
int partitionKey = 111;

Expression expr = new Expression();
expr.ExpressionStatement = "ISBN = :val";
expr.ExpressionAttributeValues[":val"] = "11-11-11-11";

// Specify optional parameters for Delete operation.
DeleteItemOperationConfig config = new DeleteItemOperationConfig
{
     ConditionalExpression = expr,
     ReturnValues = ReturnValues.AllOldAttributes // This is the only supported value when using the document model.
};

// Delete the book.
Document d = table.DeleteItem(partitionKey, config);

Atualizando um item - Tabela. UpdateItem

A operação UpdateItem atualiza um item existente, se estiver presente. Se o item que tem a chave primária especificada não for encontrado, a operação UpdateItem adicionará um novo item.

É possível usar a operação UpdateItem para atualizar valores de atributos existentes, adicionar novos atributos à coleção existente ou excluir atributos da coleção existente. Forneça essas atualizações ao criar uma instância Document que descreve as atualizações que você deseja realizar.

A ação UpdateItem usa as seguintes diretrizes:

• Se o item não existir, o UpdateItem adicionará um novo item usando a chave primária especificada na entrada.

• Se o item existir, o UpdateItem aplicará as atualizações da seguinte maneira:

  • Substitui os valores de atributos existentes pelos os valores na atualização.

  • Se um atributo que você fornecer na entrada não existir, ele adicionará um novo atributo ao item.

  • Se o valor do atributo de entrada for nulo, ele excluirá os atributos, se estiver presente.

nota

Essa UpdateItem operação de nível médio não suporta a Add ação (consulte UpdateItem) que é suportada pela operação subjacente do DynamoDB.

nota

A operação PutItem operation (Colocando um item - Tabela. PutItem método) também pode realizar uma atualização. Se você chamar PutItem para fazer upload de um item, e a chave primária existir, a operação PutItem substituirá o item inteiro. Se houver atributos no item existente e eles não forem especificados no Document que está sendo inserido, a operação PutItem excluirá esses atributos. No entanto, UpdateItem só atualiza os atributos de entrada especificados. Outros atributos existentes desse item permanecerão inalterados.

Veja a seguir as etapas para atualizar um item usando o modelo de documento do AWS SDK for .NET:

1. Execute o método Table.LoadTable fornecendo o nome da tabela na qual você deseja realizar a operação de atualização.

2. Crie uma instância de Document, fornecendo todas as atualizações que você deseja realizar.

   Para excluir um atributo existente, especifique o valor desse atributo como nulo.

3. Chame o método Table.UpdateItem e forneça a instância Document como um parâmetro de entrada.

   Você deve fornecer a chave primária na instância de Document ou explicitamente como um parâmetro.

O exemplo de código C# a seguir demonstra as tarefas anteriores. O exemplo de código atualiza um item na tabela Book. A operação UpdateItem atualiza o atributo Authors existente, exclui o atributo PageCount e adiciona um novo atributo XYZ. A instância Document inclui a chave primária do livro a ser atualizado.

exemplo

Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();

// Set the attributes that you wish to update.
book["Id"] = 111; // Primary key.
// Replace the authors attribute.
book["Authors"] = new List<string> { "Author x", "Author y" };
// Add a new attribute.
book["XYZ"] = 12345;
// Delete the existing PageCount attribute.
book["PageCount"] = null;

table.Update(book);

Especificar parâmetros opcionais

Você pode configurar opções adicionais para a operação UpdateItem, adicionando o parâmetro UpdateItemOperationConfig. Para obter uma lista completa de parâmetros opcionais, consulte UpdateItem.

O exemplo de código C# a seguir atualiza um preço de item de livro para 25. Ele especifica os dois parâmetros opcionais a seguir:

• O parâmetro ConditionalExpression, que identifica o atributo Price com o valor 20 que você espera que esteja presente.

• O parâmetro ReturnValues para solicitar que a operação UpdateItem retorne o item que está sendo atualizado.

exemplo

Table table = Table.LoadTable(client, "ProductCatalog");
string partitionKey = "111";

var book = new Document();
book["Id"] = partitionKey;
book["Price"] = 25;

Expression expr = new Expression();
expr.ExpressionStatement = "Price = :val";
expr.ExpressionAttributeValues[":val"] = "20";

UpdateItemOperationConfig config = new UpdateItemOperationConfig()
{
    ConditionalExpression = expr,
    ReturnValues = ReturnValues.AllOldAttributes
};

Document d1 = table.Update(book, config);

Gravação em lote - colocar e excluir vários itens

Gravação em lote se refere a inserir e excluir vários itens em um lote. A operação permite que você insira e exclua vários itens de uma ou mais tabelas em uma única chamada. A seguir são descritas as etapas necessária para inserir ou excluir vários itens de uma tabela usando a API do modelo de documento do AWS SDK for .NET.

1. Crie um objeto Table executando o método Table.LoadTable ao fornecer o nome da tabela na qual você deseja executar a operação em lote.

2. Execute o método createBatchWrite na instância de tabela que você criou na etapa anterior e crie um objeto DocumentBatchWrite.

3. Use os métodos de objeto DocumentBatchWrite para especificar os documentos que você deseja carregar ou excluir.

4. Chame o método DocumentBatchWrite.Execute para executar a operação em lote.

   Ao usar a API do modelo de documento, você pode especificar qualquer número de operações em um lote. No entanto, o DynamoDB limita o número de operações em lote e o tamanho total do lote em uma operação em lote. Para obter mais informações sobre os limites específicos, consulte BatchWriteItem. Se a API do modelo de documento detectar que sua solicitação de gravação em lote excedeu o número de solicitações de gravação permitidas ou que o tamanho da carga HTTP de um lote excedeu o limite permitido por BatchWriteItem, ela fragmentará esse lote em vários lotes menores. Além disso, se uma resposta a uma gravação em lote retornar itens não processados, a API do modelo de documento enviará automaticamente outra solicitação em lote com esses itens não processados.

O exemplo de código C# a seguir demonstra as etapas anteriores. O exemplo usa a operação de gravação em lote para realizar duas gravações: fazer upload de um item de livro e excluir outro item de livro.

Table productCatalog = Table.LoadTable(client, "ProductCatalog");
var batchWrite = productCatalog.CreateBatchWrite();

var book1 = new Document();
book1["Id"] = 902;
book1["Title"] = "My book1 in batch write using .NET document model";
book1["Price"] = 10;
book1["Authors"] = new List<string> { "Author 1", "Author 2", "Author 3" };
book1["InStock"] = new DynamoDBBool(true);
book1["QuantityOnHand"] = 5;

batchWrite.AddDocumentToPut(book1);
// specify delete item using overload that takes PK.
batchWrite.AddKeyToDelete(12345);

batchWrite.Execute();

Para obter um exemplo funcional, consulte Exemplo: operações em lote usando a API do modelo de documento do AWS SDK for .NET.

É possível usar a operação batchWrite para realizar operações de inserção e exclusão em várias tabelas. Veja a seguir as etapas para inserir ou excluir vários itens de várias tabelas usando o modelo de documento do AWS SDK for .NET.

1. Crie a instância de DocumentBatchWrite para cada tabela na qual deseja inserir ou excluir vários itens, conforme descrito no procedimento anterior.

2. Crie uma instância de MultiTableDocumentBatchWrite e adicione os objetos DocumentBatchWrite individuais nela.

3. Execute o método MultiTableDocumentBatchWrite.Execute.

O exemplo de código C# a seguir demonstra as etapas anteriores. O exemplo usa a operação de gravação em lote para realizar as seguintes operações de gravação:

• Inserir um novo item no item de tabela Forum.

• Inserir um item na tabela Thread e excluir um item da mesma tabela.

// 1. Specify item to add in the Forum table.
Table forum = Table.LoadTable(client, "Forum");
var forumBatchWrite = forum.CreateBatchWrite();

var forum1 = new Document();
forum1["Name"] = "Test BatchWrite Forum";
forum1["Threads"] = 0;
forumBatchWrite.AddDocumentToPut(forum1);


// 2a. Specify item to add in the Thread table.
Table thread = Table.LoadTable(client, "Thread");
var threadBatchWrite = thread.CreateBatchWrite();

var thread1 = new Document();
thread1["ForumName"] = "Amazon S3 forum";
thread1["Subject"] = "My sample question";
thread1["Message"] = "Message text";
thread1["KeywordTags"] = new List<string>{ "Amazon S3", "Bucket" };
threadBatchWrite.AddDocumentToPut(thread1);

// 2b. Specify item to delete from the Thread table.
threadBatchWrite.AddKeyToDelete("someForumName", "someSubject");

// 3. Create multi-table batch.
var superBatch = new MultiTableDocumentBatchWrite();
superBatch.AddBatch(forumBatchWrite);
superBatch.AddBatch(threadBatchWrite);

superBatch.Execute();