Samouczek: wykonywanie zapytań w usłudze Azure Cosmos DB przy użyciu interfejsu API tabelTutorial: Query Azure Cosmos DB by using the Table API

Interfejs API tabel usługi Azure Cosmos DB obsługuje zapytania OData i LINQ dla danych klucz-wartość (tabeli).The Azure Cosmos DB Table API supports OData and LINQ queries against key/value (table) data.

W tym artykule opisano następujące zadania:This article covers the following tasks:

  • Wykonywanie zapytania o dane przy użyciu interfejsu API tabelQuerying data with the Table API

Zapytania w tym artykule korzystają z następującej przykładowej tabeli 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 JanJeff Jeff@contoso.com 425-555-0104425-555-0104

Zobacz Wykonywanie zapytań względem tabel i jednostek, aby uzyskać szczegółowe informacje na temat wykonywania zapytań przy użyciu interfejsu API tabel.See Querying Tables and Entities for details on how to query by using the Table API.

Aby uzyskać więcej informacji na temat funkcji premium oferowanych przez usługę Azure Cosmos DB, zobacz Interfejs API tabel usługi Azure Cosmos DB i Opracowywanie zawartości przy użyciu interfejsu API tabel na platformie .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.

Wymagania wstępnePrerequisites

Aby te zapytania działały, musisz mieć konto usługi Azure Cosmos DB i mieć dane jednostki w kontenerze.For these queries to work, you must have an Azure Cosmos DB account and have entity data in the container. Nie spełniasz tych warunków?Don't have any of those? Ukończ pięciominutowy przewodnik Szybki start lub samouczek dewelopera, aby utworzyć konto i wypełnić bazę danych.Complete the five-minute quickstart or the developer tutorial to create an account and populate your database.

Zapytanie dotyczące właściwości PartitionKey i RowKeyQuery on PartitionKey and RowKey

Ponieważ właściwości PartitionKey i RowKey tworzą klucz podstawowy jednostki, do zidentyfikowania jednostki można użyć następującej specjalnej składni:Because the PartitionKey and RowKey properties form an entity's primary key, you can use the following special syntax to identify the entity:

ZapytanieQuery

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

ResultsResults

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

Można także określić te właściwości jako część opcji $filter, jak pokazano w poniższej sekcji.Alternatively, you can specify these properties as part of the $filter option, as shown in the following section. Należy pamiętać, że w nazwach właściwości kluczy i wartościach stałych jest rozróżniana wielkość liter.Note that the key property names and constant values are case-sensitive. Właściwości PartitionKey i RowKey są typu String.Both the PartitionKey and RowKey properties are of type String.

Wykonywanie zapytań przy użyciu filtru ODataQuery by using an OData filter

Podczas tworzenia ciągu filtru należy pamiętać o następujących regułach:When you're constructing a filter string, keep these rules in mind:

  • Aby porównać właściwość z wartością, użyj operatorów logicznych określonych w specyfikacji protokołu OData.Use the logical operators defined by the OData Protocol Specification to compare a property to a value. Pamiętaj, że nie można porównać właściwości z wartością dynamiczną.Note that you can't compare a property to a dynamic value. Jedna strona wyrażenia musi być stałą.One side of the expression must be a constant.
  • Nazwa właściwości, operator i wartość stała muszą być oddzielone spacjami zakodowanymi w adresie URL.The property name, operator, and constant value must be separated by URL-encoded spaces. Spacja jest zakodowana w adresie URL jako %20.A space is URL-encoded as %20.
  • We wszystkich częściach ciągu filtru jest rozróżniana wielkość liter.All parts of the filter string are case-sensitive.
  • Wartość stała musi mieć ten sam typ danych co właściwość, aby filtr zwracał prawidłowe wyniki.The constant value must be of the same data type as the property in order for the filter to return valid results. Aby uzyskać szczegółowe informacje na temat obsługiwanych typów właściwości, zobacz Omówienie modelu danych usługi Table service.For more information about supported property types, see Understanding the Table Service Data Model.

Poniżej przedstawiono przykładowe zapytanie, które pokazuje sposób filtrowania według właściwości PartitionKey i Email przy użyciu elementu $filter OData.Here's an example query that shows how to filter by the PartitionKey and Email properties by using an OData $filter.

ZapytanieQuery

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

Aby uzyskać więcej informacji na temat sposobu tworzenia wyrażenia filtru dla różnych typów danych, zobacz Wykonywanie zapytań względem tabel i jednostek.For more information on how to construct filter expressions for various data types, see Querying Tables and Entities.

ResultsResults

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

Wykonywanie zapytań za pomocą wyrażenia LINQQuery by using LINQ

Możesz także wykonywać zapytania za pomocą wyrażenia LINQ, co oznacza odpowiednie wyrażenia zapytań OData.You can also query by using LINQ, which translates to the corresponding OData query expressions. Oto przykład sposobu tworzenia zapytań przy użyciu zestawu .NET SDK: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);

Kolejne krokiNext steps

W tym samouczku wykonano następujące czynności:In this tutorial, you've done the following:

  • Przedstawiono sposób wykonywania zapytań przy użyciu interfejsu API tabelLearned how to query by using the Table API

Możesz teraz przejść do następnego samouczka, aby dowiedzieć się, jak dystrybuować swoje dane globalnie.You can now proceed to the next tutorial to learn how to distribute your data globally.