Query Entities

Article
06/27/2023

L'opération Query Entities interroge les entités dans une table et comprend les options $filter et $select.

Requête

Pour les demandes qui utilisent l’option $select de requête, vous devez utiliser la version 2011-08-18 ou ultérieure. En outre, les en-têtes DataServiceVersion et MaxDataServiceVersion doivent avoir la valeur 2.0.

Pour utiliser la projection, vous devez effectuer la demande à l’aide de la version 2013-08-15 ou ultérieure. Les DataServiceVersion en-têtes et MaxDataServiceVersion doivent être définis sur 3.0. Pour plus d’informations, consultez Définir les en-têtes de version du service de données OData.

Vous pouvez construire la Query Entities requête comme suit. Nous recommandons HTTPS. Remplacez myaccount par le nom de votre compte de stockage et remplacez mytable par le nom de votre table.

Méthode	URI de demande	Version HTTP
`GET`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>` `https://myaccount.table.core.windows.net/mytable()?$filter=<query-expression>&$select=<comma-separated-property-names>`	HTTP/1.1

L’adresse du jeu d’entités à interroger peut prendre différentes formes sur l’URI de demande. Pour plus d’informations, consultez Interroger des tables et des entités.

URI de service de stockage émulé

Lorsque vous effectuez une requête auprès du service de stockage émulé, spécifiez le nom d’hôte de l’émulateur et le port du service de table comme 127.0.0.1:10002. Suivez ces informations avec le nom du compte de stockage émulé.

Méthode	URI de demande	Version HTTP
`GET`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>` `http://127.0.0.1:10002/devstoreaccount1/mytable()?$filter=<query-expression>?$select=<comma-separated-property-names>`	HTTP/1.1

Le service Table dans l’émulateur de stockage diffère de Stockage Table Azure de plusieurs manières. Pour plus d’informations, consultez Différences entre l’émulateur de stockage et les services de stockage Azure.

Paramètres URI

L’opération Query Entities prend en charge les options de requête que la spécification du protocole OData définit.

En-têtes de requête

Le tableau suivant décrit les en-têtes de requête obligatoires et facultatifs :

En-tête de requête	Description
`Authorization`	Obligatoire. Spécifie le schéma d’autorisation, le nom du compte et la signature. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure.
`Date` ou `x-ms-date`	Obligatoire. Spécifie la date/heure en temps universel coordonné (UTC) pour la requête. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure.
`x-ms-version`	facultatif. Spécifie la version de l'opération à utiliser pour cette demande. Pour plus d'informations, consultez la page Contrôle de version pour les services de Stockage Microsoft Azure.
`Accept`	facultatif. Spécifie le type de contenu accepté de la charge utile de réponse. Les valeurs possibles sont les suivantes : - `application/atom+xml` (versions antérieures au 11/12/2015 uniquement) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` Pour plus d’informations, consultez Format de charge utile pour les opérations de stockage table.
`x-ms-client-request-id`	facultatif. Fournit une valeur opaque générée par le client avec une limite de caractères de 1 kibioctet (Kio) enregistrée dans les journaux lors de la configuration de la journalisation. Nous vous recommandons vivement d’utiliser cet en-tête pour mettre en corrélation les activités côté client avec les demandes reçues par le serveur.

Corps de la demande

Aucun.

Exemple de requête

Request Syntax:  
GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-12-11  
x-ms-date: Mon, 27 Jun 2016 15:25:14 GMT  
Authorization: SharedKeyLite myaccount:<some key>  
Accept: application/json;odata=nometadata  
Accept-Charset: UTF-8  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx

response

La réponse inclut un code d'état HTTP, un ensemble d'en-têtes de réponse et un corps de réponse.

Code d’état

Une opération réussie envoie le code d'état 200 (OK).

Pour plus d’informations sur les codes status, consultez Codes d’état et d’erreur et Codes d’erreur stockage table.

En-têtes de réponse

La réponse de l'opération inclut les en-têtes suivants. La réponse peut également inclure des en-têtes HTTP standard supplémentaires. Tous les en-têtes standard sont conformes à la spécification du protocole HTTP/1.1.

En-tête de réponse	Description
`x-ms-continuation-NextPartitionKey` `x-ms-continuation-NextRowKey`	Indique que : - Le nombre d’entités à retourner dépasse 1 000. - L’intervalle de délai d’attente du serveur est dépassé. - Une limite de serveur est atteinte si la requête retourne des données réparties sur plusieurs serveurs. Pour plus d’informations sur l’utilisation des jetons de continuation, consultez Délai d’expiration et pagination des requêtes.
`x-ms-request-id`	Identifie de manière unique la demande qui a été effectuée. Vous pouvez l’utiliser pour résoudre les problèmes liés à la demande. Pour plus d’informations, consultez Résoudre les problèmes liés aux opérations d’API.
`x-ms-version`	Indique la version de Stockage Table qui a été utilisée pour exécuter la demande. Cet en-tête est renvoyé pour les demandes effectuées avec la version 2009-09-19 ou une version ultérieure.
`Date`	Valeur de date/heure UTC qui indique l’heure à laquelle le service a envoyé la réponse.
`Content-Type`	Indique le type de contenu de la charge utile. La valeur de cet en-tête dépend de la valeur de l'en-tête de demande `Accept`. Les valeurs possibles sont les suivantes : - `application/atom+xml` (versions antérieures au 11/12/2015 uniquement) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` Pour plus d’informations sur les types de contenu valides, consultez Format de charge utile pour les opérations de stockage table.
`x-ms-client-request-id`	Peut être utilisé pour résoudre les demandes et les réponses correspondantes. La valeur de cet en-tête est égale à la valeur de l’en-tête `x-ms-client-request-id` , s’il est présent dans la requête et que la valeur est au maximum de 1 024 caractères ASCII visibles. Si l’en-tête `x-ms-client-request-id` n’est pas présent dans la demande, cet en-tête ne sera pas présent dans la réponse.

Exemple de réponse

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
Content-Type: application/json  
x-ms-request-id: 87f178c0-44fe-4123-a4c1-96c8fa6d9654  
Date: Mon, 27 Jun 2016 15:25:14 GMT  
x-ms-version: 2015-12-11  
Connection: close

Response body

L’opération Query Entities retourne la liste des entités d’une table sous la forme d’un ensemble d’entités OData. La liste des entités est au format JSON ou dans un flux Atom, en fonction de l’en-tête Accept de la requête.

Notes

Nous recommandons JSON comme format de charge utile. Il s’agit du seul format pris en charge pour les versions 2015-12-11 et ultérieures.

JSON (version 2013-08-15 et ultérieure)

Voici un exemple d’URI de requête pour une Query Entities opération sur une table de clients :

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

Voici la charge utile de réponse dans JSON sans métadonnées :

{  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Voici la charge utile de réponse dans JSON avec des métadonnées minimales :

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers",  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Voici la charge utile de réponse dans JSON avec des métadonnées complètes :

{  
   "odata.metadata":" https://myaccount.table.core.windows.net/metadata#Customers",  
   "value":[  
      {  
         "odata.type":"myaccount.Customers",  
         "odata.id":"https://myaccount.table.core.windows.net/Customers(PartitionKey=Customer',RowKey='Name')",  
         "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
         "odata.editLink":"Customers(PartitionKey=Customer',RowKey='Name')",  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp@odata.type":"Edm.DateTime",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Flux Atom (versions antérieures au 11-12-2015)

Voici un exemple d’URI de requête pour une Query Entities opération sur une table de clients :

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

Voici un exemple de réponse Atom pour l’opération Query Entities :

<?xml version="1.0" encoding="UTF-8"?>  
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xml:base="https://myaccount.table.core.windows.net">  
   <id>https://myaccount.table.core.windows.net/Customers</id>  
   <title type="text">Customers</title>  
   <updated>2013-08-22T00:50:32Z</updated>  
   <link rel="self" title="Customers" href="Customers" />  
   <entry m:etag="W/"0x5B168C7B6E589D2"">  
      <id>https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer',RowKey='Name')</id>  
      <category term="myaccount.Customers" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
      <link rel="edit" title="Customers" href="Customers(PartitionKey='Customer',RowKey='Name')" />  
      <title />  
      <updated>2013-08-22T00:50:32Z</updated>  
      <author>  
         <name />  
      </author>  
      <content type="application/xml">  
         <m:properties>  
            <d:PartitionKey>Customer</d:PartitionKey>  
            <d:RowKey>Name</d:RowKey>  
            <d:Timestamp m:type="Edm.DateTime">2013-08-22T00:20:16.3134645Z</d:Timestamp>  
            <d:CustomerSince m:type="Edm.DateTime">2008-10-01T15:25:05.2852025Z</d:CustomerSince>  
         </m:properties>  
      </content>  
   </entry>  
</feed>

Autorisation

Cette opération peut être exécutée par le propriétaire du compte et par toute personne qui dispose d'une signature d'accès partagé qui a l'autorisation d'exécuter cette opération.

Remarques

Une requête sur le stockage table peut retourner un maximum de 1 000 entités à la fois et peut s’exécuter pendant un maximum de cinq secondes. La réponse inclut des en-têtes personnalisés qui contiennent un ensemble de jetons de continuation dans l’un des cas suivants :

Le jeu de résultats contient plus de 1000 entités.
La requête ne s’est pas terminée dans les cinq secondes.
La requête franchit les limites de la partition.

Vous pouvez utiliser les jetons de continuation pour construire une requête suivante pour la page de données suivante. Pour plus d’informations sur les jetons de continuation, consultez Délai d’expiration et pagination des requêtes.

Notes

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, incluez cette option sur les requêtes suivantes. Dans le cas contraire, vos demandes suivantes peuvent retourner des résultats inattendus.

Dans $top ce cas, l’option de requête spécifie le nombre maximal de résultats par page. Il ne spécifie pas le nombre maximal de résultats dans l’ensemble du jeu de réponses.

Pour plus d’informations, consultez Interroger des tables et des entités.

Pour les demandes de projection qui utilisent l’option $select de requête, la version doit être 2011-08-18 ou ultérieure. Le nombre maximal de propriétés retournées est de 255. Le corps de la réponse inclut toutes les propriétés projetées, même si les propriétés ne font pas partie de l’entité retournée.

Par exemple, si la demande inclut une propriété que l'entité projetée ne contient pas, la propriété manquante est marquée avec un attribut null. L’exemple de corps de réponse précédent inclut la Address propriété , qui ne fait pas partie de l’entité projetée. La valeur de la propriété est donc null : <d:Address m:null="true" />.

Le temps total alloué à la demande pour la planification et le traitement de la requête est de 30 secondes. Ce total inclut les cinq secondes pour l’exécution de la requête.

Notez que le côté droit d’une expression de requête doit être une constante. Vous ne pouvez pas référencer une propriété sur le côté droit de l’expression. Pour plus d’informations sur la construction d’expressions de requête, consultez Tables et entités de requête.

Une expression de requête ne peut pas contenir de null valeurs. Les caractères suivants doivent être encodés si vous les utilisez dans une chaîne de requête :

barre oblique (/)
point d'interrogation (?)
deux-points (:)
Le signe « arrobas » (@)
Esperluette (&)
Le signe égal (=)
Signe plus (+)
Virgule (,)
Signe dollar ($)

Toute application qui peut autoriser et envoyer une requête HTTP GET peut interroger des entités dans une table.

Pour plus d’informations sur les opérations de requête prises en charge sur le stockage Table via LINQ, consultez Opérateurs de requête pris en charge pour le stockage table et Écrire des requêtes LINQ sur le stockage table.

Voir aussi

Codes d’erreur stockage table
Autoriser les demandes dans le Stockage Azure
Codes d’état et d’erreur
Adressage des ressources de stockage table
Interroger des tables et des entités
Définir les en-têtes de version du service de données OData
Insert Entity
Update Entity
Delete Entity