Azure Cosmos DB: procedura per l'esecuzione di query sui dati della tabella con l'API di tabellaAzure Cosmos DB: How to query table data by using the Table API

L'API di tabella di Azure Cosmos DB supporta l'esecuzione di query OData e LINQ sui dati chiave/valore (tabella).The Azure Cosmos DB Table API supports OData and LINQ queries against key/value (table) data.

Questo articolo illustra le attività seguenti:This article covers the following tasks:

  • Esecuzione di query sui dati con l'API TableQuerying data with the Table API

Le query di questo articolo usano la tabella di esempio 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

Vedere Querying Tables and Entities (Esecuzione di query su tabelle ed entità) per informazioni dettagliate su come eseguire una query con l'API di tabella.See Querying Tables and Entities for details on how to query by using the Table API.

Per altre informazioni sulle funzionalità Premium offerte da Azure Cosmos DB, vedere Introduzione all'API di tabella di Azure Cosmos DB e Sviluppare con l'API di tabella in .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.

PrerequisitiPrerequisites

Per il funzionamento di queste query è necessario disporre di un account Azure Cosmos DB e nel contenitore devono essere presenti dati di entità.For these queries to work, you must have an Azure Cosmos DB account and have entity data in the container. Questi requisiti non sono disponibili?Don't have any of those? Completare la Guida introduttiva di 5 minuti o l'esercitazione per sviluppatori per creare un account e popolare il database.Complete the five-minute quickstart or the developer tutorial to create an account and populate your database.

Query su PartitionKey e RowKeyQuery on PartitionKey and RowKey

Poiché le proprietà PartitionKey e RowKey costituiscono la chiave primaria di un'entità, è possibile usare la sintassi speciale seguente per identificare l'entità:Because the PartitionKey and RowKey properties form an entity's primary key, you can use the following special syntax to identify the entity:

QueryQuery

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

RisultatiResults

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

In alternativa, è possibile specificare queste proprietà come parte dell'opzione $filter, come illustrato nella sezione seguente.Alternatively, you can specify these properties as part of the $filter option, as shown in the following section. Si noti che i nomi delle proprietà chiave e i valori costanti distinguono tra maiuscole e minuscole.Note that the key property names and constant values are case-sensitive. Entrambe le proprietà PartitionKey e RowKey sono di tipo String.Both the PartitionKey and RowKey properties are of type String.

Eseguire una query usando un filtro ODataQuery by using an OData filter

Quando si crea una stringa di filtro, tenere presente queste regole:When you're constructing a filter string, keep these rules in mind:

  • Usare gli operatori logici definiti dalla specifica del protocollo OData per confrontare una proprietà con un valore.Use the logical operators defined by the OData Protocol Specification to compare a property to a value. Si noti che non è possibile confrontare una proprietà con un valore dinamico.Note that you can't compare a property to a dynamic value. Un lato dell'espressione deve essere una costante.One side of the expression must be a constant.
  • Il nome della proprietà, l'operatore e il valore costante devono essere separati da spazi con codifica URL.The property name, operator, and constant value must be separated by URL-encoded spaces. Uno spazio con codifica URL è come %20.A space is URL-encoded as %20.
  • Viene effettuata la distinzione tra maiuscole e minuscole per tutte le parti della stringa di filtro.All parts of the filter string are case-sensitive.
  • Il valore costante deve essere dello stesso tipo di dati della proprietà affinché il filtro restituisca risultati validi.The constant value must be of the same data type as the property in order for the filter to return valid results. Per altre informazioni sui tipi di proprietà supportati, vedere Informazioni sul modello di dati del servizio tabelle.For more information about supported property types, see Understanding the Table Service Data Model.

La query di esempio illustra come filtrare in base alla proprietà PartitionKey Email usando un $filter ODATA.Here's an example query that shows how to filter by the PartitionKey and Email properties by using an OData $filter.

QueryQuery

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

Per altre informazioni su come creare espressioni filtro per vari tipi di dati sono disponibili in Querying Tables and Entities (Esecuzione di query su tabelle ed entità).For more information on how to construct filter expressions for various data types, see Querying Tables and Entities.

RisultatiResults

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

Eseguire una query utilizzando LINQQuery by using LINQ

È anche possibile eseguire query con LINQ, che consente di tradurle nelle corrispondenti espressioni di query OData.You can also query by using LINQ, which translates to the corresponding OData query expressions. L'esempio seguente mostra come compilare le query usando .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);

Passaggi successiviNext steps

In questa esercitazione sono state eseguite le operazioni seguenti:In this tutorial, you've done the following:

  • È stato appreso come eseguire query usando l'API di tabellaLearned how to query by using the Table API

È ora possibile passare all'esercitazione successiva per imparare a distribuire i dati a livello globale.You can now proceed to the next tutorial to learn how to distribute your data globally.