As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
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.
Tópicos
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 DescribeTable
que 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.
-
Execute o método
Table.LoadTable
que fornece o nome da tabela na qual você deseja inserir um item. -
Crie um objeto
Document
que tenha uma lista de nomes de atributos e seus valores. -
Execute
Table.PutItem
fornecendo a instânciaDocument
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 Number
String
,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 atributoISBN
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étodoAsDynamoDBList
. -
Map
: use o métodoAsDocument
.
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étodoDelete
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:
-
Execute o método
Table.LoadTable
fornecendo o nome da tabela na qual você deseja realizar a operação de atualização. -
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.
-
Chame o método
Table.UpdateItem
e forneça a instânciaDocument
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 atributoPrice
com o valor20
que você espera que esteja presente. -
O parâmetro
ReturnValues
para solicitar que a operaçãoUpdateItem
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.
-
Crie um objeto
Table
executando o métodoTable.LoadTable
ao fornecer o nome da tabela na qual você deseja executar a operação em lote. -
Execute o método
createBatchWrite
na instância de tabela que você criou na etapa anterior e crie um objetoDocumentBatchWrite
. -
Use os métodos de objeto
DocumentBatchWrite
para especificar os documentos que você deseja carregar ou excluir. -
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.
-
Crie a instância de
DocumentBatchWrite
para cada tabela na qual deseja inserir ou excluir vários itens, conforme descrito no procedimento anterior. -
Crie uma instância de
MultiTableDocumentBatchWrite
e adicione os objetosDocumentBatchWrite
individuais nela. -
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();