Uso de Azure Table Storage y Table API de Azure Cosmos DB con C++How to use Azure Table storage and Azure Cosmos DB Table API with C++

Sugerencia

El contenido de este artículo se aplica a Azure Table Storage y a Table API de Azure Cosmos DB.The content in this article applies to Azure Table storage and the Azure Cosmos DB Table API. La instancia de Table API de Azure Cosmos DB es una oferta premium que ofrece tablas con rendimiento optimizado, distribución global e índices secundarios automáticos.The Azure Cosmos DB Table API is a premium offering for table storage that offers throughput-optimized tables, global distribution, and automatic secondary indexes.

En esta guía se muestran escenarios comunes en los que se usa el servicio Azure Table Storage o Table API de Azure Cosmos DB.This guide shows you common scenarios by using the Azure Table storage service or Azure Cosmos DB Table API. Los ejemplos están escritos en C++ y usan la biblioteca de cliente de Azure Storage para C++.The samples are written in C++ and use the Azure Storage Client Library for C++. En este artículo se tratan los siguientes escenarios:This article covers the following scenarios:

  • Creación y eliminación de una tablaCreate and delete a table
  • Trabajo con entidades de tablaWork with table entities

Nota

Esta guía se destina a la biblioteca de cliente de Azure Storage para C++, versión 1.0.0 y posteriores.This guide targets the Azure Storage Client Library for C++ version 1.0.0 and above. La versión recomendada es la biblioteca cliente de Storage 2.2.0, que se encuentra disponible a través de NuGet o GitHub.The recommended version is Storage Client Library 2.2.0, which is available by using NuGet or GitHub.

Creación de cuentasCreate accounts

Creación de una cuenta de servicio de AzureCreate an Azure service account

Puede trabajar con tablas mediante Azure Table Storage o Azure Cosmos DB.You can work with tables using Azure Table storage or Azure Cosmos DB. Para más información acerca de las diferencias entre los servicios, consulte Ofertas de Table.To learn more about the differences between the services, see Table offerings. Debe crear una cuenta para el servicio que se va a utilizar.You'll need to create an account for the service you're going to use.

Creación de una cuenta de Azure StorageCreate an Azure storage account

La manera más sencilla de crear una cuenta de almacenamiento de Azure es mediante Azure Portal.The easiest way to create an Azure storage account is by using the Azure portal. Para obtener más información, consulte Crear una cuenta de almacenamiento.To learn more, see Create a storage account.

También se puede crear una cuenta de Azure Storage mediante Azure PowerShell o la CLI de Azure.You can also create an Azure storage account by using Azure PowerShell or Azure CLI.

Si no desea crear una cuenta de almacenamiento en este momento, también puede utilizar el emulador de Almacenamiento de Azure para ejecutar y probar el código en un entorno local.If you prefer not to create a storage account at this time, you can also use the Azure storage emulator to run and test your code in a local environment. Para más información, consulte Uso del emulador de Azure Storage para desarrollo y pruebas.For more information, see Use the Azure storage emulator for development and testing.

Creación de una cuenta de Table API de Azure Cosmos DBCreate an Azure Cosmos DB Table API account

Para obtener instrucciones sobre cómo crear una cuenta de Table API de Azure Cosmos DB, consulte Creación de una cuenta de base de datos.For instructions on creating an Azure Cosmos DB Table API account, see Create a database account.

Creación de una aplicación de C++Create a C++ application

En esta guía, usará las características de almacenamiento de una aplicación de C++.In this guide, you use storage features from a C++ application. Para ello, instale la biblioteca cliente de Azure Storage para C++.To do so, install the Azure Storage Client Library for C++.

Para instalar la biblioteca cliente de Azure Storage para C++, use los métodos siguientes:To install the Azure Storage Client Library for C++, use the following methods:

.\vcpkg.exe install azure-storage-cpp

Puede encontrar una guía sobre cómo compilar el código fuente y exportarlo a Nuget en el archivo Léame.You can find a guide for how to build the source code and export to Nuget in the README file.

Configuración de acceso a la biblioteca cliente de TableConfigure access to the Table client library

Si desea usar las API de Azure Storage para acceder a las tablas, agregue las siguientes instrucciones include en la parte superior del archivo de C++:To use the Azure storage APIs to access tables, add the following include statements to the top of the C++ file:

#include <was/storage_account.h>
#include <was/table.h>

Un cliente de Azure Storage o Cosmos DB usa una cadena de conexión para almacenar puntos de conexión y credenciales con el fin de acceder a los servicios de administración de datos.An Azure Storage client or Cosmos DB client uses a connection string to store endpoints and credentials to access data management services. Cuando ejecuta una aplicación cliente, debe proporcionar la cadena de conexión de Storage o la cadena de conexión de Azure Cosmos DB con el formato apropiado.When you run a client application, you must provide the storage connection string or Azure Cosmos DB connection string in the appropriate format.

Configuración de una cadena de conexión de Azure StorageSet up an Azure Storage connection string

En este ejemplo se muestra cómo declarar un campo estático para mantener la cadena de conexión de Azure Storage:This example shows how to declare a static field to hold the Azure Storage connection string:

// Define the Storage connection string with your values.
const utility::string_t storage_connection_string(U("DefaultEndpointsProtocol=https;AccountName=<your_storage_account>;AccountKey=<your_storage_account_key>"));

Use el nombre de la cuenta de Storage en <your_storage_account>.Use the name of your Storage account for <your_storage_account>. En <your_storage_account_key>, use la clave de acceso de la cuenta de Storage que se muestra en Azure Portal.For <your_storage_account_key>, use the access key for the Storage account listed in the Azure portal. Para obtener información sobre las cuentas de Storage y las claves de acceso, consulte Crear una cuenta de almacenamiento.For information on Storage accounts and access keys, see Create a storage account.

Configuración de una cadena de conexión de Azure Cosmos DBSet up an Azure Cosmos DB connection string

En este ejemplo se muestra cómo declarar un campo estático para mantener la cadena de conexión de Azure Cosmos DB:This example shows how to declare a static field to hold the Azure Cosmos DB connection string:

// Define the Azure Cosmos DB connection string with your values.
const utility::string_t storage_connection_string(U("DefaultEndpointsProtocol=https;AccountName=<your_cosmos_db_account>;AccountKey=<your_cosmos_db_account_key>;TableEndpoint=<your_cosmos_db_endpoint>"));

Use el nombre de la cuenta de Azure Cosmos DB en <your_cosmos_db_account>.Use the name of your Azure Cosmos DB account for <your_cosmos_db_account>. Escriba la clave principal en <your_cosmos_db_account_key>.Enter your primary key for <your_cosmos_db_account_key>. Escriba el punto de conexión que aparece en Azure Portal en <your_cosmos_db_endpoint>.Enter the endpoint listed in the Azure portal for <your_cosmos_db_endpoint>.

Para probar la aplicación en el equipo local de Windows, puede usar el emulador de Azure Storage que se instala con el SDK de Azure.To test your application in your local Windows-based computer, you can use the Azure storage emulator that is installed with the Azure SDK. El emulador de almacenamiento es una utilidad que simula los servicios Azure Blob, Queue y Table en el equipo de desarrollo local.The storage emulator is a utility that simulates the Azure Blob, Queue, and Table services available on your local development machine. En el ejemplo siguiente se muestra cómo declarar un campo estático para mantener la cadena de conexión al emulador de almacenamiento local:The following example shows how to declare a static field to hold the connection string to your local storage emulator:

// Define the connection string with Azure storage emulator.
const utility::string_t storage_connection_string(U("UseDevelopmentStorage=true;"));  

Para iniciar el emulador de Azure Storage, en el escritorio de Windows, seleccione el botón Iniciar o la tecla Windows.To start the Azure storage emulator, from your Windows desktop, select the Start button or the Windows key. Escriba y ejecute Emulador de Microsoft Azure Storage.Enter and run Microsoft Azure Storage Emulator. Para más información, consulte Uso del emulador de Azure Storage para desarrollo y pruebas.For more information, see Use the Azure storage emulator for development and testing.

Recuperación de la cadena de conexiónRetrieve your connection string

Puede usar la clase cloud_storage_account para representar la información de la cuenta de almacenamiento.You can use the cloud_storage_account class to represent your storage account information. Para recuperar la información de la cuenta de almacenamiento a partir de la cadena de conexión de almacenamiento, use el método parse.To retrieve your storage account information from the storage connection string, use the parse method.

// Retrieve the storage account from the connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

A continuación, obtenga una referencia a una clase cloud_table_client.Next, get a reference to a cloud_table_client class. Esta clase permite obtener objetos de referencia para las tablas y entidades almacenadas en el servicio Table Storage.This class lets you get reference objects for tables and entities stored within the Table storage service. En el código siguiente se crea un objeto cloud_table_client mediante el objeto de cuenta de almacenamiento recuperado anteriormente:The following code creates a cloud_table_client object by using the storage account object you retrieved previously:

// Create the table client.
azure::storage::cloud_table_client table_client = storage_account.create_cloud_table_client();

Creación e incorporación de entidades a una tablaCreate and add entities to a table

Creación de una tablaCreate a table

Los objetos cloud_table_client permiten obtener objetos de referencia para tablas y entidades.A cloud_table_client object lets you get reference objects for tables and entities. El código siguiente crea un objeto cloud_table_client y lo usa para crear una tabla.The following code creates a cloud_table_client object and uses it to create a new table.

// Retrieve the storage account from the connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);  

// Create the table client.
azure::storage::cloud_table_client table_client = storage_account.create_cloud_table_client();

// Retrieve a reference to a table.
azure::storage::cloud_table table = table_client.get_table_reference(U("people"));

// Create the table if it doesn't exist.
table.create_if_not_exists();  

Adición de una entidad a una tablaAdd an entity to a table

Para agregar una entidad a una tabla, cree un nuevo objeto table_entity y páselo a table_operation::insert_entity.To add an entity to a table, create a new table_entity object and pass it to table_operation::insert_entity. El código siguiente usa el nombre de pila del cliente como clave de fila y el apellido como clave de partición.The following code uses the customer's first name as the row key and last name as the partition key. En conjunto, la clave de partición y la clave de fila de una entidad la identifican inequívocamente en la tabla.Together, an entity's partition and row key uniquely identify the entity in the table. Puede realizarse una consulta en las entidades con la misma clave de partición de manera más rápida que en aquellas que tienen claves de partición distintas.Entities with the same partition key can be queried faster than entities with different partition keys. El uso de claves de partición diversas favorece una mayor escalabilidad de las operaciones paralelas.Using diverse partition keys allows for greater parallel operation scalability. Para obtener más información, consulte Lista de comprobación de rendimiento y escalabilidad de Almacenamiento de Microsoft Azure.For more information, see Microsoft Azure storage performance and scalability checklist.

El código siguiente crea una nueva instancia de table_entity con algunos datos de clientes que se van a almacenar.The following code creates a new instance of table_entity with some customer data to store. El código siguiente llama a table_operation::insert_entity para crear un objeto table_operation a fin de insertar una entidad en una tabla y le asocia la nueva entidad de tabla.The code next calls table_operation::insert_entity to create a table_operation object to insert an entity into a table, and associates the new table entity with it. Por último, el código llama al método execute en el objeto cloud_table.Finally, the code calls the execute method on the cloud_table object. El nuevo objeto table_operation envía una solicitud a Table service para insertar la nueva entidad de cliente en la tabla people.The new table_operation sends a request to the Table service to insert the new customer entity into the people table.

// Retrieve the storage account from the connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the table client.
azure::storage::cloud_table_client table_client = storage_account.create_cloud_table_client();

// Retrieve a reference to a table.
azure::storage::cloud_table table = table_client.get_table_reference(U("people"));

// Create the table if it doesn't exist.
table.create_if_not_exists();

// Create a new customer entity.
azure::storage::table_entity customer1(U("Harp"), U("Walter"));

azure::storage::table_entity::properties_type& properties = customer1.properties();
properties.reserve(2);
properties[U("Email")] = azure::storage::entity_property(U("Walter@contoso.com"));

properties[U("Phone")] = azure::storage::entity_property(U("425-555-0101"));

// Create the table operation that inserts the customer entity.
azure::storage::table_operation insert_operation = azure::storage::table_operation::insert_entity(customer1);

// Execute the insert operation.
azure::storage::table_result insert_result = table.execute(insert_operation);

Inserción de un lote de entidadesInsert a batch of entities

Puede insertar un lote de entidades en Table service mediante una operación de escritura.You can insert a batch of entities to the Table service in one write operation. El siguiente código crea un objeto table_batch_operation y, luego, le agrega tres operaciones de inserción.The following code creates a table_batch_operation object, and then adds three insert operations to it. Cada operación de inserción se agrega mediante la creación de un nuevo objeto de entidad, la configuración de sus valores y, a continuación, la llamada al método insert en el objeto table_batch_operation para asociar la entidad a una nueva operación de inserción.Each insert operation is added by creating a new entity object, setting its values, and then calling the insert method on the table_batch_operation object to associate the entity with a new insert operation. A continuación, el código llama a cloud_table.execute para ejecutar la operación.Then, the code calls cloud_table.execute to run the operation.

// Retrieve the storage account from the connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the table client.
azure::storage::cloud_table_client table_client = storage_account.create_cloud_table_client();

// Create a cloud table object for the table.
azure::storage::cloud_table table = table_client.get_table_reference(U("people"));

// Define a batch operation.
azure::storage::table_batch_operation batch_operation;

// Create a customer entity and add it to the table.
azure::storage::table_entity customer1(U("Smith"), U("Jeff"));

azure::storage::table_entity::properties_type& properties1 = customer1.properties();
properties1.reserve(2);
properties1[U("Email")] = azure::storage::entity_property(U("Jeff@contoso.com"));
properties1[U("Phone")] = azure::storage::entity_property(U("425-555-0104"));

// Create another customer entity and add it to the table.
azure::storage::table_entity customer2(U("Smith"), U("Ben"));

azure::storage::table_entity::properties_type& properties2 = customer2.properties();
properties2.reserve(2);
properties2[U("Email")] = azure::storage::entity_property(U("Ben@contoso.com"));
properties2[U("Phone")] = azure::storage::entity_property(U("425-555-0102"));

// Create a third customer entity to add to the table.
azure::storage::table_entity customer3(U("Smith"), U("Denise"));

azure::storage::table_entity::properties_type& properties3 = customer3.properties();
properties3.reserve(2);
properties3[U("Email")] = azure::storage::entity_property(U("Denise@contoso.com"));
properties3[U("Phone")] = azure::storage::entity_property(U("425-555-0103"));

// Add customer entities to the batch insert operation.
batch_operation.insert_or_replace_entity(customer1);
batch_operation.insert_or_replace_entity(customer2);
batch_operation.insert_or_replace_entity(customer3);

// Execute the batch operation.
std::vector<azure::storage::table_result> results = table.execute_batch(batch_operation);

Algunos aspectos que cabe tener en cuenta acerca de las operaciones por lotes:Some things to note on batch operations:

  • Puede realizar hasta 100 operaciones insert, delete, merge, replace, insert-or-merge y insert-or-replace con cualquier combinación en un solo lote.You can do up to 100 insert, delete, merge, replace, insert-or-merge, and insert-or-replace operations in any combination in a single batch.
  • Una operación por lotes puede tener una operación de recuperación, si es la única operación del lote.A batch operation can have a retrieve operation, if it's the only operation in the batch.
  • Todas las entidades de la misma operación por lotes deben compartir la misma clave de partición.All entities in a single batch operation must have the same partition key.
  • Una operación por lotes se limita a una carga de datos de 4 MB.A batch operation is limited to a 4-MB data payload.

Consulta y modificación de entidadesQuery and modify entities

todas las entidades de una particiónRetrieve all entities in a partition

Para consultar una tabla a fin de obtener todas las entidades de una partición, use un objeto table_query.To query a table for all entities in a partition, use a table_query object. El siguiente ejemplo de código especifica un filtro para las entidades en las que Smith es la clave de partición.The following code example specifies a filter for entities where Smith is the partition key. En este ejemplo, los campos de cada entidad se imprimen en la consola, como parte de los resultados de la consulta.This example prints the fields of each entity in the query results to the console.

Nota

Estos métodos no son compatibles actualmente con C++ en Azure Cosmos DB.These methods are not currently supported for C++ in Azure Cosmos DB.

// Retrieve the storage account from the connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the table client.
azure::storage::cloud_table_client table_client = storage_account.create_cloud_table_client();

// Create a cloud table object for the table.
azure::storage::cloud_table table = table_client.get_table_reference(U("people"));

// Construct the query operation for all customer entities where PartitionKey="Smith".
azure::storage::table_query query;

query.set_filter_string(azure::storage::table_query::generate_filter_condition(U("PartitionKey"), azure::storage::query_comparison_operator::equal, U("Smith")));

// Execute the query.
azure::storage::table_query_iterator it = table.execute_query(query);

// Print the fields for each customer.
azure::storage::table_query_iterator end_of_results;
for (; it != end_of_results; ++it)
{
    const azure::storage::table_entity::properties_type& properties = it->properties();

    std::wcout << U("PartitionKey: ") << it->partition_key() << U(", RowKey: ") << it->row_key()
        << U(", Property1: ") << properties.at(U("Email")).string_value()
        << U(", Property2: ") << properties.at(U("Phone")).string_value() << std::endl;
}  

La consulta de este ejemplo devuelve todas las entidades que coinciden con los criterios de filtro.The query in this example returns all the entities that match the filter criteria. Si tiene tablas grandes y necesita descargar las entidades de tabla con frecuencia, se recomienda almacenar los datos en blobs de Almacenamiento de Azure en su lugar.If you have large tables and need to download the table entities often, we recommend that you store your data in Azure storage blobs instead.

Recuperación de un rango de entidades de una particiónRetrieve a range of entities in a partition

Si no desea consultar todas las entidades de una partición, puede especificar un rango.If you don't want to query all the entities in a partition, you can specify a range. Combine el filtro de clave de partición con un filtro de clave de fila.Combine the partition key filter with a row key filter. El siguiente ejemplo de código utiliza dos filtros para obtener todas las entidades de la partición Smith en las que la clave de fila (nombre) empieza por una letra anterior a E en el alfabeto y, a continuación, imprime los resultados de la consulta.The following code example uses two filters to get all entities in partition Smith where the row key (first name) starts with a letter earlier than E in the alphabet, and then prints the query results.

Nota

Estos métodos no son compatibles actualmente con C++ en Azure Cosmos DB.These methods are not currently supported for C++ in Azure Cosmos DB.

// Retrieve the storage account from the connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the table client.
azure::storage::cloud_table_client table_client = storage_account.create_cloud_table_client();

// Create a cloud table object for the table.
azure::storage::cloud_table table = table_client.get_table_reference(U("people"));

// Create the table query.
azure::storage::table_query query;

query.set_filter_string(azure::storage::table_query::combine_filter_conditions(
    azure::storage::table_query::generate_filter_condition(U("PartitionKey"),
    azure::storage::query_comparison_operator::equal, U("Smith")),
    azure::storage::query_logical_operator::op_and,
    azure::storage::table_query::generate_filter_condition(U("RowKey"), azure::storage::query_comparison_operator::less_than, U("E"))));

// Execute the query.
azure::storage::table_query_iterator it = table.execute_query(query);

// Loop through the results, displaying information about the entity.
azure::storage::table_query_iterator end_of_results;
for (; it != end_of_results; ++it)
{
    const azure::storage::table_entity::properties_type& properties = it->properties();

    std::wcout << U("PartitionKey: ") << it->partition_key() << U(", RowKey: ") << it->row_key()
        << U(", Property1: ") << properties.at(U("Email")).string_value()
        << U(", Property2: ") << properties.at(U("Phone")).string_value() << std::endl;
}  

una sola entidadRetrieve a single entity

Puede enviar una consulta para recuperar una sola entidad concreta.You can write a query to retrieve a single, specific entity. En el código siguiente se utiliza table_operation::retrieve_entity para especificar el cliente Jeff Smith.The following code uses table_operation::retrieve_entity to specify the customer Jeff Smith. Este método devuelve una sola entidad, en lugar de una colección, y el valor devuelto se incluye en table_result.This method returns just one entity, rather than a collection, and the returned value is in table_result. La forma más rápida de recuperar una sola entidad de Table service es especificar claves tanto de partición como de fila en las consultas.Specifying both partition and row keys in a query is the fastest way to retrieve a single entity from the Table service.

azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the table client.
azure::storage::cloud_table_client table_client = storage_account.create_cloud_table_client();

// Create a cloud table object for the table.
azure::storage::cloud_table table = table_client.get_table_reference(U("people"));

// Retrieve the entity with partition key of "Smith" and row key of "Jeff".
azure::storage::table_operation retrieve_operation = azure::storage::table_operation::retrieve_entity(U("Smith"), U("Jeff"));
azure::storage::table_result retrieve_result = table.execute(retrieve_operation);

// Output the entity.
azure::storage::table_entity entity = retrieve_result.entity();
const azure::storage::table_entity::properties_type& properties = entity.properties();

std::wcout << U("PartitionKey: ") << entity.partition_key() << U(", RowKey: ") << entity.row_key()
    << U(", Property1: ") << properties.at(U("Email")).string_value()
    << U(", Property2: ") << properties.at(U("Phone")).string_value() << std::endl;

una entidadReplace an entity

Para reemplazar una entidad, recupérela de Table service, modifique su objeto y, luego, guarde los cambios de nuevo en Table service.To replace an entity, retrieve it from the Table service, modify the entity object, and then save the changes back to the Table service. El código siguiente cambia el número de teléfono y la dirección de correo electrónico de un cliente.The following code changes an existing customer's phone number and email address. En lugar de llamar a table_operation::insert_entity, este código utiliza table_operation::replace_entity.Instead of calling table_operation::insert_entity, this code uses table_operation::replace_entity. De este modo, la entidad se reemplaza por completo en el servidor, a menos que la entidad del servidor hubiese cambiado desde que se recuperó.This approach causes the entity to be fully replaced on the server, unless the entity on the server has changed since it was retrieved. Si se modificó, se produce un error en la operación.If it has been changed, the operation fails. Este error evita que la aplicación sobrescriba un cambio realizado por parte de otro componente entre la recuperación y la actualización.This failure prevents your application from overwriting a change made between the retrieval and update by another component. La manera correcta de actuar ante este error es recuperar de nuevo la entidad, hacer los cambios oportunos —si siguen siendo válidos— y, a continuación, realizar otra operación table_operation::replace_entity.The proper handling of this failure is to retrieve the entity again, make your changes, if still valid, and then do another table_operation::replace_entity operation.

// Retrieve the storage account from the connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the table client.
azure::storage::cloud_table_client table_client = storage_account.create_cloud_table_client();

// Create a cloud table object for the table.
azure::storage::cloud_table table = table_client.get_table_reference(U("people"));

// Replace an entity.
azure::storage::table_entity entity_to_replace(U("Smith"), U("Jeff"));
azure::storage::table_entity::properties_type& properties_to_replace = entity_to_replace.properties();
properties_to_replace.reserve(2);

// Specify a new phone number.
properties_to_replace[U("Phone")] = azure::storage::entity_property(U("425-555-0106"));

// Specify a new email address.
properties_to_replace[U("Email")] = azure::storage::entity_property(U("JeffS@contoso.com"));

// Create an operation to replace the entity.
azure::storage::table_operation replace_operation = azure::storage::table_operation::replace_entity(entity_to_replace);

// Submit the operation to the Table service.
azure::storage::table_result replace_result = table.execute(replace_operation);

Inserción o reemplazo de una entidadInsert or replace an entity

Las operaciones table_operation::replace_entity darán error si se cambió la entidad desde que se recuperó del servidor.table_operation::replace_entity operations fail if the entity has been changed since it was retrieved from the server. Asimismo, para que la operación table_operation::replace_entity se realice correctamente, antes debe recuperar la entidad del servidor.Furthermore, you must retrieve the entity from the server first in order for table_operation::replace_entity to be successful. En ocasiones, no sabe si la entidad existe en el servidor.Sometimes, you don't know if the entity exists on the server. Los valores actuales almacenados en ella son irrelevantes, ya que la actualización deberá sobrescribirlos todos.The current values stored in it are irrelevant, because your update should overwrite them all. Para lograr este resultado, use una operación table_operation::insert_or_replace_entity.To accomplish this result, use a table_operation::insert_or_replace_entity operation. Esta operación inserta la entidad si no existe.This operation inserts the entity if it doesn't exist. La operación reemplaza la entidad si existe.The operation replaces the entity if it exists. En el siguiente ejemplo de código, también se recupera la entidad de cliente Jeff Smith pero, a continuación, se guarda de nuevo en el servidor mediante table_operation::insert_or_replace_entity.In the following code example, the customer entity for Jeff Smith is still retrieved, but it's then saved back to the server by using table_operation::insert_or_replace_entity. Las actualizaciones realizadas en la entidad entre la operación de recuperación y actualización se sobrescribirán.Any updates made to the entity between the retrieval and update operation will be overwritten.

// Retrieve the storage account from the connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the table client.
azure::storage::cloud_table_client table_client = storage_account.create_cloud_table_client();

// Create a cloud table object for the table.
azure::storage::cloud_table table = table_client.get_table_reference(U("people"));

// Insert or replace an entity.
azure::storage::table_entity entity_to_insert_or_replace(U("Smith"), U("Jeff"));
azure::storage::table_entity::properties_type& properties_to_insert_or_replace = entity_to_insert_or_replace.properties();

properties_to_insert_or_replace.reserve(2);

// Specify a phone number.
properties_to_insert_or_replace[U("Phone")] = azure::storage::entity_property(U("425-555-0107"));

// Specify an email address.
properties_to_insert_or_replace[U("Email")] = azure::storage::entity_property(U("Jeffsm@contoso.com"));

// Create an operation to insert or replace the entity.
azure::storage::table_operation insert_or_replace_operation = azure::storage::table_operation::insert_or_replace_entity(entity_to_insert_or_replace);

// Submit the operation to the Table service.
azure::storage::table_result insert_or_replace_result = table.execute(insert_or_replace_operation);

Consulta de un subconjunto de propiedades de las entidadesQuery a subset of entity properties

Una consulta de tabla puede recuperar solo algunas propiedades de una entidad.A query to a table can retrieve just a few properties from an entity. La consulta del siguiente código usa el método table_query::set_select_columns para devolver solo las direcciones de correo electrónico de las entidades de la tabla.The query in the following code uses the table_query::set_select_columns method to return only the email addresses of entities in the table.

// Retrieve the storage account from the connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the table client.
azure::storage::cloud_table_client table_client = storage_account.create_cloud_table_client();

// Create a cloud table object for the table.
azure::storage::cloud_table table = table_client.get_table_reference(U("people"));

// Define the query, and select only the Email property.
azure::storage::table_query query;
std::vector<utility::string_t> columns;

columns.push_back(U("Email"));
query.set_select_columns(columns);

// Execute the query.
azure::storage::table_query_iterator it = table.execute_query(query);

// Display the results.
azure::storage::table_query_iterator end_of_results;
for (; it != end_of_results; ++it)
{
    std::wcout << U("PartitionKey: ") << it->partition_key() << U(", RowKey: ") << it->row_key();

    const azure::storage::table_entity::properties_type& properties = it->properties();
    for (auto prop_it = properties.begin(); prop_it != properties.end(); ++prop_it)
    {
        std::wcout << ", " << prop_it->first << ": " << prop_it->second.str();
    }

    std::wcout << std::endl;
}

Nota

Consultar una serie de propiedades de una entidad es una operación más eficaz que recuperar todas las propiedades.Querying a few properties from an entity is a more efficient operation than retrieving all properties.

Eliminación de contenidoDelete content

Eliminación de una entidadDelete an entity

Puede eliminar una entidad después de recuperarla.You can delete an entity after you retrieve it. Después de recuperar una entidad, llame a table_operation::delete_entity con la entidad que va a eliminar.After you retrieve an entity, call table_operation::delete_entity with the entity to delete. A continuación, llame al método cloud_table.execute.Then call the cloud_table.execute method. El siguiente código recupera y elimina una entidad con la clave de partición Smith y la clave de fila Jeff.The following code retrieves and deletes an entity with a partition key of Smith and a row key of Jeff.

// Retrieve the storage account from the connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the table client.
azure::storage::cloud_table_client table_client = storage_account.create_cloud_table_client();

// Create a cloud table object for the table.
azure::storage::cloud_table table = table_client.get_table_reference(U("people"));

// Create an operation to retrieve the entity with partition key of "Smith" and row key of "Jeff".
azure::storage::table_operation retrieve_operation = azure::storage::table_operation::retrieve_entity(U("Smith"), U("Jeff"));
azure::storage::table_result retrieve_result = table.execute(retrieve_operation);

// Create an operation to delete the entity.
azure::storage::table_operation delete_operation = azure::storage::table_operation::delete_entity(retrieve_result.entity());

// Submit the delete operation to the Table service.
azure::storage::table_result delete_result = table.execute(delete_operation);  

Eliminar una tablaDelete a table

Finalmente, el ejemplo de código siguiente elimina una tabla de una cuenta de almacenamiento.Finally, the following code example deletes a table from a storage account. Una tabla que se ha eliminado no podrá volver a crearse durante un tiempo tras la eliminación.A table that has been deleted is unavailable to be re-created for some time following the deletion.

// Retrieve the storage account from the connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the table client.
azure::storage::cloud_table_client table_client = storage_account.create_cloud_table_client();

// Create a cloud table object for the table.
azure::storage::cloud_table table = table_client.get_table_reference(U("people"));

// Delete the table if it exists
if (table.delete_table_if_exists())
{
    std::cout << "Table deleted!";
}
else
{
    std::cout << "Table didn't exist";
}

Solución de problemasTroubleshooting

En Visual Studio Community Edition, si en el proyecto se generan errores de compilación debido a los archivos de inclusión storage_account.h y table.h, quite el conmutador de compilador /permissive- :For Visual Studio Community Edition, if your project gets build errors because of the include files storage_account.h and table.h, remove the /permissive- compiler switch:

  1. En el Explorador de soluciones, haga clic con el botón derecho en el proyecto y seleccione Propiedades.In Solution Explorer, right-click your project and select Properties.
  2. En el cuadro de diálogo Páginas de propiedades, expanda Propiedades de configuración, expanda C/C++ y seleccione Lenguaje.In the Property Pages dialog box, expand Configuration Properties, expand C/C++, and select Language.
  3. Establezca Modo de conformidad en No.Set Conformance mode to No.

Pasos siguientesNext steps

El Explorador de Microsoft Azure Storage es una aplicación independiente y gratuita de Microsoft que permite trabajar visualmente con los datos de Azure Storage en Windows, macOS y Linux.Microsoft Azure Storage Explorer is a free, standalone app from Microsoft that enables you to work visually with Azure Storage data on Windows, macOS, and Linux.

Siga estos vínculos para obtener más información sobre Azure Storage y Table API de Azure Cosmos DB:Follow these links to learn more about Azure Storage and the Table API in Azure Cosmos DB: