Interrogation de tables et d’entitésQuerying tables and entities

L'interrogation de tables et d'entités dans le service de Table nécessite une construction appropriée de l'URI de la demande.Querying tables and entities in the Table service requires careful construction of the request URI. Les sections suivantes décrivent les options de requête et des scénarios courants.The following sections describe query options and demonstrate some common scenarios.

Syntaxe de requête de baseBasic Query Syntax

Pour retourner toutes les tables dans un compte de stockage donné, effectuez une GET opération sur la ressource tables, comme décrit dans l’opération tables de requête .To return all of the tables in a given storage account, perform a GET operation on the Tables resource, as described in the Query Tables operation. L'URI de base pour l'adressage de la ressource Tables est le suivant :The basic URI for addressing the Tables resource is as follows:

https://myaccount.table.core.windows.net/Tables  

Pour retourner une unique table nommée, indiquez cette table comme suit :To return a single named table, specify that table as follows:

https://myaccount.table.core.windows.net/Tables('MyTable')  

Pour retourner toutes les entités d'une table, indiquez le nom de la table dans l'URI, sans la ressource Tables :To return all entities in a table, specify the table name on the URI, without the Tables resource:

https://myaccount.table.core.windows.net/MyTable()  

Les résultats de la requête sont triés par PartitionKey, puis par RowKey.Query results are sorted by PartitionKey, then by RowKey. Un ordre de tri des résultats différent n'est actuellement pas pris en charge.Ordering results in any other way is not currently supported.

Vous pouvez spécifier des options supplémentaires pour limiter l'ensemble de tables ou d'entités retourné, comme décrit dans la section suivante Options de requête prises en charge.You can specify additional options to limit the set of tables or entities returned, as described in the following Supported Query Options section.

Notes

Le nombre d'entités retourné pour une demande peut être limité, si la requête dépasse le nombre maximum d'entités, l'intervalle de délai d'expiration ou dépasse une limite de partition.The number of entities returned for a single request may be limited, if the query exceeds the maximum number of entities, exceeds the timeout interval, or crosses a partition boundary. Pour plus d’informations, consultez délai de requête et pagination.For more information, see Query Timeout and Pagination.

Options de requête prise en chargeSupported Query Options

Le service de table prend en charge les options de requête suivantes, qui sont conformes à la spécification du protocole OData.The Table service supports the following query options, which conform to the OData Protocol Specification. Vous pouvez utiliser ces options pour limiter l'ensemble de tables, d'entités ou de propriétés d'entité retournées par une requête.You can use these options to limit the set of tables, entities, or entity properties returned by a query.

Option de requête systèmeSystem query option DescriptionDescription
$filter Retourne uniquement les tables ou les entités qui correspondent au filtre spécifié.Returns only tables or entities that satisfy the specified filter.

Notez qu'un maximum de 15 comparaisons discrètes sont autorisées au sein d'une chaîne $filter.Note that no more than 15 discrete comparisons are permitted within a $filter string.
$top Retourne uniquement les n tables ou entités supérieures de l'ensemble.Returns only the top n tables or entities from the set.
$select Retourne les propriétés souhaitées pour une entité de l'ensemble.Returns the desired properties of an entity from the set. Cette option de requête est prise en charge uniquement pour les demandes à partir de la version du 18/08/2011.This query option is only supported for requests using version 2011-08-18 or newer. Pour plus d’informations, consultez écriture de requêtes LINQ sur le service de table.For more information, see Writing LINQ Queries Against the Table Service.

Notes

Une demande qui retourne plus que le nombre maximal par défaut ou le nombre maximal spécifié de résultats retourne un jeton de continuation pour effectuer la pagination.A request that returns more than the default maximum or specified maximum number of results returns a continuation token for performing pagination. Lorsque vous effectuez les demandes suivantes qui incluent des jetons de continuation, veillez à transmettre l’URI d’origine à la demande.When making subsequent requests that include continuation tokens, be sure to pass the original URI on the request. Par exemple, si vous avez spécifié une $filter $select option de requête, ou dans $top le cadre de la demande d’origine, vous pouvez inclure cette option sur les demandes suivantes.For example, if you have specified a $filter, $select, or $top query option as part of the original request, you will want to include that option on subsequent requests. Dans le cas contraire, vos demandes suivantes peuvent retourner des résultats inattendus.Otherwise your subsequent requests may return unexpected results. Pour plus d’informations , consultez expiration et pagination des requêtes .See Query Timeout and Pagination for additional information.

Notez que l' $top option de requête dans le cas où les résultats sont paginés spécifie le nombre maximal de résultats par page, et non le nombre maximal de résultats dans l’ensemble de la réponse.Note that the $top query option in the case where results are paginated specifies the maximum number of results per page, not the maximum number of results in the whole response set.

Les options de requête supplémentaires définies par OData ne sont pas prises en charge par le service de Table.Additional query options defined by OData are not supported by the Table service.

Opérateurs de comparaison pris en chargeSupported Comparison Operators

Au sein d'une clause $filter, vous pouvez utiliser les opérateurs de comparaison pour spécifier des critères pour filtrer les résultats de requête.Within a $filter clause, you can use comparison operators to specify the criteria against which to filter the query results.

Pour tous les types de propriété, les opérateurs de comparaison suivants sont pris en charge :For all property types, the following comparison operators are supported:

OpérateurOperator Expression d'URIURI expression
Equal eq
GreaterThan gt
GreaterThanOrEqual ge
LessThan lt
LessThanOrEqual le
NotEqual ne

De plus, les opérateurs suivants sont pris en charge pour les propriétés booléennes :Additionally, the following operators are supported for Boolean properties:

OpérateurOperator Expression d'URIURI expression
And and
Not not
Or or

Pour plus d’informations sur la syntaxe de filtre, consultez la spécification du protocole OData.For more information about filter syntax, see the OData Protocol Specification.

Encodage des chaînes de requêteQuery String Encoding

Les caractères suivants doivent être encodés s'ils doivent être utilisés dans une chaîne de requête :The following characters must be encoded if they are to be used in a query string:

  • barre oblique (/)Forward slash (/)
  • point d'interrogation (?)Question mark (?)
  • deux-points (:)Colon (:)
  • Symbole arobase (@)'At' symbol (@)
  • Esperluette (&)Ampersand (&)
  • Signe égal (=)Equals sign (=)
  • Signe plus (+)Plus sign (+)
  • Virgule (,)Comma (,)
  • Signe dollar ($)Dollar sign ($)

Apostrophe (')Single quote (')

Les guillemets simples dans les chaînes de requête doivent être représentés sous la forme de deux guillemets simples consécutifs ( '' ).Single quotes in query strings must be represented as two consecutive single quotes (''). Par exemple, « heures » serait :For example, "o'clock" would be:

o''clock

Exemple d'expressions de requêteSample Query Expressions

Les exemples suivants décrivent comment construire l'URI de la demande pour des requêtes d'entité typiques à l'aide de la syntaxe REST.The following samples show how to construct the request URI for some typical entity queries using REST syntax. Les mêmes requêtes pourraient être écrites en syntaxe LINQ.The same queries could be written using LINQ syntax. Pour plus d’informations, consultez écriture de requêtes LINQ sur le service de table.For more information, see Writing LINQ Queries Against the Table Service.

Notez que les options $top et $filter peuvent être utilisées pour filtrer les noms de table, à l'aide de la syntaxe décrite pour filtrer les propriétés de type String.Note that both the $top and $filter options can be used to filter on table names as well, using the syntax demonstrated for filtering on properties of type String.

Retour des n entités supérieuresReturning the Top n Entities

Pour retourner les n entités supérieures pour une requête, indiquez l'option de requête $top.To return the top n entities for any query, specify the $top query option. L'exemple suivant retourne les 10 entités supérieures d'une table appelée Customers :The following example returns the top 10 entities from a table named Customers:

https://myaccount.table.core.windows.net/Customers()?$top=10  

Filtrage sur les propriétés PartitionKey et RowKeyFiltering on the PartitionKey and RowKey Properties

Dans la mesure où les propriétés PartitionKey et RowKey forment une clé primaire d'entité, vous pouvez utiliser une syntaxe spéciale pour identifier l'entité, comme suit :Because the PartitionKey and RowKey properties form an entity's primary key, you can use a special syntax to identify the entity, as follows:

https://myaccount.table.core.windows.net/Customers(PartitionKey='MyPartition',RowKey='MyRowKey1')  

Vous pouvez également spécifier ces propriétés dans le cadre de l’option $filter, comme indiqué dans la section suivante.Alternatively, you can specify these properties as part of the $filter option, as shown in the following section.

Notez que les noms de propriété de clé et les valeurs de constante respectent la casse.Note that the key property names and constant values are case-sensitive. Les propriétés PartitionKey et RowKey sont de type String.Both the PartitionKey and RowKey properties are of type String.

Construction des chaîne de filtreConstructing Filter Strings

Lorsque vous élaborez une chaîne de filtrage, n’oubliez pas les règles suivantes :When constructing a filter string, keep these rules in mind:

  • Utilisez les opérateurs logiques définis par la spécification du protocole OData pour comparer une propriété à une valeur.Use the logical operators defined by the OData Protocol Specification to compare a property to a value. Notez qu’il n’est pas possible de comparer une propriété à une valeur dynamique, car l’une des parties de l’expression doit avoir une valeur constante.Note that it is not possible to compare a property to a dynamic value; one side of the expression must be a constant.

  • Le nom de la propriété, l’opérateur et la valeur de constante doivent être séparés par des espaces codés URL.The property name, operator, and constant value must be separated by URL-encoded spaces. Un espace est codé URL sous la forme %20.A space is URL-encoded as %20.

  • Toutes les parties de la chaîne de filtrage respectent la casse.All parts of the filter string are case-sensitive.

  • Pour que le filtre retourne des résultats valides, la valeur constante doit être du même type de données que la propriété.The constant value must be of the same data type as the property in order for the filter to return valid results. Pour plus d’informations sur les types de propriétés pris en charge, consultez Présentation du modèle de données du service de Table.For more information about supported property types, see Understanding the Table Service Data Model.

Notes

Assurez-vous de vérifier qu'une propriété a été explicitement typée avant de considérer qu'elle a un type autre que chaîne.Be sure to check whether a property has been explicitly typed before assuming it is of a type other than string. Si une propriété a été explicitement typée, le type est indiqué dans la réponse quand l'entité est retournée.If a property has been explicitly typed, the type is indicated within the response when the entity is returned. Si la propriété n'a pas été explicitement typée, elle sera de type String, et le type ne sera pas indiqué dans la réponse quand l'entité est retournée.If the property has not been explicitly typed, it will be of type String, and the type will not be indicated within the response when the entity is returned.

Filtrage par propriété de chaîneFiltering on String Properties

Lors du filtrage sur les propriétés de chaîne, placez la constante de chaîne entre guillemets simples.When filtering on string properties, enclose the string constant in single quotes.

L'exemple suivant filtre sur les propriétés PartitionKey et RowKey ; d'autres propriétés non clé pourraient être ajoutées à la chaîne de requête.The following example filters on the PartitionKey and RowKey properties; additional non-key properties could also be added to the query string.

https://myaccount.table.core.windows.net/Customers()?$filter=PartitionKey%20eq%20'MyPartitionKey'%20and%20RowKey%20eq%20'MyRowKey1'  

L'exemple suivant filtre sur une propriété FirstName et LastName :The following example filters on a FirstName and LastName property:

https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20eq%20'Smith'%20and%20FirstName%20eq%20'John'  

Notez que le service de Table ne prend pas en charge les requêtes avec des caractères génériques.Note that the Table service does not support wildcard queries. Toutefois, vous pouvez lancer une correspondance de préfixe à l’aide d’opérateurs de comparaison sur le préfixe de votre choix.However, you can perform prefix matching by using comparison operators on the desired prefix. L'exemple suivant retourne des entités avec une propriété LastName qui commence par la lettre « A »:The following example returns entities with a LastName property beginning with the letter 'A':

https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20ge%20'A'%20and%20LastName%20lt%20'B'  

Filtrage par propriété numériqueFiltering on Numeric Properties

Pour filtrer sur un entier ou un nombre à virgule flottante, indiquez la valeur de constante dans l'URI sans guillemets.To filter on an integer or floating-point number, specify the constant value on the URI without quotes.

Cet exemple retourne toutes les entités avec une propriété Age dont la valeur est supérieure à 30 :This example returns all entities with an Age property whose value is greater than 30:

https://myaccount.table.core.windows.net/Customers()?$filter=Age%20gt%2030  

Cet exemple retourne toutes les entités avec une propriété AmountDue dont la valeur est inférieure ou égale à 100,25 :This example returns all entities with an AmountDue property whose value is less than or equal to 100.25:

https://myaccount.table.core.windows.net/Customers()?$filter=AmountDue%20le%20100.25%20  

Filtrage par propriété booléenneFiltering on Boolean Properties

Pour filtrer sur une valeur booléenne, indiquez true ou false sans guillemets.To filter on a Boolean value, specify true or false without quotes.

L'exemple suivant retourne toutes les entités pour lesquelles la propriété IsActive a la valeur true :The following example returns all entities where the IsActive property is set to true:

https://myaccount.table.core.windows.net/Customers()?$filter=IsActive%20eq%20true  

Filtrage par propriété DateTimeFiltering on DateTime Properties

Pour filtrer sur une valeur DateTime, indiquez le mot clé datetime dans l'URI, suivi par la constante date/heure entre guillemets simples.To filter on a DateTime value, specify the datetime keyword on the URI, followed by the date/time constant in single quotes. La constante date/heure doit être au format UTC combiné, comme décrit dans mise en forme des valeurs DateTime.The date/time constant must be in combined UTC format, as described in Formatting DateTime values.

L'exemple suivant retourne les entités pour lesquelles la propriété CustomerSince est égale au 10 juillet 2008 :The following example returns entities where the CustomerSince property is equal to July 10, 2008:

https://myaccount.table.core.windows.net/Customers()?$filter=CustomerSince%20eq%20datetime'2008-07-10T00:00:00Z'  

Filtrage sur les propriétés GUIDFiltering on GUID Properties

Pour filtrer sur une valeur GUID, spécifiez le mot clé guid dans l'URI, suivi par la constante de guid entre guillemets simples.To filter on a GUID value, specify the guid keyword on the URI, followed by the guid constant in single quotes.

L'exemple suivant retourne les entités pour lesquelles la propriété GuidValue est égale à :The following example returns entities where the GuidValue property is equal to :

https://myaccount.table.core.windows.net/Customers()?$filter=GuidValue%20eq%20guid'a455c695-df98-5678-aaaa-81d3367e5a34'  

Voir aussiSee Also

Concepts du service de table Table Service Concepts
Comprendre le modèle de données du service de table Understanding the Table Service Data Model
Adressage des ressources du service de table Addressing Table Service Resources
Délai de requête et pagination Query Timeout and Pagination
Écriture de requêtes LINQ sur le service de TableWriting LINQ Queries Against the Table Service