Tutorial: Consultar o Azure Cosmos DB usando a API de TabelaTutorial: Query Azure Cosmos DB by using the Table API

A API de Tabela do Azure Cosmos DB oferece suporte a consultas de OData e LINQ em dados de chave/valor (tabela).The Azure Cosmos DB Table API supports OData and LINQ queries against key/value (table) data.

Este artigo aborda as seguintes tarefas:This article covers the following tasks:

  • Consultar dados com a API de TabelaQuerying data with the Table API

As consultas neste artigo usam a seguinte tabela de exemplo People:The queries in this article use the following sample People table:

PartitionKeyPartitionKey RowKeyRowKey EmailEmail PhoneNumberPhoneNumber
HarpHarp WalterWalter Walter@contoso.com 425-555-0101425-555-0101
SmithSmith BenBen Ben@contoso.com 425-555-0102425-555-0102
SmithSmith JeffJeff Jeff@contoso.com 425-555-0104425-555-0104

Consulte Consultar tabelas e entidades para obter detalhes sobre como executar consultas usando a API de tabela.See Querying Tables and Entities for details on how to query by using the Table API.

Para obter mais informações sobre os recursos premium que o Azure Cosmos DB oferece, consulte Azure Cosmos DB API de Tabela e Desenvolver com a API de Tabela em .NET.For more information on the premium capabilities that Azure Cosmos DB offers, see Azure Cosmos DB Table API and Develop with the Table API in .NET.

Pré-requisitosPrerequisites

Para essas consultas funcionarem, você deve ter uma conta do Azure Cosmos DB e ter dados de entidade no contêiner.For these queries to work, you must have an Azure Cosmos DB account and have entity data in the container. Não tenho nenhum deles?Don't have any of those? Complete o Guia de início rápido de cinco minutos ou o tutorial de desenvolvedor para criar uma conta e preencher seu banco de dados.Complete the five-minute quickstart or the developer tutorial to create an account and populate your database.

Consultar em PartitionKey e RowKeyQuery on PartitionKey and RowKey

Como as propriedades PartitionKey e RowKey formam a chave primária de uma entidade, é possível utilizar a seguinte sintaxe especial para identificar a entidade:Because the PartitionKey and RowKey properties form an entity's primary key, you can use the following special syntax to identify the entity:

ConsultaQuery

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

ResultadosResults

PartitionKeyPartitionKey RowKeyRowKey EmailEmail PhoneNumberPhoneNumber
HarpHarp WalterWalter Walter@contoso.com 425-555-0104425-555-0104

Como alternativa, você pode especificar essas propriedades como parte da opção $filter, conforme mostra a seção a seguir.Alternatively, you can specify these properties as part of the $filter option, as shown in the following section. Observe que os nomes de propriedade de chave e valores constantes diferenciam maiúsculas de minúsculas.Note that the key property names and constant values are case-sensitive. As propriedades PartitionKey e RowKey são do tipo Cadeia de caracteres.Both the PartitionKey and RowKey properties are of type String.

Consultar utilizando um filtro ODataQuery by using an OData filter

Ao construir uma cadeia de caracteres de filtro, lembre-se destas regras:When you're constructing a filter string, keep these rules in mind:

  • Use os operadores lógicos definidos pela Especificação do Protocolo OData para comparar uma propriedade a um valor.Use the logical operators defined by the OData Protocol Specification to compare a property to a value. Observe que você não pode comparar uma propriedade com um valor dinâmico.Note that you can't compare a property to a dynamic value. Um lado da expressão deve ser uma constante.One side of the expression must be a constant.
  • O nome da propriedade, o operador e um valor constante devem ser separados por espaços codificados por URL.The property name, operator, and constant value must be separated by URL-encoded spaces. Um espaço é codificado por URL como %20.A space is URL-encoded as %20.
  • Todas as partes da cadeia de caracteres de filtro diferenciam maiúsculas de minúsculas.All parts of the filter string are case-sensitive.
  • O valor da constante deve ser do mesmo tipo de dados como a propriedade para que o filtro retorne resultados válidos.The constant value must be of the same data type as the property in order for the filter to return valid results. Para obter informações sobre tipos de propriedades com suporte, consulte Noções básicas sobre o modelo de dados do serviço Tabela.For more information about supported property types, see Understanding the Table Service Data Model.

Veja um exemplo de consulta que mostra como filtrar por PartitionKey e as propriedades de Email usando um OData $filter.Here's an example query that shows how to filter by the PartitionKey and Email properties by using an OData $filter.

ConsultaQuery

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

Para obter mais informações sobre como construir expressões de filtro para vários tipos de dados, consulte Consultar tabelas e entidades.For more information on how to construct filter expressions for various data types, see Querying Tables and Entities.

ResultadosResults

PartitionKeyPartitionKey RowKeyRowKey EmailEmail PhoneNumberPhoneNumber
SmithSmith BenBen Ben@contoso.com 425-555-0102425-555-0102

Consultar utilizando LINQQuery by using LINQ

Você também pode consultar utilizando o LINQ, o que resulta em expressões de consulta Odata correspondentes.You can also query by using LINQ, which translates to the corresponding OData query expressions. Veja um exemplo de como criar consultas usando o SDK do .NET.:Here's an example of how to build queries by using the .NET SDK:

CloudTableClient tableClient = account.CreateCloudTableClient();
CloudTable table = tableClient.GetTableReference("People");

TableQuery<CustomerEntity> query = new TableQuery<CustomerEntity>()
    .Where(
        TableQuery.CombineFilters(
            TableQuery.GenerateFilterCondition("PartitionKey", QueryComparisons.Equal, "Smith"),
            TableOperators.And,
            TableQuery.GenerateFilterCondition("Email", QueryComparisons.Equal,"Ben@contoso.com")
    ));

await table.ExecuteQuerySegmentedAsync<CustomerEntity>(query, null);

Próximas etapasNext steps

Neste tutorial, você fez o seguinte:In this tutorial, you've done the following:

  • Aprendeu a consultar utilizando a API de TabelaLearned how to query by using the Table API

Agora você pode prosseguir para o próximo tutorial e aprender a distribuir seus dados globalmente.You can now proceed to the next tutorial to learn how to distribute your data globally.