Biblioteca cliente de Azure Tables para .NET: versión 12.8.1
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 APIMuestras | Registro de cambios
Instale la biblioteca cliente de Azure Tables para .NET con NuGet:
dotnet add package Azure.Data.Tables
- 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.
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
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
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.
TableServiceClient
- Cliente que proporciona métodos para interactuar en el nivel de Table Service, como crear, enumerar y eliminar tablasTableClient
- 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
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.
Opciones | de clienteAcceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente
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));
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}.");
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);
}
Las tablas individuales se pueden eliminar del servicio.
// Deletes the table made previously.
serviceClient.DeleteTable(tableName);
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();
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);
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);
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);
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());
}
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í.
Empiece a trabajar con nuestros ejemplos de table.
Puede encontrar una lista de problemas conocidos actualmente relacionados con los puntos de conexión de tabla de Cosmos DB aquí.
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.