Inicio rápido: Azure Cosmos DB for Table para .NET
SE APLICA A: Table
En este inicio rápido, se muestra cómo empezar a trabajar con Azure Cosmos DB for Table desde una aplicación .NET. Azure Cosmos DB for Table es un almacén de datos sin esquema que permite a las aplicaciones almacenar datos de tabla estructurados en la nube. Aprenderá a crear tablas y filas, y a realizar tareas básicas en el recurso de Azure Cosmos DB mediante el paquete Azure.Data.Tables (NuGet).
Nota:
Los fragmentos de código de ejemplo están disponibles en GitHub como un proyecto de .NET.
Documentación de referencia sobre la API para Table | Paquete Azure.Data.Tables (NuGet)
Prerrequisitos
- Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
- Cuenta de GitHub
- Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
- CLI de desarrollo de Azure
- Docker Desktop
Instalación
Implemente el contenedor de desarrollo de este proyecto en su entorno. A continuación, use Azure Developer CLI (azd) para crear una cuenta de Azure Cosmos DB for Table e implementar una aplicación de ejemplo contenedorizada. La aplicación de ejemplo usa la biblioteca cliente para administrar, crear, leer y consultar datos de ejemplo.
Importante
Las cuentas de GitHub incluyen un derecho de almacenamiento y horas de núcleo sin costo alguno. Para obtener más información, consulte el almacenamiento y las horas de núcleo incluidas para las cuentas de GitHub.
Abra un terminal en el directorio raíz del proyecto.
Autentíquese en Azure Developer CLI mediante
azd auth login
. Siga los pasos especificados por la herramienta para autenticarse en la CLI mediante sus credenciales de Azure preferidas.azd auth login
Ejecute
azd init
para inicializar el proyecto.azd init
Durante la inicialización, configure un nombre de entorno único.
Sugerencia
El nombre del entorno también se usará como nombre del grupo de recursos de destino. Para este inicio rápido, considere la posibilidad de usar
msdocs-cosmos-db
.Implemente la cuenta de Azure Cosmos DB mediante
azd up
. Las plantillas de Bicep también implementan una aplicación web de muestra.azd up
Durante el proceso de aprovisionamiento, seleccione la suscripción y la ubicación deseada. Espere a que se complete el proceso de aprovisionamiento. El proceso puede tardar aproximadamente cinco minutos.
Una vez realizado el aprovisionamiento de los recursos de Azure, se incluye una dirección URL a la aplicación web en ejecución en la salida.
Deploying services (azd deploy) (✓) Done: Deploying service web - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io> SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
Use la dirección URL de la consola para ir a la aplicación web en el explorador. Observe la salida de la aplicación en ejecución.
Instalación de la biblioteca cliente
La biblioteca cliente está disponible a través de NuGet, como paquete Microsoft.Azure.Cosmos
.
Abra un terminal y vaya a la carpeta
/src/web
.cd ./src/web
Si aún no está instalado, instale el paquete
Azure.Data.Tables
mediantedotnet add package
.dotnet add package Azure.Data.Tables
Además, instale el paquete
Azure.Identity
si aún no está instalado.dotnet add package Azure.Identity
Abra y revise el archivo src/web/Cosmos.Samples.Table.Quickstart.Web.csproj para validar que existen ambas entradas,
Microsoft.Azure.Cosmos
yAzure.Identity
.
Ejemplos de código
- Autenticar el cliente
- de una tabla
- Creación de un elemento
- Obtención de un elemento
- Elementos de consulta
El código de ejemplo descrito en este artículo crea una base de datos denominada adventureworks
. Cada fila de la tabla contiene los detalles de un producto, como el nombre, la categoría, la cantidad y un indicador de venta. Cada producto también contiene un identificador único.
Usará las siguientes clases de la API para Table a fin de interactuar con estos recursos:
TableServiceClient
: esta clase proporciona métodos para realizar operaciones de nivel de servicio con Azure Cosmos DB for Table.TableClient
: esta clase permite interactuar con tablas hospedadas en Table API de Azure Cosmos DB.TableEntity
: esta clase es una referencia a una fila de una tabla que le permite administrar propiedades y datos de columnas.
Autenticar el cliente
En el directorio del proyecto, abra el archivo Program.cs. En el editor, agregue una directiva using para Azure.Data.Tables
.
using Azure.Data.Tables;
Defina una nueva instancia de la clase TableServiceClient
mediante el constructor y Environment.GetEnvironmentVariable
para leer la cadena de conexión que estableció anteriormente.
// New instance of the TableClient class
TableServiceClient tableServiceClient = new TableServiceClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));
Creación de una tabla
Recupere una instancia de TableClient
mediante la clase TableServiceClient
. Use el método TableClient.CreateIfNotExistsAsync
en TableClient
para crear una nueva tabla si aún no existe. Este método devolverá una referencia a la tabla existente o recién creada.
// New instance of TableClient class referencing the server-side table
TableClient tableClient = tableServiceClient.GetTableClient(
tableName: "adventureworks"
);
await tableClient.CreateIfNotExistsAsync();
Crear un elemento
La manera más fácil de crear un nuevo elemento en una tabla es crear una clase que implemente la interfaz ITableEntity
. A continuación, puede agregar sus propias propiedades a la clase para rellenar columnas de datos en esa fila de tabla.
// C# record type for items in the table
public record Product : ITableEntity
{
public string RowKey { get; set; } = default!;
public string PartitionKey { get; set; } = default!;
public string Name { get; init; } = default!;
public int Quantity { get; init; }
public bool Sale { get; init; }
public ETag ETag { get; set; } = default!;
public DateTimeOffset? Timestamp { get; set; } = default!;
}
Cree un elemento en la colección mediante la clase Product
llamando a TableClient.AddEntityAsync<T>
.
// Create new item using composite key constructor
var prod1 = new Product()
{
RowKey = "68719518388",
PartitionKey = "gear-surf-surfboards",
Name = "Ocean Surfboard",
Quantity = 8,
Sale = true
};
// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(prod1);
Obtención de un elemento
Puede recuperar un elemento específico de una tabla mediante el método TableEntity.GetEntityAsync<T>
. Proporcione partitionKey
y rowKey
como parámetros para identificar la fila correcta y realizar una rápida lectura de puntos de ese elemento.
// Read a single item from container
var product = await tableClient.GetEntityAsync<Product>(
rowKey: "68719518388",
partitionKey: "gear-surf-surfboards"
);
Console.WriteLine("Single product:");
Console.WriteLine(product.Value.Name);
Elementos de consulta
Después de insertar un elemento, también puede ejecutar una consulta para obtener todos los elementos que coincidan con un filtro específico mediante el método TableClient.Query<T>
. En este ejemplo se filtran los productos por categoría mediante la sintaxis Linq, que es una de las ventajas del uso de modelos ITableEntity
tipados como la clase Product
.
Nota
También puede consultar elementos mediante la sintaxis OData. Puede ver un ejemplo de este enfoque en el tutorial Datos de consulta.
// Read multiple items from container
var prod2 = new Product()
{
RowKey = "68719518390",
PartitionKey = "gear-surf-surfboards",
Name = "Sand Surfboard",
Quantity = 5,
Sale = false
};
await tableClient.AddEntityAsync<Product>(prod2);
var products = tableClient.Query<Product>(x => x.PartitionKey == "gear-surf-surfboards");
Console.WriteLine("Multiple products:");
foreach (var item in products)
{
Console.WriteLine(item.Name);
}
Ejecución del código
Esta aplicación crea una tabla de la API para Table de Azure Cosmos DB. A continuación, el ejemplo crea un elemento y luego lee el mismo elemento exactamente. Por último, en el ejemplo se crea un segundo elemento y se realiza una consulta que debe devolver varios elementos. Con cada paso, el ejemplo genera metadatos en la consola sobre los pasos que ha realizado.
Para ejecutar la aplicación, use un terminal para ir al directorio de la aplicación y ejecutarla.
dotnet run
La salida de la aplicación debe ser similar a este ejemplo:
Single product name:
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard
Limpieza de recursos
Cuando ya no necesite la cuenta de Azure Cosmos DB for Table, puede eliminar el grupo de recursos correspondiente.
Use el comando az group delete
para eliminar el grupo de recursos.
az group delete --name $resourceGroupName
Pasos siguientes
En este inicio rápido, ha aprendido a crear una cuenta de Azure Cosmos DB for Table, a crear una tabla y a administrar entradas mediante el SDK de .NET. Ahora puede profundizar más en el SDK para aprender a realizar tareas de administración y consultas de datos más avanzadas en los recursos de Azure Cosmos DB for Table.
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente las Cuestiones de GitHub como mecanismo de retroalimentación para el contenido y lo sustituiremos por un nuevo sistema de retroalimentación. Para más información, consulta:Enviar y ver comentarios de