教學課程:使用資料表 API 查詢 Azure Cosmos DBTutorial: Query Azure Cosmos DB by using the Table API

Azure Cosmos DB 資料表 API 支援對索引鍵/值 (資料表) 資料進行 OData 和 LINQ 查詢。The Azure Cosmos DB Table API supports OData and LINQ queries against key/value (table) data.

本文涵蓋下列工作:This article covers the following tasks:

  • 使用資料表 API 來查詢資料Querying data with the Table API

本文中的查詢使用下列範例 People 資料表:The queries in this article use the following sample People table:

PartitionKeyPartitionKey RowKeyRowKey 電子郵件Email 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

如需怎樣使用資料表 API 進行查詢的詳細資料,請參閱查詢資料表和實體See Querying Tables and Entities for details on how to query by using the Table API.

如需 Azure Cosmos DB 所提供之進階功能的詳細資訊,請參閱 Azure Cosmos DB:資料表 API在 .NET 中使用資料表 API 進行開發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.

必要條件Prerequisites

若要讓這些查詢能夠運作,您必須具備 Azure Cosmos DB 帳戶,並且在容器中有實體資料。For these queries to work, you must have an Azure Cosmos DB account and have entity data in the container. 不符合上述其中任何一項條件嗎?Don't have any of those? 請完成 5 分鐘快速入門開發人員教學課程,以建立帳戶並在資料庫中填入資料。Complete the five-minute quickstart or the developer tutorial to create an account and populate your database.

在 PartitionKey 和 RowKey 上執行查詢Query on PartitionKey and RowKey

由於 PartitionKey 和 RowKey 屬性會構成實體的主索引鍵,因此您可以使用下列特殊語法來識別實體:Because the PartitionKey and RowKey properties form an entity's primary key, you can use the following special syntax to identify the entity:

查詢Query

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

結果Results

PartitionKeyPartitionKey RowKeyRowKey 電子郵件Email PhoneNumberPhoneNumber
HarpHarp WalterWalter Walter@contoso.com 425-555-0104425-555-0104

或者,您也可以在指定 $filter 選項時一併指定這些屬性,如下一節中所示。Alternatively, you can specify these properties as part of the $filter option, as shown in the following section. 請注意,索引鍵屬性名稱和常數值有區分大小寫。Note that the key property names and constant values are case-sensitive. PartitionKey 和 RowKey 屬性的類型都是 String。Both the PartitionKey and RowKey properties are of type String.

使用 OData 篩選進行查詢Query by using an OData filter

建構篩選字串時,請牢記下列規則:When you're constructing a filter string, keep these rules in mind:

  • 使用「OData 通訊協定規格」所定義的邏輯運算子來比較屬性與值。Use the logical operators defined by the OData Protocol Specification to compare a property to a value. 請注意,您無法比較屬性與動態值。Note that you can't compare a property to a dynamic value. 運算式的一端必須是常數。One side of the expression must be a constant.
  • 屬性名稱、運算子及常數值必須以 URL 編碼的空格分隔。The property name, operator, and constant value must be separated by URL-encoded spaces. 空格經 URL 編碼後會變成 %20A space is URL-encoded as %20.
  • 篩選字串的所有部分都區分大小寫。All parts of the filter string are case-sensitive.
  • 常數和屬性必須是相同的資料類型,篩選才能傳回有效的結果。The constant value must be of the same data type as the property in order for the filter to return valid results. 如需支援的屬性類型的詳細資訊,請參閱 了解表格服務資料模型For more information about supported property types, see Understanding the Table Service Data Model.

以下是一個範例查詢,說明如如何使用 OData $filter 依 PartitionKey 和 Email 屬性進行篩選。Here's an example query that shows how to filter by the PartitionKey and Email properties by using an OData $filter.

查詢Query

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

如需如何針對各種資料類型建構篩選條件運算式的詳細資訊,請參閱查詢資料表和實體For more information on how to construct filter expressions for various data types, see Querying Tables and Entities.

結果Results

PartitionKeyPartitionKey RowKeyRowKey 電子郵件Email PhoneNumberPhoneNumber
SmithSmith BenBen Ben@contoso.com 425-555-0102425-555-0102

使用 LINQ 進行查詢Query by using LINQ

您也可以使用 LINQ 進行查詢,這會轉譯成對應的 OData 查詢運算式。You can also query by using LINQ, which translates to the corresponding OData query expressions. 以下是一個範例,說明如何使用 .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);

後續步驟Next steps

在本教學課程中,您已完成下列操作:In this tutorial, you've done the following:

  • 了解如何使用資料表 API 來進行查詢Learned how to query by using the Table API

您現在可以繼續進行到下一個教學課程,以了解如何全域散發您的資料。You can now proceed to the next tutorial to learn how to distribute your data globally.