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á.
Como usar os bancos de dados NoSQL Amazon DynamoDB
nota
Os modelos de programação nesses tópicos estão presentes tanto no .NET Framework quanto no .NET (Core), mas as convenções de chamada diferem, sejam síncronas ou assíncronas.
O AWS SDK for .NET suporta o Amazon DynamoDB, que é um serviço rápido de banco de dados NoSQL oferecido pela. AWS O SDK fornece três módulos de programação para comunicar-se com o DynamoDB: o modelo de baixo nível, o modelo de documento e o modelo de persistência de objetos.
A informações a seguir apresentam esses modelos e suas APIs, fornecem exemplos de como e quando usá-los e links para recursos de programação adicionais do DynamoDB no AWS SDK for .NET.
Tópicos
Modelo de baixo nível
O modelo de programação de baixo nível envolve chamadas diretas para o serviço do DynamoDB. Você acessa esse modelo pelo namespace Amazon.DynamoDBv2.
Dos três modelos, o de baixo nível é o que exige que você escreva mais código. Por exemplo, você deve converter tipos de dados .NET para seus equivalentes no DynamoDB. Contudo, esse modelo fornece acesso à maioria dos recursos.
Os exemplos a seguir mostram como usar o modelo de baixo nível para criar ou modificar uma tabela e inserir itens em uma tabela no DynamoDB.
Criar uma tabela
No exemplo a seguir, você cria uma tabela usando o método CreateTable
da classe AmazonDynamoDBClient
. O método CreateTable
usa uma instância da classe CreateTableRequest
que contém características como nomes de atributo do item obrigatório, definição de chave primária e a capacidade de transferência. O método CreateTable
retorna uma instância da classe CreateTableResponse
.
// using Amazon.DynamoDBv2; // using Amazon.DynamoDBv2.Model; var client = new AmazonDynamoDBClient(); Console.WriteLine("Getting list of tables"); List<string> currentTables = client.ListTables().TableNames; Console.WriteLine("Number of tables: " + currentTables.Count); if (!currentTables.Contains("AnimalsInventory")) { var request = new CreateTableRequest { TableName = "AnimalsInventory", AttributeDefinitions = new List<AttributeDefinition> { new AttributeDefinition { AttributeName = "Id", // "S" = string, "N" = number, and so on. AttributeType = "N" }, new AttributeDefinition { AttributeName = "Type", AttributeType = "S" } }, KeySchema = new List<KeySchemaElement> { new KeySchemaElement { AttributeName = "Id", // "HASH" = hash key, "RANGE" = range key. KeyType = "HASH" }, new KeySchemaElement { AttributeName = "Type", KeyType = "RANGE" }, }, ProvisionedThroughput = new ProvisionedThroughput { ReadCapacityUnits = 10, WriteCapacityUnits = 5 }, }; var response = client.CreateTable(request); Console.WriteLine("Table created with request ID: " + response.ResponseMetadata.RequestId); }
Verificação de que uma tabela está pronta para ser modificada
Antes que você possa alterar ou modificar uma tabela, esta tem de estar pronta para modificação. O exemplo a seguir mostra como usar o modelo de baixo nível para verificar se uma tabela do DynamoDB está pronta. Neste exemplo, a tabela de destino a ser verificada é mencionada pelo método DescribeTable
da classe AmazonDynamoDBClient
. A cada cinco segundos, o código verifica o valor da propriedade TableStatus
da tabela. Quando o status é definido como ACTIVE
, a tabela está pronta para ser modificada.
// using Amazon.DynamoDBv2; // using Amazon.DynamoDBv2.Model; var client = new AmazonDynamoDBClient(); var status = ""; do { // Wait 5 seconds before checking (again). System.Threading.Thread.Sleep(TimeSpan.FromSeconds(5)); try { var response = client.DescribeTable(new DescribeTableRequest { TableName = "AnimalsInventory" }); Console.WriteLine("Table = {0}, Status = {1}", response.Table.TableName, response.Table.TableStatus); status = response.Table.TableStatus; } catch (ResourceNotFoundException) { // DescribeTable is eventually consistent. So you might // get resource not found. } } while (status != TableStatus.ACTIVE);
Introdução um item em uma tabela
No exemplo a seguir, você usa o modelo de baixo nível para inserir dois itens em uma tabela do DynamoDB. Cada item é inserido pelo método PutItem
da classe AmazonDynamoDBClient
usando uma instância da classe PutItemRequest
. Cada uma das duas instâncias da classe PutItemRequest
pega o nome da tabela em que os itens serão introduzidos, com uma série de valores de atributos de item.
// using Amazon.DynamoDBv2; // using Amazon.DynamoDBv2.Model; var client = new AmazonDynamoDBClient(); var request1 = new PutItemRequest { TableName = "AnimalsInventory", Item = new Dictionary<string, AttributeValue> { { "Id", new AttributeValue { N = "1" }}, { "Type", new AttributeValue { S = "Dog" }}, { "Name", new AttributeValue { S = "Fido" }} } }; var request2 = new PutItemRequest { TableName = "AnimalsInventory", Item = new Dictionary<string, AttributeValue> { { "Id", new AttributeValue { N = "2" }}, { "Type", new AttributeValue { S = "Cat" }}, { "Name", new AttributeValue { S = "Patches" }} } }; client.PutItem(request1); client.PutItem(request2);
Modelo de documento
O modelo de programação de documento oferece uma maneira mais fácil para trabalhar com dados dentro do DynamoDB. Esse modelo é destinado especificamente a acessar tabelas e itens nas tabelas. Você acessa esse modelo por meio do Amazon.DynamoDBV2. DocumentModelnamespace.
Em comparação com o modelo de programação de baixo nível, o modelo de documento é mais fácil de codificar em relação aos dados do DynamoDB. Por exemplo, não é necessário converter tantos tipos de dados .NET em seus equivalentes no DynamoDB. Contudo, esse modelo não fornece acesso a tantos recursos como o modelo de programação de baixo nível. Por exemplo, você pode usar esse modelo para criar, recuperar, atualizar e excluir itens nas tabelas. No entanto, para criar as tabelas, é preciso usar o módulo de baixo nível. Em comparação com o modelo de persistência de objetos, este modelo exige que você grave mais código para armazenar, carregar e consultar objetos .NET.
Para obter mais informações sobre o modelo de programação de documentos do DynamoDB, consulte .NET: modelo de documento no Amazon DynamoDB Developer Guide.
As seções a seguir fornecem informações sobre como criar uma representação da tabela desejada do DynamoDB e exemplos sobre como usar o modelo de documento para inserir itens em tabelas e obter itens de tabelas.
Criar uma representação da tabela
Para realizar operações de dados usando o modelo de documento, você deve primeiro criar uma instância da classe Table
que representa uma tabela específica. Há duas maneiras Principais de fazer isso:
LoadTable método
O primeiro mecanismo é usar um dos métodos estáticos LoadTable
da classe Table
, semelhante ao exemplo a seguir:
var client = new AmazonDynamoDBClient(); Table table = Table.LoadTable(client, "Reply");
nota
Embora esse mecanismo funcione, em determinadas condições, ele às vezes pode resultar em latência ou bloqueios adicionais devido aos comportamentos de inicialização a frio e de thread-pool. Para obter mais informações sobre esses comportamentos, consulte a postagem do blog Padrões aprimorados de inicialização do DynamoDB para o AWS SDK for .NET
TableBuilder
Um mecanismo alternativo, a TableBuilder
classe, foi introduzido na versão 3.7.203 do pacote .DynamoDBv2DescribeTable
. Esse mecanismo é usado de maneira semelhante ao seguinte exemplo:
var client = new AmazonDynamoDBClient(); var table = new TableBuilder(client, "Reply") .AddHashKey("Id", DynamoDBEntryType.String) .AddRangeKey("ReplyDateTime", DynamoDBEntryType.String) .AddGlobalSecondaryIndex("PostedBy-Message-index", "Author", DynamoDBEntryType.String, "Message", DynamoDBEntryType.String) .Build();
Para obter mais informações sobre esse mecanismo alternativo, consulte novamente a postagem do blog Padrões aprimorados de inicialização do DynamoDB para o AWS SDK for .NET
Introdução de um item em uma tabela
No exemplo a seguir, um item é introduzido na tabela de respostas por maio do método PutItemAsync
da classe Table
. O método PutItemAsync
leva uma instância da classe Document
; a classe Document
é simplesmente uma coleção de atributos inicializados.
using Amazon.DynamoDBv2; using Amazon.DynamoDBv2.DocumentModel; // Create a representation of the "Reply" table // by using one of the mechanisms described previously. // Then, add a reply to the table. var newReply = new Document(); newReply["Id"] = Guid.NewGuid().ToString(); newReply["ReplyDateTime"] = DateTime.UtcNow; newReply["PostedBy"] = "Author1"; newReply["Message"] = "Thank you!"; await table.PutItemAsync(newReply);
Obtendo um item de uma tabela
No exemplo a seguir, uma resposta é recuperada pelo método GetItemAsync
da classe Table
. Para determinar a resposta a ser obtida, o GetItemAsync
método usa a chave hash-and-range primária da resposta de destino.
using Amazon.DynamoDBv2; using Amazon.DynamoDBv2.DocumentModel; // Create a representation of the "Reply" table // by using one of the mechanisms described previously. // Then, get a reply from the table // where "guid" is the hash key and "datetime" is the range key. var reply = await table.GetItemAsync(guid, datetime); Console.WriteLine("Id = " + reply["Id"]); Console.WriteLine("ReplyDateTime = " + reply["ReplyDateTime"]); Console.WriteLine("PostedBy = " + reply["PostedBy"]); Console.WriteLine("Message = " + reply["Message"]);
O exemplo anterior converte implicitamente valores de tabela em strings para o método WriteLine
. Você pode fazer conversões explícitas usando os vários métodos de “As[type]” da classe DynamoDBEntry
. Por exemplo, você pode converter explicitamente o valor para o Id
a partir do tipo de dado Primitive
para um GUID por meio do método AsGuid()
:
var guid = reply["Id"].AsGuid();
Modelo de persistência de objeto
O modelo de programação de persistência de objetos é especificamente projetado para armazenar, carregar e consultar objetos .NET no DynamoDB. Você acessa esse modelo por meio do Amazon.DynamoDBV2. DataModelnamespace.
Dos três modelos, o modelo de persistência de objetos é o mais fácil de codificar sempre que estiver armazenando, carregando ou consultando dados do DynamoDB. Por exemplo, você trabalha diretamente com os tipos de dados do DynamoDB. Contudo, este modelo fornece acesso somente a operações que armazenam, carregam e consultam objetos .NET no DynamoDB. Por exemplo, você pode usar esse modelo para criar, recuperar, atualizar e excluir itens nas tabelas. No entanto, é preciso primeiro criar suas tabelas usando o modelo de baixo nível e, em seguida, usar esse modelo para mapear suas classes .NET para as tabelas.
Para obter mais informações sobre o modelo de programação de persistência de objetos do DynamoDB, consulte .NET: modelo de persistência de objetos no Guia do desenvolvedor do Amazon DynamoDB.
Os exemplos a seguir mostram como definir uma classe .NET que representa um item DynamoDB, usa uma instância da classe .NET para inserir um item no DynamoDB e usa uma instância de uma classe .NET para obter um item de uma tabela.
Definindo uma classe .NET que represente um item em uma tabela
No exemplo a seguir de uma definição de classe, o DynamoDBTable
atributo especifica o nome da tabela, enquanto os DynamoDBRangeKey
atributos DynamoDBHashKey
e modelam a chave hash-and-range primária da tabela. O atributo DynamoDBGlobalSecondaryIndexHashKey
é definido para que uma consulta de respostas de um autor específico possa ser construída.
using Amazon.DynamoDBv2; using Amazon.DynamoDBv2.DataModel; [DynamoDBTable("Reply")] public class Reply { [DynamoDBHashKey] public string Id { get; set; } [DynamoDBRangeKey(StoreAsEpoch = false)] public DateTime ReplyDateTime { get; set; } [DynamoDBGlobalSecondaryIndexHashKey("PostedBy-Message-Index", AttributeName ="PostedBy")] public string Author { get; set; } [DynamoDBGlobalSecondaryIndexRangeKey("PostedBy-Message-Index")] public string Message { get; set; } }
Criando um contexto para o modelo de persistência de objetos
Para usar o modelo de programação de persistência de objetos para o DynamoDB, você deve criar um contexto que forneça uma conexão ao DynamoDB e permita acessar tabelas, e realizar diversas operações e executar consultas.
Contexto básico
O exemplo de código a seguir mostra como criar o contexto mais básico.
using Amazon.DynamoDBv2; using Amazon.DynamoDBv2.DataModel; var client = new AmazonDynamoDBClient(); var context = new DynamoDBContext(client);
Contexto com DisableFetchingTableMetadata propriedade
O exemplo a seguir mostra como você também pode definir a propriedade DisableFetchingTableMetadata
da classe DynamoDBContextConfig
para evitar chamadas implícitas ao método DescribeTable
.
using Amazon.DynamoDBv2; using Amazon.DynamoDBv2.DataModel; var client = new AmazonDynamoDBClient(); var context = new DynamoDBContext(client, new DynamoDBContextConfig { DisableFetchingTableMetadata = true });
Se a propriedade DisableFetchingTableMetadata
estiver definida como false
(o padrão), conforme mostrado no primeiro exemplo, você poderá omitir os atributos que descrevem a estrutura de chave e índice dos itens da tabela da classe Reply
. Em vez disso, esses atributos serão inferidos por meio de uma chamada implícita ao método DescribeTable
. Se o DisableFetchingTableMetadata
for definido como true
, conforme mostrado no segundo exemplo, métodos do modelo de persistência de objetos, como o SaveAsync
e o QueryAsync
depende inteiramente dos atributos definidos na classe Reply
. Nesse caso, uma chamada para o método DescribeTable
não ocorre.
nota
Sob certas condições, as chamadas para o método DescribeTable
às vezes podem levar a latência ou bloqueios adicionais devido aos comportamentos de inicialização a frio e thread-pool. Por esse motivo, às vezes é vantajoso evitar chamadas para esse método.
Para obter mais informações sobre esses comportamentos, consulte a postagem do blog Padrões aprimorados de inicialização do DynamoDB para o AWS SDK for .NET
Usando uma instância da classe .NET para inserir um item em uma tabela
Neste exemplo, um item é inserido pelo método SaveAsync
da classe DynamoDBContext
, que recebe uma instância inicializada da classe .NET que representa o item.
using Amazon.DynamoDBv2; using Amazon.DynamoDBv2.DataModel; // Create an appropriate context for the object persistence programming model, // examples of which have been described earlier. // Create an object that represents the new item. var reply = new Reply() { Id = Guid.NewGuid().ToString(), ReplyDateTime = DateTime.UtcNow, Author = "Author1", Message = "Thank you!" }; // Insert the item into the table. await context.SaveAsync<Reply>(reply, new DynamoDBOperationConfig { IndexName = "PostedBy-Message-index" });
Usando uma instância de um objeto .NET para obter itens de uma tabela
Neste exemplo, uma consulta é criada para encontrar todos os registros de “Author1” usando o método QueryAsync
da classe DynamoDBContext
. Em seguida, os itens são recuperados por meio do método GetNextSetAsync
de consulta.
using Amazon.DynamoDBv2; using Amazon.DynamoDBv2.DataModel; // Create an appropriate context for the object persistence programming model, // examples of which have been described earlier. // Construct a query that finds all replies by a specific author. var query = context.QueryAsync<Reply>("Author1", new DynamoDBOperationConfig { IndexName = "PostedBy-Message-index" }); // Display the result. var set = await query.GetNextSetAsync(); foreach (var item in set) { Console.WriteLine("Id = " + item.Id); Console.WriteLine("ReplyDateTime = " + item.ReplyDateTime); Console.WriteLine("PostedBy = " + item.Author); Console.WriteLine("Message = " + item.Message); }
Informações adicionais sobre o modelo de persistência de objetos
Os exemplos e explicações mostrados acima às vezes incluem uma propriedade da classe DynamoDBContext
chamada DisableFetchingTableMetadata
. Essa propriedade, que foi introduzida na versão 3.7.203 do NuGet pacote AWSSDK .dynamoDBv2
A seguir, algumas informações adicionais sobre essa propriedade.
-
Essa propriedade pode ser definida globalmente em seu arquivo
app.config
ouweb.config
se estiver usando o .NET Framework. -
Essa propriedade pode ser definida globalmente usando a classe
AWSConfigsDynamoDB
, como mostra o exemplo a seguir.// Set the DisableFetchingTableMetadata property globally // before constructing any context objects. AWSConfigsDynamoDB.Context.DisableFetchingTableMetadata = true; var client = new AmazonDynamoDBClient(); var context = new DynamoDBContext(client);
-
Em alguns casos, você não pode adicionar atributos do DynamoDB a uma classe .NET, por exemplo, se a classe estiver definida em uma dependência. Nesses casos, ainda é possível aproveitar a propriedade
DisableFetchingTableMetadata
. Para fazer isso, use a classeTableBuilder
além da propriedadeDisableFetchingTableMetadata
. ATableBuilder
classe também foi introduzida na versão 3.7.203do pacote .DynamoDBV2. AWSSDK NuGet // Set the DisableFetchingTableMetadata property globally // before constructing any context objects. AWSConfigsDynamoDB.Context.DisableFetchingTableMetadata = true; var client = new AmazonDynamoDBClient(); var context = new DynamoDBContext(client); var table = new TableBuilder(client, "Reply") .AddHashKey("Id", DynamoDBEntryType.String) .AddRangeKey("ReplyDateTime", DynamoDBEntryType.String) .AddGlobalSecondaryIndex("PostedBy-Message-index", "Author", DynamoDBEntryType.String, "Message", DynamoDBEntryType.String) .Build(); // This registers the "Reply" table we constructed via the builder. context.RegisterTableDefinition(table); // Now operations like this will work, // even if the Reply class was not annotated with this index. var query = context.QueryAsync<Reply>("Author1", new DynamoDBOperationConfig() { IndexName = "PostedBy-Message-index" });
Mais informações
Usando o AWS SDK for .NET para programar informações e exemplos do DynamoDB**
Informações e exemplos do modelo de baixo nível
-
Trabalhando com tabelas usando a API AWS SDK for .NET de baixo nível
-
Trabalhando com itens usando a API AWS SDK for .NET de baixo nível
-
Consultando tabelas usando a API de AWS SDK for .NET baixo nível
-
Digitalizando tabelas usando a API AWS SDK for .NET de baixo nível
-
Trabalhando com índices secundários locais usando a API AWS SDK for .NET de baixo nível
-
Trabalhando com índices secundários globais usando a API AWS SDK for .NET de baixo nível
Informações e exemplos do modelo de documentos
Informações e exemplos de modelo de persistência de objetos