Clase DynamoDBContext - Amazon DynamoDB
CreateMultiTableBatchGetCreateMultiTableBatchWriteCreateBatchGetCreateBatchWriteDeleteDisposeExecuteBatchGetExecuteBatchWriteFromDocumentFromQueryFromScanGetTargetTableCargarConsultarSave (Guardar) ExamenToDocumentEspecificación de parámetros opcionales para DynamoDBContext

Clase DynamoDBContext

La clase DynamoDBContext es el punto de entrada de la base de datos de Amazon DynamoDB. Proporciona conexión con DynamoDB y le permite acceder a los datos de diversas tablas, realizar distintas operaciones CRUD y ejecutar consultas. La clase DynamoDBContext proporciona los métodos siguientes.

CreateMultiTableBatchGet

Crea un objeto MultiTableBatchGet, que consta de varios objetos BatchGet individuales. Cada uno de estos objetos BatchGet se puede usar para recuperar elementos de una sola tabla de DynamoDB.

Para recuperar elementos de una o varias tablas, utilice el método ExecuteBatchGet y pase el objeto MultiTableBatchGet como parámetro.

CreateMultiTableBatchWrite

Crea un objeto MultiTableBatchWrite, que consta de varios objetos BatchWrite individuales. Cada uno de estos objetos BatchWrite se puede usar para escribir o eliminar elementos de una sola tabla de DynamoDB.

Para escribir en una o varias tablas, utilice el método ExecuteBatchWrite y pase el objeto MultiTableBatchWrite como parámetro.

CreateBatchGet

Crea un objeto BatchGet que puede usar para recuperar varios elementos de una tabla. Para obtener más información, consulte Obtención por lotes: obtención de varios elementos .

CreateBatchWrite

Crea un objeto BatchWrite que puede usar para colocar o eliminar varios elementos en una tabla. Para obtener más información, consulte Escritura por lotes: colocación y eliminación de varios elementos .

Delete

Elimina un elemento de la tabla. El método requiere la clave principal del elemento que se desea eliminar. Como parámetro de este método, puede proporcionar el valor de la clave principal o un objeto del lado del cliente que contenga un valor de clave .

  • Si especifica un objeto del lado del cliente como parámetro y ha habilitado el bloqueo optimista, la eliminación se llevará a cabo correctamente solo si las versiones del lado del cliente y del lado del servidor del objeto coinciden.

  • Si especifica únicamente el valor de clave principal como parámetro, la eliminación se llevará a cabo correctamente tanto si ha habilitado bloqueo optimista como si no.

nota

Para ejecutar esta operación en segundo plano, use el método DeleteAsync en su lugar.

Dispose

Elimina todos los recursos administrados y no administrados.

ExecuteBatchGet

Lee datos en una o varias tablas y procesa todos los objetos BatchGet de un objeto MultiTableBatchGet.

nota

Para ejecutar esta operación en segundo plano, use el método ExecuteBatchGetAsync en su lugar.

ExecuteBatchWrite

Escribe o elimina datos en una o varias tablas y procesa todos los objetos BatchWrite de un objeto MultiTableBatchWrite.

nota

Para ejecutar esta operación en segundo plano, use el método ExecuteBatchWriteAsync en su lugar.

FromDocument

Dada una instancia de un objeto Document, el método FromDocument devuelve una instancia de una clase del lado del cliente.

Esto resulta útil si desea utilizar las clases del modelo de documento junto con el modelo de persistencia de objetos para realizar operaciones con datos. Para obtener más información sobre las clases del modelo de documentos que se proporcionan en AWS SDK for .NET, consulte .NET: modelo de documento.

Supongamos que tiene un objeto Document denominado doc que contiene una representación de un elemento Forum. (Para saber cómo construir este objeto, consulte la descripción del método ToDocument más adelante en este tema). Puede utilizar FromDocument para recuperar el elemento Forum del Document como se muestra en el siguiente ejemplo de código C#.

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

Si el objeto Document implementa la interfaz IEnumerable, puede usar el método FromDocuments en su lugar. Esto le permitirá recorrer en iteración todas las instancias de la clase contenidas en Document.

FromQuery

Ejecuta una operación Query con los parámetros de la consulta definidos en un objeto QueryOperationConfig.

nota

Para ejecutar esta operación en segundo plano, use el método FromQueryAsync en su lugar.

FromScan

Ejecuta una operación Scan con los parámetros del análisis definidos en un objeto ScanOperationConfig.

nota

Para ejecutar esta operación en segundo plano, use el método FromScanAsync en su lugar.

GetTargetTable

Recupera la tabla de destino del tipo especificado. Esto resulta útil si va a escribir un convertidor personalizado para mapear datos arbitrarios a una tabla de DynamoDB y tiene que determinar qué tabla está asociada con un tipo de datos personalizado.

Cargar

Recupera un elemento de una tabla. El método requiere solo la clave principal del elemento que se desea recuperar.

De forma predeterminada, DynamoDB devuelve el elemento con valores que presentan consistencia final. Para obtener más información sobre el modelo de consistencia final, consulte Coherencia de lectura.

El método Load o LoadAsync llama a la operación GetItem, que requiere que especifique la clave principal de la tabla. Como GetItem omite el parámetro IndexName, no puede cargar un elemento con la partición o la clave de clasificación de un índice. Por lo tanto, debe utilizar la clave principal de la tabla para cargar un elemento.

nota

Para ejecutar esta operación en segundo plano, use el método LoadAsync en su lugar. Para ver un ejemplo del uso del método LoadAsync para realizar operaciones CRUD de alto nivel en una tabla de DynamoDB, consulte el siguiente ejemplo.


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

Consultar

Consulta una tabla basándose en los parámetros de consulta que haya proporcionado.

Solo se puede consultar una tabla si cuenta con una clave principal compuesta (una clave de partición y una clave de ordenación). Al realizar la consulta, debe especificar una clave de partición y una condición que se aplica a la clave de ordenación.

Supongamos que tenemos una clase Reply del lado del cliente mapeada a la tabla Reply de DynamoDB. En el siguiente ejemplo de código C# se consulta la tabla Reply para buscar las respuestas de las conversaciones de un foro publicadas en los últimos 15 días. La tabla Reply tiene una clave principal cuya clave de partición es Id y cuya clave de ordenación es ReplyDateTime. Para obtener más información sobre la tabla Reply, consulte Creación de tablas y carga de datos para ejemplos de código en DynamoDB.

ejemplo 
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);

Devuelve una colección de objetos Reply.

El método Query devuelve una colección IEnumerable de "carga diferida". Inicialmente devuelve una sola página de resultados y, a continuación, realiza una llamada de servicio para obtener la página siguiente si es necesario. Para obtener todos los elementos coincidentes, solo tiene que recorrer en iteración el IEnumerable.

Si la tabla tiene una clave principal simple (clave de partición), no puede usar el método Query. En su lugar, puede usar el método Load y proporcionar la clave de partición para recuperar el elemento.

nota

Para ejecutar esta operación en segundo plano, use el método QueryAsync en su lugar.

Save (Guardar)

Guarda el objeto especificado en la tabla. Si la clave principal especificada en el objeto de entrada no existe en la tabla, el método agrega un nuevo elemento a la tabla. Si la clave principal sí está presente, el método actualiza el elemento.

Si ha configurado el bloqueo optimista, la actualización solo se llevará a cabo correctamente si las versiones del elemento del lado del cliente y del lado del servidor coinciden. Para obtener más información, consulte Bloqueo positivo mediante un número de versión con DynamoDB mediante el modelo de persistencia de objetos de AWS SDK for .NET.

nota

Para ejecutar esta operación en segundo plano, use el método SaveAsync en su lugar.

Examen

Realiza un examen de toda la tabla.

Puede filtrar el resultado del examen especificando una condición de examen. La condición se puede evaluar según cualesquiera atributos de la tabla. Supongamos que tenemos una clase Book del lado del cliente mapeada a la tabla ProductCatalog de DynamoDB. En el siguiente ejemplo de código C# se examina la tabla y se devuelven solamente aquellos elementos de libro cuyo precio es menor que 0.

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

El método Scan devuelve una colección IEnumerable de "carga diferida". Inicialmente devuelve una sola página de resultados y, a continuación, realiza una llamada de servicio para obtener la página siguiente si es necesario. Para obtener todos los elementos coincidentes, solo tiene que recorrer en iteración la colección IEnumerable.

Por motivos de desempeño, debe consultar las tablas y evitar examinarlas.

nota

Para ejecutar esta operación en segundo plano, use el método ScanAsync en su lugar.

ToDocument

Devuelve una instancia de la clase Document del modelo de documento de la instancia de clase.

Esto resulta útil si desea utilizar las clases del modelo de documento junto con el modelo de persistencia de objetos para realizar operaciones con datos. Para obtener más información sobre las clases del modelo de documentos que se proporcionan en AWS SDK for .NET, consulte .NET: modelo de documento.

Supongamos que tenemos una clase del lado del cliente mapeada al ejemplo de tabla Forum. Puede usar una DynamoDBContext para obtener un elemento, como un objeto Document, de la tabla Forum, como se muestra en el siguiente ejemplo de código C#.

ejemplo 
DynamoDBContext context = new DynamoDBContext(client);

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

Especificación de parámetros opcionales para DynamoDBContext

Cuando se utiliza el modelo de persistencia de objetos, es posible especificar los siguientes parámetros opcionales para la clase DynamoDBContext.

  • ConsistentRead: cuando se recuperan datos utilizando las operaciones Load, Query o Scan, es posible agregar este parámetro si se desea para solicitar los valores más recientes de los datos.

  • IgnoreNullValues: este parámetro informa a DynamoDBContext de que debe pasar por alto los valores null de los atributos durante una operación Save. Si este parámetro es false (o, si no se ha establecido), entonces un valor null se interpretará como una instrucción de eliminar el atributo de que se trate.

  • SkipVersionCheck: este parámetro informa a DynamoDBContext de que no debe comparar las versiones al guardar o eliminar un elemento. Para obtener más información sobre el control de versiones, consulte Bloqueo positivo mediante un número de versión con DynamoDB mediante el modelo de persistencia de objetos de AWS SDK for .NET.

  • TableNamePrefix: antepone una cadena determinada a los nombres de todas las tablas. Si este parámetro es null (o si no se ha establecido), no se utilizará ningún prefijo.

  • DynamoDBEntryConversion: especifica el esquema de conversión que utiliza el cliente. Puede establecer este parámetro en la versión V1 o V2. V1 es la versión predeterminada.

    En función de la versión que establezca, el comportamiento de este parámetro cambia. Por ejemplo:

    • En V1, el tipo de datos bool se convierte al tipo numérico N, donde 0 representa falso y 1 representa verdadero. En V2, bool se convierte en BOOL.

    • En V2, las listas y las matrices no se agrupan con los HashSets. Las listas y las matrices de números, tipos basados en cadenas y tipos basados en binarios se convierten al tipo L (Lista), que se puede enviar vacío para actualizar una lista. A diferencia de V1, en la que no se envía una lista vacía por cable.

      En V1, los tipos de recopilaciones, como List, HashSet y matrices, se tratan de la misma manera. La lista, el HashSet y la matriz de números se convierten al tipo NS (conjunto de números).

    El siguiente ejemplo establece la versión del esquema de conversión en V2, lo que cambia el comportamiento de conversión entre los tipos .NET y los tipos de datos de DynamoDB.

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

En los siguientes fragmentos de código C# se crea un nuevo DynamoDBContext especificando dos de los parámetros opcionales anteriores, ConsistentRead y SkipVersionCheck.

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

DynamoDBContext incluye estos parámetros opcionales con cada solicitud que se envía utilizando este contexto.

En lugar de establecer estos parámetros en el nivel de DynamoDBContext, puede especificarlos para las operaciones individuales que ejecute utilizando DynamoDBContext, como se muestra en el siguiente ejemplo de código C#. En el ejemplo se carga un elemento de libro concreto. El método Load de DynamoDBContext especifica los parámetros opcionales ConsistentRead y SkipVersionCheck.

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

En este caso, DynamoDBContext incluye estos parámetros solo cuando se envía la solicitud Get.