Compartir a través de

Inicio rápido: Biblioteca de Azure Cosmos DB for Table para .NET

  • Artículo

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 SDK de Azure para .NET

Documentación de referencia de la API | Código fuente de la biblioteca | Paquete (NuGet) | Azure Developer CLI

Requisitos previos

Inicialización del proyecto

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.

  1. Abra un terminal en un directorio vacío.

  2. Si aún no está autenticado, 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

  3. Ejecute azd init para inicializar el proyecto.

    azd init --template cosmos-db-table-dotnet-quickstart

  4. Durante la inicialización, configure un nombre de entorno único.

  5. 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

  6. Durante el proceso de aprovisionamiento, seleccione la suscripción, la ubicación deseada y el grupo de recursos de destino. Espere a que se complete el proceso de aprovisionamiento. El proceso puede tardar aproximadamente cinco minutos.

  7. 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.

  8. 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.

    Captura de pantalla de la aplicación web en ejecución.

Instalación de la biblioteca cliente

La biblioteca cliente está disponible a través de NuGet, como paquete Azure.Data.Tables.

  1. Abra un terminal y vaya a la carpeta /src/web.

    cd ./src/web

  2. Si aún no está instalado, instale el paquete Azure.Data.Tables mediante dotnet add package.

    dotnet add package Azure.Data.Tables

  3. Abra y revise el archivo src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj para validar que existe las entrada Azure.Data.Tables.

Modelo de objetos

Nombre Descripción
TableServiceClient Esta clase es la clase de cliente principal y se usa para administrar bases de datos o metadatos de toda la cuenta.
TableClient Esta clase representa el cliente de una tabla dentro de la cuenta.

Ejemplos de código

En el código de ejemplo de la plantilla se usa una tabla denominada cosmicworks-products. La tabla cosmicworks-products contiene detalles como el nombre, la categoría, la cantidad, el precio, un identificador único y una marca de venta para cada producto. El contenedor usa un identificador único* como clave de fila y una categoría como clave de partición.

Autenticar el cliente

En este ejemplo se crea una nueva instancia de la clase TableServiceClient.

TableServiceClient serviceClient = new(
    endpoint: new Uri("<azure-cosmos-db-table-account-endpoint>"),
    credential
);

Obtención de una tabla

En este ejemplo se crea una instancia de la clase TableClient mediante el método GetTableClient de la clase TableServiceClient.

TableClient client = serviceClient.GetTableClient(
    tableName: "<azure-cosmos-db-table-name>"
);

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.

public record Product : ITableEntity
{
    public string RowKey { get; set; } = $"{Guid.NewGuid()}";

    public string PartitionKey { get; set; } = String.Empty;

    public string Name { get; set; } = String.Empty;

    public int Quantity { get; set; } = 0;

    public decimal Price { get; set; } = 0.0m;

    public bool Clearance { get; set; } = false;

    public ETag ETag { get; set; } = ETag.All;

    public DateTimeOffset? Timestamp { get; set; }
};

Cree un elemento en la colección mediante la clase Product llamando a TableClient.AddEntityAsync<T>.

Product entity = new()
{
    RowKey = "68719518391",
    PartitionKey = "gear-surf-surfboards",
    Name = "Surfboard",
    Quantity = 10,
    Price = 300.00m,
    Clearance = true
};

Response response = await client.UpsertEntityAsync<Product>(
    entity: entity,
    mode: TableUpdateMode.Replace
);

Obtención de un elemento

Puede recuperar un elemento específico de una tabla mediante el método TableClient.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.

Response<Product> response = await client.GetEntityAsync<Product>(
    rowKey: "68719518391",
    partitionKey: "gear-surf-surfboards"
);

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.

string category = "gear-surf-surfboards";

AsyncPageable<Product> results = client.QueryAsync<Product>(
    product => product.PartitionKey == category
);

Para analizar los resultados paginados de la consulta, ejecute un bucle en cada página de resultados mediante un bucle asincrónico.

List<Product> entities = new();
await foreach (Product product in results)
{
    entities.Add(product);
}

Limpieza de recursos

Cuando ya no necesite la aplicación o los recursos de ejemplo, quite la implementación correspondiente y todos los recursos.

azd down

Contenido relacionado