Tutorial: Consultar o Azure Cosmos DB usando a API para Tabela

Artigo
08/15/2024

APLICA-SE A: Tabela

O Azure Cosmos DB for Table dá suporte a consultas OData e LINQ em dados de chave/valor (tabela).

Este artigo abrange as seguintes tarefas:

Consultando dados com a API para Tabela

As consultas neste artigo utilizam a tabela People de exemplo seguinte:

PartitionKey	RowKey	E-mail	PhoneNumber
Harp	Walter	Walter@contoso.com	425-555-0101
Smith	Ben	Ben@contoso.com	425-555-0102
Smith	Jeff	Jeff@contoso.com	425-555-0104

Para obter detalhes sobre como consultar usando a API para Tabela, consulte Consultando tabelas e entidades.

Pré-requisitos

Para estas consultas funcionarem, tem de ter uma conta do Azure Cosmos DB e dados de entidade no contentor. Se você não tiver uma conta ou dados, conclua Guia de início rápido: Azure Cosmos DB for Table for .NET para criar uma conta e preencher seu banco de dados.

Consultar em PartitionKey e RowKey

Uma vez que as propriedades PartitionKey e RowKey formam a chave primária de uma entidade, pode utilizar a seguinte sintaxe especial para identificar a entidade:

Consulta

https://<mytableendpoint>/People(PartitionKey='Harp',RowKey='Walter')

Resultados

PartitionKey	RowKey	E-mail	PhoneNumber
Harp	Walter	Walter@contoso.com	425-555-0104

Em alternativa, pode especificar estas propriedades como parte da opção $filter, conforme mostrado na secção seguinte. Os nomes das propriedades de chave e os valores constantes diferenciam maiúsculas de minúsculas. As propriedades PartitionKey e RowKey são do tipo String.

Consultar com um filtro OData

Quando estiver a criar uma cadeia de filtro, não se esqueça destas regras:

Utilize os operadores lógicos definidos pela Especificação do Protocolo OData para comparar uma propriedade a um valor. Não é possível comparar uma propriedade com um valor dinâmico. Um lado da expressão tem de ser uma constante.
Os espaços codificados por URL devem separar o nome da propriedade, o operador e o valor constante. Um espaço tem codificação URL como %20.
Todas as partes da cadeia de filtro são sensíveis a maiúsculas e minúsculas.
O valor constante tem de ser do mesmo tipo de dados da propriedade para que o filtro devolva resultados válidos. Para obter mais informações sobre tipos de propriedade suportados, consulte Noções básicas sobre o modelo de dados do serviço Tabela.

Segue-se uma consulta de exemplo que mostra como filtrar pelas propriedades PartitionKey e Email com um $filter OData.

Consulta

https://<mytableapi-endpoint>/People()?$filter=PartitionKey%20eq%20'Smith'%20and%20Email%20eq%20'Ben@contoso.com'

Para obter mais informações sobre como criar expressões de filtro para vários tipos de dados, veja Consultar Tabelas e Entidades.

Resultados

PartitionKey	RowKey	E-mail	PhoneNumber
Smith	Ben	Ben@contoso.com	425-555-0102

As consultas em propriedades datetime não retornam dados quando executadas na API para Tabela do Azure Cosmos DB. Enquanto o armazenamento de Tabela do Azure armazena valores de data com granularidade de tempo de ticks, a API para Tabela no Azure Cosmos DB usa a _ts propriedade. A _ts propriedade está em um segundo nível de granularidade, que não é um filtro OData. O Azure Cosmos DB bloqueia as consultas nas propriedades de carimbo de data/hora. Como solução alternativa, você pode definir uma propriedade de tipo de dados datetime ou long personalizada e definir o valor de data do cliente.

Consultar com o LINQ

Também pode consultar com o LINQ, que traduz as expressões de consulta OData correspondentes. Segue-se um exemplo de como criar consultas com o SDK .NET:

IQueryable<CustomerEntity> linqQuery = table.CreateQuery<CustomerEntity>()
            .Where(x => x.PartitionKey == "4")
            .Select(x => new CustomerEntity() { PartitionKey = x.PartitionKey, RowKey = x.RowKey, Email = x.Email });

Próximos passos

Agora pode avançar para o tutorial seguinte para saber como distribuir dados globalmente.

Configurar a distribuição global do Azure Cosmos DB usando a API para Tabela

Partilhar via