Biblioteca cliente de Azure Tables para .NET: versión 12.8.1

Artículo
08/16/2023

Azure Table Storage es un servicio que almacena grandes cantidades de datos NoSQL estructurados en la nube, lo que proporciona un almacén de claves y atributos con un diseño sin esquema.

Azure Cosmos DB proporciona una Table API para aplicaciones escritas para Azure Table Storage que necesitan funcionalidades premium como:

Distribución global llave en mano.
Rendimiento dedicado en todo el mundo.
Latencias en milisegundos de un solo dígito en el percentil 99.
Alta disponibilidad garantizada.
Indexación secundaria automática.

La biblioteca cliente Azure Tables puede tener como destino sin problemas los puntos de conexión de servicio del almacenamiento de Azure Table o de la tabla de Azure Cosmos DB sin cambios de código.

Código | fuentePaquete (NuGet) | Documentación | de referencia de API Muestras | Registro de cambios

Introducción

Instalar el paquete

Instale la biblioteca cliente de Azure Tables para .NET con NuGet:

dotnet add package Azure.Data.Tables

Requisitos previos

Una suscripción de Azure.
Una cuenta de almacenamiento de Azure existente o una base de datos de Azure Cosmos DB con Azure Table API especificada.

Si necesita crear cualquiera de estos, puede usar la CLI de Azure.

Creación de una cuenta de almacenamiento

Cree una cuenta mystorageaccount de almacenamiento en el grupo MyResourceGroup de recursos de la suscripción MySubscription en la región Oeste de EE. UU.

az storage account create -n mystorageaccount -g MyResourceGroup -l westus --subscription MySubscription

Creación de una base de datos de Cosmos DB

Cree una cuenta MyCosmosDBDatabaseAccount de Cosmos DB en el grupo MyResourceGroup de recursos de la suscripción MySubscription y una tabla denominada MyTableName en la cuenta.

az cosmosdb create --name MyCosmosDBDatabaseAccount --capabilities EnableTable --resource-group MyResourceGroup --subscription MySubscription

az cosmosdb table create --name MyTableName --resource-group MyResourceGroup --account-name MyCosmosDBDatabaseAccount

Autenticar el cliente

Obtenga más información sobre las opciones de autenticación (incluidas cadenas de conexión, clave compartida, firmas de clave compartida y TokenCredentials)en nuestros ejemplos.

Conceptos clave

TableServiceClient - Cliente que proporciona métodos para interactuar en el nivel de Table Service, como crear, enumerar y eliminar tablas
TableClient - Cliente que proporciona métodos para interactuar en un nivel de entidad de tabla, como crear, consultar y eliminar entidades dentro de una tabla.
Table - Las tablas almacenan datos como colecciones de entidades.
Entity - Las entidades son similares a las filas. Una entidad tiene una clave principal y un conjunto de propiedades. Una propiedad es un par de valores de nombre, similar a una columna.

Entre los usos frecuentes de Table service se encuentran los siguientes:

Almacenamiento de TB de datos estructurados capaces de ofrecer servicio a aplicaciones de escalado web
Almacenamiento de conjuntos de datos que no requieren combinaciones complejas, claves externas o procedimientos almacenados y se pueden des normalizar para un acceso rápido
Consulta rápida de datos mediante un índice agrupado
Acceso a datos mediante el protocolo OData y expresiones de filtro LINQ

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente sean seguros para subprocesos e independientes entre sí (guía). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Creación del cliente de Table service

En primer lugar, es necesario construir un TableServiceClient.

// Construct a new "TableServiceClient using a TableSharedKeyCredential.

var serviceClient = new TableServiceClient(
    new Uri(storageUri),
    new TableSharedKeyCredential(accountName, storageAccountKey));

Creación de una tabla de Azure

A continuación, podemos crear una nueva tabla.

// Create a new table. The TableItem class stores properties of the created table.
TableItem table = serviceClient.CreateTableIfNotExists(tableName);
Console.WriteLine($"The created table's name is {table.Name}.");

Obtención de una tabla de Azure

El conjunto de tablas de Azure existentes puede ser consultas mediante un filtro OData.

// Use the <see cref="TableServiceClient"> to query the service. Passing in OData filter strings is optional.

Pageable<TableItem> queryTableResults = serviceClient.Query(filter: $"TableName eq '{tableName}'");

Console.WriteLine("The following are the names of the tables in the query results:");

// Iterate the <see cref="Pageable"> in order to access queried tables.

foreach (TableItem table in queryTableResults)
{
    Console.WriteLine(table.Name);
}

Eliminación de una tabla de Azure

Las tablas individuales se pueden eliminar del servicio.

// Deletes the table made previously.
serviceClient.DeleteTable(tableName);

Creación del cliente table

Para interactuar con entidades de tabla, primero debemos construir un TableClient.

// Construct a new <see cref="TableClient" /> using a <see cref="TableSharedKeyCredential" />.
var tableClient = new TableClient(
    new Uri(storageUri),
    tableName,
    new TableSharedKeyCredential(accountName, storageAccountKey));

// Create the table in the service.
tableClient.Create();

Agregar entidades de tabla

Vamos a definir un nuevo TableEntity para que podamos agregarlo a la tabla.

// Make a dictionary entity by defining a <see cref="TableEntity">.
var tableEntity = new TableEntity(partitionKey, rowKey)
{
    { "Product", "Marker Set" },
    { "Price", 5.00 },
    { "Quantity", 21 }
};

Console.WriteLine($"{tableEntity.RowKey}: {tableEntity["Product"]} costs ${tableEntity.GetDouble("Price")}.");

Con ahora TableClient podemos agregar nuestra nueva entidad a la tabla.

// Add the newly created entity.
tableClient.AddEntity(tableEntity);

Consulta las entidades de tabla.

Para inspeccionar el conjunto de entidades de tabla existentes, podemos consultar la tabla mediante un filtro OData.

Pageable<TableEntity> queryResultsFilter = tableClient.Query<TableEntity>(filter: $"PartitionKey eq '{partitionKey}'");

// Iterate the <see cref="Pageable"> to access all queried entities.
foreach (TableEntity qEntity in queryResultsFilter)
{
    Console.WriteLine($"{qEntity.GetString("Product")}: {qEntity.GetDouble("Price")}");
}

Console.WriteLine($"The query returned {queryResultsFilter.Count()} entities.");

Si prefiere expresiones de consulta de estilo LINQ, también podemos consultar la tabla con esa sintaxis. Para demostrar esta sintaxis, necesitará un modelo fuertemente tipado, como el siguiente:

// Define a strongly typed entity by implementing the ITableEntity interface.
public class OfficeSupplyEntity : ITableEntity
{
    public string Product { get; set; }
    public double Price { get; set; }
    public int Quantity { get; set; }
    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public DateTimeOffset? Timestamp { get; set; }
    public ETag ETag { get; set; }
}

Dada esta definición de clase de modelo, esta es la forma en que escribiría una consulta:

double priceCutOff = 6.00;
Pageable<OfficeSupplyEntity> queryResultsLINQ = tableClient.Query<OfficeSupplyEntity>(ent => ent.Price >= priceCutOff);

Eliminar entidades de tabla

Si ya no necesitamos nuestra nueva entidad de tabla, se puede eliminar.

// Delete the entity given the partition and row key.
tableClient.DeleteEntity(partitionKey, rowKey);

Solución de problemas

Cuando se usa la biblioteca de tablas de Azure, los errores devueltos por el servicio se notifican mediante los mismos códigos de estado HTTP devueltos para las solicitudes de API REST .

Por ejemplo, si intenta crear una tabla que ya existe, se devuelve un 409 error, que indica "Conflicto".

// Construct a new TableClient using a connection string.

var client = new TableClient(
    connectionString,
    tableName);

// Create the table if it doesn't already exist.

client.CreateIfNotExists();

// Now attempt to create the same table unconditionally.

try
{
    client.Create();
}
catch (RequestFailedException ex) when (ex.Status == (int)HttpStatusCode.Conflict)
{
    Console.WriteLine(ex.ToString());
}

Configuración del registro de la consola

La manera más sencilla de ver los registros es habilitar el registro de la consola. Para crear un agente de escucha de registro del SDK de Azure que genere mensajes en la consola, use el método AzureEventSourceListener.CreateConsoleLogger.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Para más información sobre otros mecanismos de registro, consulte aquí.

Pasos siguientes

Empiece a trabajar con nuestros ejemplos de table.

Problemas conocidos

Puede encontrar una lista de problemas conocidos actualmente relacionados con los puntos de conexión de tabla de Cosmos DB aquí.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más información, visite cla.microsoft.com.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones