Interrogation de tables et d’entités

  • Article

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. Les sections suivantes décrivent les options de requête et des scénarios courants.

Syntaxe de requête de base

Pour retourner toutes les tables d’un compte de stockage donné, effectuez une GET opération sur la ressource Tables, comme décrit dans l’opération Interroger les tables . L'URI de base pour l'adressage de la ressource Tables est le suivant :

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

Pour retourner une unique table nommée, indiquez cette table comme suit :

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 :

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

Les résultats de la requête sont triés par PartitionKey, puis par RowKey. Un ordre de tri des résultats différent n'est actuellement pas pris en charge.

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.

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. Pour plus d’informations, consultez Délai d’expiration et pagination des requêtes.

Options de requête prise en charge

Le service Table prend en charge les options de requête suivantes, qui sont conformes à la spécification du protocole OData. 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.

Option de requête système Description
$filter Retourne uniquement les tables ou les entités qui correspondent au filtre spécifié.

Notez qu'un maximum de 15 comparaisons discrètes sont autorisées au sein d'une chaîne $filter.
$top Retourne uniquement les n tables ou entités supérieures de l'ensemble.
$select Retourne les propriétés souhaitées pour une entité de l'ensemble. Cette option de requête est prise en charge uniquement pour les demandes à partir de la version du 18/08/2011. Pour plus d’informations, consultez Écriture de requêtes LINQ sur le service de table.

Notes

Une requête qui retourne plus que le nombre maximal de résultats par défaut ou le nombre maximal spécifié de résultats retourne un jeton de continuation pour l’exécution de la pagination. Lorsque vous effectuez des requêtes suivantes qui incluent des jetons de continuation, veillez à passer l’URI d’origine sur la demande. Par exemple, si vous avez spécifié une $filteroption de requête , $selectou $top dans le cadre de la demande d’origine, vous devez inclure cette option sur les demandes suivantes. Sinon, vos demandes ultérieures peuvent retourner des résultats inattendus. Pour plus d’informations, consultez Délai d’expiration et pagination des requêtes.

Notez que l’option $top 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 du jeu de réponses.

Les options de requête supplémentaires définies par OData ne sont pas prises en charge par le service de Table.

Opérateurs de comparaison pris en charge

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.

Pour tous les types de propriété, les opérateurs de comparaison suivants sont pris en charge :

Opérateur Expression d'URI
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 :

Opérateur Expression d'URI
And and
Not not
Or or

Pour plus d’informations sur la syntaxe de filtre, consultez spécification du protocole OData.

Encodage des chaînes de requête

Les caractères suivants doivent être encodés s'ils doivent être utilisés dans une chaîne de requête :

  • barre oblique (/)
  • point d'interrogation (?)
  • deux-points (:)
  • Symbole arobase (@)
  • Esperluette (&)
  • Signe égal (=)
  • Signe plus (+)
  • Virgule (,)
  • Signe dollar ($)

Apostrophe (')

Les guillemets simples dans les chaînes de requête doivent être représentés sous la forme de deux guillemets simples consécutifs (''). Par exemple, « o’clock » serait :

o''clock

Exemple d'expressions de requête

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. Les mêmes requêtes pourraient être écrites en syntaxe LINQ. Pour plus d’informations, consultez Écriture de requêtes LINQ sur le service de table.

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.

Retour des n entités supérieures

Pour retourner les n entités supérieures pour une requête, indiquez l'option de requête $top. L'exemple suivant retourne les 10 entités supérieures d'une table appelée Customers :

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

Filtrage sur les propriétés PartitionKey et RowKey

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 :

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.

Notez que les noms de propriété de clé et les valeurs de constante respectent la casse. Les propriétés PartitionKey et RowKey sont de type String.

Construction des chaîne de filtre

Lorsque vous élaborez une chaîne de filtrage, n’oubliez pas les règles suivantes :

  • Utilisez les opérateurs logiques définis par la spécification du protocole OData pour comparer une propriété à une valeur. 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.

  • 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. Un espace est codé URL sous la forme %20.

  • Toutes les parties de la chaîne de filtrage respectent la casse.

  • 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é. 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.

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. Si une propriété a été explicitement typée, le type est indiqué dans la réponse quand l'entité est retournée. 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.

Filtrage par propriété de chaîne

Lors du filtrage sur les propriétés de chaîne, placez la constante de chaîne entre guillemets simples.

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.

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 :

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. Toutefois, vous pouvez lancer une correspondance de préfixe à l’aide d’opérateurs de comparaison sur le préfixe de votre choix. L'exemple suivant retourne des entités avec une propriété LastName qui commence par la lettre « A »:

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

Filtrage par propriété numérique

Pour filtrer sur un entier ou un nombre à virgule flottante, indiquez la valeur de constante dans l'URI sans guillemets.

Cet exemple retourne toutes les entités avec une propriété Age dont la valeur est supérieure à 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 :

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

Filtrage par propriété booléenne

Pour filtrer sur une valeur booléenne, indiquez true ou false sans guillemets.

L'exemple suivant retourne toutes les entités pour lesquelles la propriété IsActive a la valeur true :

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

Filtrage par propriété DateTime

Pour filtrer sur une valeur DateTime, indiquez le mot clé datetime dans l'URI, suivi par la constante date/heure entre guillemets simples. La constante date/heure doit être au format UTC combiné, comme décrit dans Mise en forme des valeurs DateTime.

L'exemple suivant retourne les entités pour lesquelles la propriété CustomerSince est égale au 10 juillet 2008 :

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

Filtrage sur les propriétés GUID

Pour filtrer sur une valeur GUID, spécifiez le mot clé guid dans l'URI, suivi par la constante de guid entre guillemets simples.

L'exemple suivant retourne les entités pour lesquelles la propriété GuidValue est égale à :

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

Voir aussi

Concepts du service de Table
Présentation du modèle de données du service de table
Ressources du service table d’adressage
Délai d’expiration et pagination des requêtes
Écriture de requêtes LINQ sur le service de Table