# Uso de elementos: .NET Puede usar la API de bajo nivel AWS SDK para .NET para realizar operaciones típicas de creación, lectura, actualización y eliminación (CRUD, por sus siglas en inglés) en los elementos de una tabla. A continuación se indican los pasos que suelen llevarse a cabo para realizar operaciones CRUD a los datos mediante la API de bajo nivel de .NET: 1. Cree una instancia de la clase `AmazonDynamoDBClient` (el cliente). 1. Proporcione los parámetros requeridos específicos de la operación en el objeto de solicitud correspondiente. Por ejemplo, use el objeto de solicitud `PutItemRequest` para cargar un elemento y el objeto de solicitud `GetItemRequest` para recuperar un elemento existente. Puede usar el objeto de solicitud para proporcionar los parámetros necesarios y opcionales. 1. Ejecute el método apropiado proporcionado por el cliente pasándolo en el objeto de solicitud que ha creado en el paso anterior. El cliente `AmazonDynamoDBClient` proporciona los métodos `PutItem`, `GetItem`, `UpdateItem` y `DeleteItem` para las operaciones CRUD. **Topics** + [Colocación de un elemento](#PutItemLowLevelAPIDotNet) + [Obtención de un elemento](#GetItemLowLevelDotNET) + [Actualización de un elemento](#UpdateItemLowLevelDotNet) + [Contador atómico](#AtomicCounterLowLevelDotNet) + [Eliminación de un elemento](#DeleteMidLevelDotNet) + [Escritura por lotes: colocación y eliminación de varios elementos](#BatchWriteLowLevelDotNet) + [Obtención por lotes: obtención de varios elementos](#BatchGetLowLevelDotNet) + [Ejemplo: operaciones CRUD con la API de bajo nivel de AWS SDK para .NET](LowLevelDotNetItemsExample.md) + [Ejemplo: operaciones por lotes con la API de bajo nivel de AWS SDK para .NET](batch-operation-lowlevel-dotnet.md) + [Ejemplo: control de atributos de tipo binario mediante la API de bajo nivel de AWS SDK para .NET](LowLevelDotNetBinaryTypeExample.md) ## Colocación de un elemento El método `PutItem` carga un elemento en una tabla. Si el elemento existe, sustituye el elemento completo. **nota** En lugar de ello, si prefiere actualizar solamente algunos atributos concretos, puede usar el método `UpdateItem`. Para obtener más información, consulte [Actualización de un elemento](#UpdateItemLowLevelDotNet). A continuación se indican los pasos que hay que seguir para cargar un elemento mediante la API de bajo nivel del SDK para .NET: 1. Cree una instancia de la clase `AmazonDynamoDBClient`. 1. Cree una instancia de la clase `PutItemRequest` para proporcionar los parámetros requeridos. Para colocar un elemento, debe proporcionar el nombre de la tabla y el elemento. 1. Ejecute el método `PutItem` proporcionando el objeto `PutItemRequest` que creó en el paso anterior. En el siguiente ejemplo de C\$1 se ponen en práctica los pasos anteriores. En el ejemplo se carga un elemento en la tabla `ProductCatalog`. **Example** ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new PutItemRequest { TableName = tableName, Item = new Dictionary() { { "Id", new AttributeValue { N = "201" }}, { "Title", new AttributeValue { S = "Book 201 Title" }}, { "ISBN", new AttributeValue { S = "11-11-11-11" }}, { "Price", new AttributeValue { S = "20.00" }}, { "Authors", new AttributeValue { SS = new List{"Author1", "Author2"} } } } }; client.PutItem(request); ``` En el ejemplo anterior, hemos cargado un elemento de libro que tiene los atributos `Id`, `Title`, `ISBN` y `Authors`. Tenga en cuenta `Id` es un atributo de tipo numérico y demás son de cadena. Autores es un conjunto `String`. ### Especificación de parámetros opcionales También puede usar el objeto `PutItemRequest` para proporcionar parámetros opcionales, como se muestra en el siguiente ejemplo de código C\$1. En el ejemplo se especifican los parámetros opcionales siguientes: + `ExpressionAttributeNames`, `ExpressionAttributeValues` y `ConditionExpression` especifican que el elemento existente se puede sustituir únicamente si su atributo ISBN tiene un valor específico. + `ReturnValues`El parámetro para solicitar el elemento anterior en la respuesta. **Example** ``` var request = new PutItemRequest { TableName = tableName, Item = new Dictionary() { { "Id", new AttributeValue { N = "104" }}, { "Title", new AttributeValue { S = "Book 104 Title" }}, { "ISBN", new AttributeValue { S = "444-4444444444" }}, { "Authors", new AttributeValue { SS = new List{"Author3"}}} }, // Optional parameters. ExpressionAttributeNames = new Dictionary() { {"#I", "ISBN"} }, ExpressionAttributeValues = new Dictionary() { {":isbn",new AttributeValue {S = "444-4444444444"}} }, ConditionExpression = "#I = :isbn" }; var response = client.PutItem(request); ``` Para obtener más información, consulte [PutItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html). ## Obtención de un elemento El método `GetItem` recupera un elemento. **nota** Para recuperar varios elementos, puede usar el método `BatchGetItem`. Para obtener más información, consulte [Obtención por lotes: obtención de varios elementos](#BatchGetLowLevelDotNet). A continuación se indican los pasos que hay que seguir para recuperar un elemento existente mediante la API de bajo nivel de AWS SDK para .NET. 1. Cree una instancia de la clase `AmazonDynamoDBClient`. 1. Cree una instancia de la clase `GetItemRequest` para proporcionar los parámetros requeridos. Para obtener un elemento, debe proporcionar el nombre de la tabla y la clave principal del elemento. 1. Ejecute el método `GetItem` proporcionando el objeto `GetItemRequest` que creó en el paso anterior. En el siguiente ejemplo de C\$1 se ponen en práctica los pasos anteriores. En el siguiente ejemplo se recupera un elemento de la tabla `ProductCatalog`. ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new GetItemRequest { TableName = tableName, Key = new Dictionary() { { "Id", new AttributeValue { N = "202" } } }, }; var response = client.GetItem(request); // Check the response. var result = response.GetItemResult; var attributeMap = result.Item; // Attribute list in the response. ``` ### Especificación de parámetros opcionales También puede usar el objeto `GetItemRequest` para proporcionar parámetros opcionales, como se muestra en el siguiente ejemplo de código C\$1. En el ejemplo se especifican los parámetros opcionales siguientes: + `ProjectionExpression`El parámetro para especificar los atributos que se van a recuperar. + `ConsistentRead`El parámetro para realizar una lectura de consistencia alta. Para obtener más información sobre la consistencia de lectura, consulte [Coherencia de lectura de DynamoDB](HowItWorks.ReadConsistency.md). **Example** ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new GetItemRequest { TableName = tableName, Key = new Dictionary() { { "Id", new AttributeValue { N = "202" } } }, // Optional parameters. ProjectionExpression = "Id, ISBN, Title, Authors", ConsistentRead = true }; var response = client.GetItem(request); // Check the response. var result = response.GetItemResult; var attributeMap = result.Item; ``` Para obtener más información, consulte [GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html). ## Actualización de un elemento El método `UpdateItem` actualiza un elemento si existe. Puede usar la operación `UpdateItem` para actualizar los valores de atributos presentes, agregar atributos nuevos o eliminarlos de la colección existente. Si el elemento que tiene clave principal especificada no se encuentra, se agrega un nuevo elemento. La operación `UpdateItem` se rige por las directrices siguientes: + Si el elemento no existe, `UpdateItem` agrega un elemento nuevo utilizando la clave principal especificada en la información de entrada. + Si el elemento existe, `UpdateItem` aplica las actualizaciones como se indica a continuación: + Sustituye los valores de los atributos existentes por los valores de la actualización. + Si el atributo que se proporciona en la información de entrada no existe, agrega un nuevo atributo al elemento. + Si el atributo de entrada es null, elimina el atributo, en caso de que esté presente. + Si se utiliza `ADD` para `Action`, puede agregar valores a un conjunto existente (de tipo String Set o Number Set) o bien sumar (si se usa un número positivo) o restar (si se usa un número negativo) matemáticamente un valor del atributo numérico existente. **nota** La operación `PutItem` también puede llevar a cabo una actualización. Para obtener más información, consulte [Colocación de un elemento](#PutItemLowLevelAPIDotNet). Por ejemplo, si llama a `PutItem` para cargar un elemento y la clave principal ya existe, la operación `PutItem` sustituye el elemento completo. Tenga en cuenta que, si hay atributos en el elemento existente que no se especifican en la información de entrada, la operación `PutItem` los eliminará. Sin embargo, `UpdateItem` solo actualiza los atributos de entrada especificados. Todos los demás atributos existentes de ese elemento permanecen inalterados. A continuación se indican los pasos que hay que seguir para actualizar un elemento existente mediante la API de bajo nivel del SDK para .NET: 1. Cree una instancia de la clase `AmazonDynamoDBClient`. 1. Cree una instancia de la clase `UpdateItemRequest` para proporcionar los parámetros requeridos. Se trata del objeto de solicitud en el que se describen todas las actualizaciones, tales como agregar atributos o actualizar o eliminar atributos existentes. Para eliminar un atributo, especifique su nombre con el valor null. 1. Ejecute el método `UpdateItem` proporcionando el objeto `UpdateItemRequest` que creó en el paso anterior. En el siguiente ejemplo de código C\$1 se ponen en práctica los pasos anteriores. En el ejemplo se actualiza un elemento libro de la tabla `ProductCatalog`. Se agrega un nuevo autor a la colección `Authors` y se elimina el atributo `ISBN` existente. También se reduce el precio en una unidad. ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new UpdateItemRequest { TableName = tableName, Key = new Dictionary() { { "Id", new AttributeValue { N = "202" } } }, ExpressionAttributeNames = new Dictionary() { {"#A", "Authors"}, {"#P", "Price"}, {"#NA", "NewAttribute"}, {"#I", "ISBN"} }, ExpressionAttributeValues = new Dictionary() { {":auth",new AttributeValue { SS = {"Author YY","Author ZZ"}}}, {":p",new AttributeValue {N = "1"}}, {":newattr",new AttributeValue {S = "someValue"}}, }, // This expression does the following: // 1) Adds two new authors to the list // 2) Reduces the price // 3) Adds a new attribute to the item // 4) Removes the ISBN attribute from the item UpdateExpression = "ADD #A :auth SET #P = #P - :p, #NA = :newattr REMOVE #I" }; var response = client.UpdateItem(request); ``` ### Especificación de parámetros opcionales También puede usar el objeto `UpdateItemRequest` para proporcionar parámetros opcionales, como se muestra en el siguiente ejemplo de código C\$1. En él se especifican los parámetros opcionales siguientes: + `ExpressionAttributeValues` y `ConditionExpression` para especificar que el precio solo puede actualizarse si el precio actual es 20.00. + `ReturnValues`El parámetro para solicitar el elemento actualizado en la respuesta. **Example** ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new UpdateItemRequest { Key = new Dictionary() { { "Id", new AttributeValue { N = "202" } } }, // Update price only if the current price is 20.00. ExpressionAttributeNames = new Dictionary() { {"#P", "Price"} }, ExpressionAttributeValues = new Dictionary() { {":newprice",new AttributeValue {N = "22"}}, {":currprice",new AttributeValue {N = "20"}} }, UpdateExpression = "SET #P = :newprice", ConditionExpression = "#P = :currprice", TableName = tableName, ReturnValues = "ALL_NEW" // Return all the attributes of the updated item. }; var response = client.UpdateItem(request); ``` Para obtener más información, consulte [UpdateItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html). ## Contador atómico Puede usar `updateItem` para implementar un contador atómico y aumentar o reducir el valor de un atributo existente sin interferir con las demás solicitudes de escritura. Para actualizar un contador atómico, use `updateItem` con un atributo de tipo `Number` en el parámetro `UpdateExpression` y use `ADD` como `Action`. En el siguiente ejemplo se pone en práctica lo anterior y se incrementa el atributo `Quantity` en una unidad. ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new UpdateItemRequest { Key = new Dictionary() { { "Id", new AttributeValue { N = "121" } } }, ExpressionAttributeNames = new Dictionary() { {"#Q", "Quantity"} }, ExpressionAttributeValues = new Dictionary() { {":incr",new AttributeValue {N = "1"}} }, UpdateExpression = "SET #Q = #Q + :incr", TableName = tableName }; var response = client.UpdateItem(request); ``` ## Eliminación de un elemento El método `DeleteItem` elimina un elemento de una tabla. A continuación se indican los pasos que hay que seguir para eliminar un elemento mediante el API de bajo nivel del SDK para .NET. 1. Cree una instancia de la clase `AmazonDynamoDBClient`. 1. Cree una instancia de la clase `DeleteItemRequest` para proporcionar los parámetros requeridos. Para eliminar un elemento, se requieren el nombre de la tabla y la clave principal del elemento. 1. Ejecute el método `DeleteItem` proporcionando el objeto `DeleteItemRequest` que creó en el paso anterior. **Example** ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new DeleteItemRequest { TableName = tableName, Key = new Dictionary() { { "Id", new AttributeValue { N = "201" } } }, }; var response = client.DeleteItem(request); ``` ### Especificación de parámetros opcionales También puede usar el objeto `DeleteItemRequest` para proporcionar parámetros opcionales, como se muestra en el siguiente ejemplo de código C\$1. En él se especifican los parámetros opcionales siguientes: + `ExpressionAttributeValues` y `ConditionExpression` para especificar que el elemento de libro solo se puede eliminar si está descatalogado (el valor del atributo InPublication es false). + `ReturnValues`El parámetro para solicitar el elemento eliminado en la respuesta. **Example** ``` var request = new DeleteItemRequest { TableName = tableName, Key = new Dictionary() { { "Id", new AttributeValue { N = "201" } } }, // Optional parameters. ReturnValues = "ALL_OLD", ExpressionAttributeNames = new Dictionary() { {"#IP", "InPublication"} }, ExpressionAttributeValues = new Dictionary() { {":inpub",new AttributeValue {BOOL = false}} }, ConditionExpression = "#IP = :inpub" }; var response = client.DeleteItem(request); ``` Para obtener más información, consulte [DeleteItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html). ## Escritura por lotes: colocación y eliminación de varios elementos La *escritura por lotes* se refiere a colocar y eliminar varios elementos en un lote. El método `BatchWriteItem` permite colocar y eliminar varios elementos de una o varias tablas con una sola llamada. A continuación se indican los pasos que hay que seguir para recuperar varios elementos mediante el API de bajo nivel del SDK para .NET. 1. Cree una instancia de la clase `AmazonDynamoDBClient`. 1. Cree una instancia de la clase `BatchWriteItemRequest` para describir todas las operaciones de colocación y eliminación. 1. Ejecute el método `BatchWriteItem` proporcionando el objeto `BatchWriteItemRequest` que creó en el paso anterior. 1. Procese la respuesta. Debe comprobar si en la respuesta se ha devuelto algún elemento de solicitud sin procesar. Esto puede ocurrir si se alcanza la cuota de rendimiento aprovisionado o se produce algún otro error transitorio. Además, DynamoDB limita el tamaño de la solicitud y el número de operaciones que se pueden especificar en ella. Si supera estos límites, DynamoDB rechaza la solicitud. Para obtener más información, consulte [BatchWriteItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html). En el siguiente ejemplo de código C\$1 se ponen en práctica los pasos anteriores. En el siguiente ejemplo se crea una solicitud `BatchWriteItemRequest` para realizar las siguientes operaciones de escritura: + Colocar un elemento en la tabla `Forum`. + Colocar y eliminar un elemento en la tabla `Thread` A continuación, el código ejecuta `BatchWriteItem` para llevar a cabo una operación por lote. ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string table1Name = "Forum"; string table2Name = "Thread"; var request = new BatchWriteItemRequest { RequestItems = new Dictionary> { { table1Name, new List { new WriteRequest { PutRequest = new PutRequest { Item = new Dictionary { { "Name", new AttributeValue { S = "Amazon S3 forum" } }, { "Threads", new AttributeValue { N = "0" }} } } } } } , { table2Name, new List { new WriteRequest { PutRequest = new PutRequest { Item = new Dictionary { { "ForumName", new AttributeValue { S = "Amazon S3 forum" } }, { "Subject", new AttributeValue { S = "My sample question" } }, { "Message", new AttributeValue { S = "Message Text." } }, { "KeywordTags", new AttributeValue { SS = new List { "Amazon S3", "Bucket" } } } } } }, new WriteRequest { DeleteRequest = new DeleteRequest { Key = new Dictionary() { { "ForumName", new AttributeValue { S = "Some forum name" } }, { "Subject", new AttributeValue { S = "Some subject" } } } } } } } } }; response = client.BatchWriteItem(request); ``` Para ver un ejemplo práctico, consulte [Ejemplo: operaciones por lotes con la API de bajo nivel de AWS SDK para .NET](batch-operation-lowlevel-dotnet.md). ## Obtención por lotes: obtención de varios elementos El método `BatchGetItem` permite recuperar varios elementos de una o varias tablas. **nota** Para recuperar un solo elemento, puede usar el método `GetItem`. A continuación se indican los pasos que hay que seguir para recuperar varios elementos mediante la API de bajo nivel AWS SDK para .NET. 1. Cree una instancia de la clase `AmazonDynamoDBClient`. 1. Cree una instancia de la clase `BatchGetItemRequest` para proporcionar los parámetros requeridos. Para recuperar varios elementos, es obligatorio indicar el nombre de la tabla y una lista de valores de clave principal. 1. Ejecute el método `BatchGetItem` proporcionando el objeto `BatchGetItemRequest` que creó en el paso anterior. 1. Procese la respuesta. Debe comprobar si han quedado claves sin procesar, lo que podría ocurrir si se alcanza la cuota de rendimiento aprovisionada o se produce cualquier otro error transitorio. En el siguiente ejemplo de código C\$1 se ponen en práctica los pasos anteriores. En el ejemplo se recuperan elementos de dos tablas, `Forum` y `Thread`. La solicitud especifica dos elementos en la tabla `Forum` y tres en la tabla `Thread`. La respuesta incluye elementos de ambas tablas. En el código se muestra cómo procesar la respuesta. ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string table1Name = "Forum"; string table2Name = "Thread"; var request = new BatchGetItemRequest { RequestItems = new Dictionary() { { table1Name, new KeysAndAttributes { Keys = new List>() { new Dictionary() { { "Name", new AttributeValue { S = "DynamoDB" } } }, new Dictionary() { { "Name", new AttributeValue { S = "Amazon S3" } } } } } }, { table2Name, new KeysAndAttributes { Keys = new List>() { new Dictionary() { { "ForumName", new AttributeValue { S = "DynamoDB" } }, { "Subject", new AttributeValue { S = "DynamoDB Thread 1" } } }, new Dictionary() { { "ForumName", new AttributeValue { S = "DynamoDB" } }, { "Subject", new AttributeValue { S = "DynamoDB Thread 2" } } }, new Dictionary() { { "ForumName", new AttributeValue { S = "Amazon S3" } }, { "Subject", new AttributeValue { S = "Amazon S3 Thread 1" } } } } } } } }; var response = client.BatchGetItem(request); // Check the response. var result = response.BatchGetItemResult; var responses = result.Responses; // The attribute list in the response. var table1Results = responses[table1Name]; Console.WriteLine("Items in table {0}" + table1Name); foreach (var item1 in table1Results.Items) { PrintItem(item1); } var table2Results = responses[table2Name]; Console.WriteLine("Items in table {1}" + table2Name); foreach (var item2 in table2Results.Items) { PrintItem(item2); } // Any unprocessed keys? could happen if you exceed ProvisionedThroughput or some other error. Dictionary unprocessedKeys = result.UnprocessedKeys; foreach (KeyValuePair pair in unprocessedKeys) { Console.WriteLine(pair.Key, pair.Value); } ``` ### Especificación de parámetros opcionales También puede usar el objeto `BatchGetItemRequest` para proporcionar parámetros opcionales, como se muestra en el siguiente ejemplo de código C\$1. En el siguiente ejemplo de código se recuperan dos elementos de la tabla `Forum`. En él se especifica el parámetro opcional siguiente: + `ProjectionExpression`El parámetro para especificar los atributos que se van a recuperar. **Example** ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string table1Name = "Forum"; var request = new BatchGetItemRequest { RequestItems = new Dictionary() { { table1Name, new KeysAndAttributes { Keys = new List>() { new Dictionary() { { "Name", new AttributeValue { S = "DynamoDB" } } }, new Dictionary() { { "Name", new AttributeValue { S = "Amazon S3" } } } } }, // Optional - name of an attribute to retrieve. ProjectionExpression = "Title" } } }; var response = client.BatchGetItem(request); ``` Para obtener más información, consulte [BatchGetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchGetItem.html).