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

Artigo
08/15/2024

APLICA-SE AO: Table

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

Criar um identificador exclusivo para um item

O identificador exclusivo, programaticamente conhecido 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 do item. Ambas as chaves são necessárias ao criar um novo item dentro de uma tabela.

Dentro do escopo de uma tabela, dois itens não podem compartilhar a mesma chave de linha e chave de partição.

Criar um item

A classe TableEntity é 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 TableEntityclasse
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 apenas com as propriedades necessárias. Em seguida, você pode usar o método Add 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 método TableClient.AddEntityAsync<> usa um parâmetro do tipo TableEntity e cria um item do lado do servidor na tabela.

Implementar interface

Observação

Os exemplos nesta seção pressupõem que você já tenha definido um tipo C# chamado Produto para representar seus dados:

// 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 método TableClient.AddEntityAsync<> usa um parâmetro de qualquer tipo que implemente a ITableEntity interface. A interface já inclui as propriedades necessárias RowKey e PartitionKey.

Por exemplo, você pode criar um novo objeto que implemente 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óximas etapas

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

Ler um item

Compartilhar via