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

Lendo itens usando a chave composta

Cada item no Azure Cosmos DB for Table tem um identificador exclusivo especificado pela composição das chaves de linha e de partição. Essas chaves compostas são armazenadas como as propriedades RowKey e PartitionKey, respectivamente. No escopo de uma tabela, dois itens não podem compartilhar a mesma composição de identificador exclusivo.

O Azure Cosmos BD requer ambos, o identificador exclusivo e o valor da chave de partição, de um item para executar uma leitura do item. Especificamente, fornecer a chave composta executará uma leitura pontual rápida desse item com um custo previsível em RUs (unidades de solicitação).

Ler um item

Para executar uma leitura pontual de um item, chame use uma das seguintes estratégias:

Retornar um objeto TableEntity usando GetEntityAsync<>
Retornar um objeto de seu tipo usando GetEntityAsync<>

Ler um item usando uma classe interna

O ponto do exemplo a seguir lê um só item de modo assíncrono e retorna os resultados desserializados em um dicionário usando o tipo interno TableEntity:

// Read existing item from server-side table
TableEntity readItem = await tableClient.GetEntityAsync<TableEntity>(
    partitionKey: "68719518388",
    rowKey: "gear-surf-surfboards"
);

O método TableClient.GetEntityAsync<TableEntity> lê um item e retorna um objeto do tipo Response<TableEntity>. O tipo Resposta<> contém um operador de conversão implícita para converter o objeto em um objeto **TableEntity''.

Ler um item usando seu tipo

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 seguinte exemplo efetuar a leitura pontual de um item de modo assíncrono e retorna um item desserializado usando o tipo genérico fornecido:

// Read existing item from server-side table
Product readItem = await tableClient.GetEntityAsync<Product>(
    partitionKey: "68719518388",
    rowKey: "gear-surf-surfboards"
);

Importante

O tipo genérico usado com o método TableClient.GetEntityAsync<> deve implementar a interface ITableEntity.

O método TableClient.GetEntityAsync<> lê um item e retorna um objeto do tipo Response<>. O tipo Resposta<> contém um operador de conversão implícita para converter o objeto no tipo genérico. Para saber mais sobre operadores implícitos, confira Operadores de conversão definidos pelo usuário.

Próximas etapas

Agora que você leu vários itens, experimente um dos nossos tutoriais sobre a consulta de dados do Azure Cosmos DB for Table.

Consultar o Azure Cosmos DB usando a API for Table

Compartilhar via