Criar um item no Azure Cosmos DB for Table usando o .NET

Artigo
08/15/2024

APLICA-SE A: Tabela

Os itens no Azure Cosmos DB representam uma entidade específica armazenada em uma tabela. Na API para Tabela, um item consiste em um conjunto de pares chave-valor identificados exclusivamente pela composição das chaves de linha e partição.

Criar um identificador exclusivo para um item

O identificador exclusivo, conhecido programaticamente como **** é uma cadeia de caracteres distinta que identifica um item dentro de uma tabela. Cada item também inclui um valor de chave de partição que é usado para determinar a partição lógica para o item. Ambas as chaves são necessárias ao criar um novo item dentro de uma tabela.

No âmbito de uma tabela, dois itens não podem partilhar a mesma chave de linha e a mesma chave de partição.

Criar um item

A TableEntity classe é uma implementação genérica de um dicionário que é projetado exclusivamente para facilitar a criação de um novo item a partir de um dicionário arbitrário de pares chave-valor.

Use uma das seguintes estratégias para modelar itens que você deseja criar em uma tabela:

Criar uma instância da TableEntity classe
Implementar a ITableEntity interface

Usar uma classe interna

O (string rowKey, string partitionKey) construtor da classe TableEntity é uma maneira rápida de criar um item com apenas as propriedades necessárias. Em seguida, você pode usar o Add método para adicionar pares chave-valor extras ao item.

Por exemplo, você pode criar uma nova instância da classe TableEntity especificando primeiro as chaves de linha e partição no construtor e, em seguida, adicionando novos pares chave-valor ao dicionário:

// 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);

O (IDictionary<string, object>) construtor da classe TableEntity converte um dicionário existente em um item pronto para ser adicionado a uma tabela.

Por exemplo, você pode passar um dicionário para uma nova instância da classe 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);

O TableClient.AddEntityAsync<> método recebe um parâmetro do tipo TableEntity e, em seguida, cria um item do lado do servidor na tabela.

Implementar interface

Nota

Os exemplos nesta seção pressupõem que você já definiu um tipo de C# para representar seus dados chamado 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!;
}

O TableClient.AddEntityAsync<> método leva em um parâmetro de qualquer tipo que implementa a ITableEntity interface. A interface já inclui o necessário RowKey e PartitionKey as propriedades.

Por exemplo, você pode criar um novo objeto que implementa pelo menos todas as propriedades necessárias na interface ITableEntity :

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

Em seguida, você pode passar esse objeto para o método AddEntityAsync<> criando um item do lado do servidor:

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

Próximos passos

Agora que você criou vários itens, use o próximo guia para ler um item.

Ler um item

Partilhar via