Comparteix a través de

Creación de un elemento en Azure Cosmos DB for Table mediante .NET

  • Article

SE APLICA A: Table

Los elementos de Azure Cosmos DB representan una entidad específica almacenada dentro de una tabla. En la API para Table, un elemento consta de un conjunto de pares clave-valor identificados de forma única por la composición de las claves de fila y partición.

Creación de un identificador único para un elemento

El identificador único, conocido mediante programación como el *** es una cadena distinta que identifica un elemento dentro de una tabla. Cada elemento también incluye un valor de clave de partición que se usa para determinar la partición lógica del elemento. Ambas claves son necesarias al crear un nuevo elemento dentro de una tabla.

Dentro del ámbito de una tabla, dos elementos no pueden compartir la misma clave de fila ni clave de partición.

Crear un elemento

La clase TableEntity es una implementación genérica de un diccionario diseñado de forma única para facilitar la creación de un nuevo elemento a partir de un diccionario arbitrario de pares clave-valor.

Use una de las estrategias siguientes para modelar los elementos que desea crear en una tabla:

Use una clase integrada

El constructor (string rowKey, string partitionKey) de la clase TableEntity es una manera rápida de crear un elemento con solo las propiedades necesarias. A continuación, puede usar el método Add para agregar pares clave-valor adicionales al elemento.

Por ejemplo, puede crear una nueva instancia de la clase TableEntity especificando primero las claves de fila y partición en el constructor y, a continuación, agregando nuevos pares clave-valor al diccionario:

// Create new item using composite key constructor
TableEntity item1 = new(
    rowKey: "68719518388",
    partitionKey: "gear-surf-surfboards"
);

// Add properties to item
item1.Add("Name", "Sunnox Surfboard");
item1.Add("Quantity", 8);
item1.Add("Sale", true);

// Add new item to server-side table
await tableClient.AddEntityAsync<TableEntity>(item1);

El constructor (IDictionary<string, object>) de la clase TableEntity convierte un diccionario existente en un elemento listo para agregarse a una tabla.

Por ejemplo, puede pasar un diccionario a una nueva instancia de la clase TableEntity:

// Create dictionary
Dictionary<string, object> properties = new()
{
    { "RowKey", "68719518388" },
    { "PartitionKey", "gear-surf-surfboards" },
    { "Name", "Sunnox Surfboard" },
    { "Quantity", 8 },
    { "Sale", true }
};

// Create new item using dictionary constructor
TableEntity item2 = new(
    values: properties
);

// Add new item to server-side table
await tableClient.AddEntityAsync<TableEntity>(item2);

El método TableClient.AddEntityAsync<> toma un parámetro de tipo TableEntity y, a continuación, crea un elemento del lado del servidor en la tabla.

Implementación de interfaz

Nota

En los ejemplos de esta sección se supone que ya ha definido un tipo de C# para representar los datos denominados Product:

// 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!;
}

El método TableClient.AddEntityAsync<> toma un parámetro de cualquier tipo que implementa la interfaz ITableEntity. La interfaz ya incluye las propiedades RowKey y PartitionKey requeridas.

Por ejemplo, puede crear un nuevo objeto que implemente al menos todas las propiedades necesarias en la interfaz ITableEntity:

// Create new item
Product item = new()
{
    RowKey = "68719518388",
    PartitionKey = "gear-surf-surfboards",
    Name = "Sunnox Surfboard",
    Quantity = 8,
    Sale = true
};

A continuación, puede pasar este objeto al método AddEntityAsync<> creando un elemento del lado del servidor:

// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(item);

Pasos siguientes

Ahora que ha creado varios elementos, use la siguiente guía para leer un elemento.

Lectura de un elemento