Query Entities

Artículo
06/27/2023

La operación Query Entities consulta las entidades de una tabla e incluye las opciones $filter y $select.

Solicitud

Para las solicitudes que usan la opción de consulta, debe usar la $select versión 2011-08-18 o posterior. Además, los encabezados DataServiceVersion y MaxDataServiceVersion deben establecerse en 2.0.

Para usar la proyección, debe realizar la solicitud con la versión 2013-08-15 o posterior. Los DataServiceVersion encabezados y MaxDataServiceVersion deben establecerse en 3.0. Para obtener más información, consulte Establecimiento de los encabezados de versión del servicio de datos de OData.

Puede construir la solicitud de la Query Entities siguiente manera. Se recomienda HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento y reemplace mytable por el nombre de la tabla.

Método	URI de solicitud	Versión de 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

La dirección del conjunto de entidades que se va a consultar puede adoptar varias formas en el URI de solicitud. Para obtener más información, vea Consulta de tablas y entidades.

URI del servicio de almacenamiento emulado

Cuando realice una solicitud en el servicio de almacenamiento emulado, especifique el nombre de host del emulador y el puerto de Table Service como 127.0.0.1:10002. Siga esa información con el nombre de la cuenta de almacenamiento emulada.

Método	URI de solicitud	Versión de 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

Table service en el emulador de almacenamiento difiere de Azure Table Storage de varias maneras. Para más información, consulte Diferencias entre el emulador de almacenamiento y los servicios de Azure Storage.

Parámetros del identificador URI

La Query Entities operación admite las opciones de consulta que define la especificación del protocolo OData .

Encabezados de solicitud

En la tabla siguiente se describen los encabezados de solicitud obligatorios y opcionales:

Encabezado de solicitud	Descripción
`Authorization`	Necesario. Especifica el esquema de autorización, el nombre de cuenta y la firma. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
`Date` o `x-ms-date`	Necesario. Especifica la hora universal coordinada (UTC) de la solicitud. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
`x-ms-version`	Opcional. Especifica la versión de la operación que se utiliza para esta solicitud. Para obtener más información, vea Versiones de los servicios de Azure Storage.
`Accept`	Opcional. Especifica el tipo de contenido aceptado de la carga de respuesta. Los valores posibles son: - `application/atom+xml` (versiones anteriores solo a 2015-12-11) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` Para más información, consulte Formato de carga para las operaciones de Table Storage.
`x-ms-client-request-id`	Opcional. Proporciona un valor opaco generado por el cliente con un límite de caracteres de 1 kibibyte (KiB) que se registra en los registros cuando se configura el registro. Se recomienda encarecidamente usar este encabezado para correlacionar las actividades del lado cliente con las solicitudes que recibe el servidor.

Cuerpo de la solicitud

Ninguno.

Solicitud de ejemplo

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 respuesta incluye un código de estado HTTP, un conjunto de encabezados de respuesta y un cuerpo de respuesta.

status code

Una operación correcta devuelve el código de estado 200 Correcto.

Para obtener información sobre los códigos de estado, consulte Códigos de error y estado y Códigos de error de Table Storage.

Encabezados de respuesta

La respuesta para esta operación incluye los encabezados siguientes. La respuesta también puede incluir encabezados HTTP estándar adicionales. Todos los encabezados estándar se ajustan a la especificación del protocolo HTTP/1.1.

Encabezado de respuesta	Descripción
`x-ms-continuation-NextPartitionKey` `x-ms-continuation-NextRowKey`	Indica que: - El número de entidades que se van a devolver supera los 1000. - Se supera el intervalo de tiempo de espera del servidor. - Se alcanza un límite de servidor, si la consulta devuelve datos que se distribuyen entre varios servidores. Para obtener más información sobre el uso de los tokens de continuación, consulte Tiempo de espera y paginación de consultas.
`x-ms-request-id`	Identifica de forma única la solicitud que se realizó. Puede usarlo para solucionar problemas de la solicitud. Para más información, consulte Solución de problemas de operaciones de API.
`x-ms-version`	Indica la versión de Table Storage que se usó para ejecutar la solicitud. Este encabezado se devuelve para las solicitudes realizadas en la versión 2009-09-19 y versiones posteriores.
`Date`	Valor de fecha y hora UTC que indica la hora en la que el servicio envió la respuesta.
`Content-Type`	Indica el tipo de contenido de la carga. El valor de este encabezado depende del valor del encabezado de solicitud `Accept`. Los valores posibles son: - `application/atom+xml` (versiones anteriores solo a 2015-12-11) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` Para obtener más información sobre los tipos de contenido válidos, consulte Formato de carga para las operaciones de Table Storage.
`x-ms-client-request-id`	Se puede usar para solucionar problemas de solicitudes y respuestas correspondientes. El valor de este encabezado es igual al valor del `x-ms-client-request-id` encabezado, si está presente en la solicitud y el valor es como máximo de 1024 caracteres ASCII visibles. Si el `x-ms-client-request-id` encabezado no está presente en la solicitud, este encabezado no estará presente en la respuesta.

Respuesta de muestra

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

La Query Entities operación devuelve la lista de entidades de una tabla como un conjunto de entidades de OData. La lista de entidades está en un formato JSON o en una fuente Atom, en función del Accept encabezado de la solicitud.

Nota

Se recomienda JSON como formato de carga. Es el único formato admitido para la versión 2015-12-11 y posteriores.

JSON (versión 2013-08-15 y posteriores)

Este es un URI de solicitud de ejemplo para una Query Entities operación en una tabla de clientes:

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

Esta es la carga de respuesta en JSON sin metadatos:

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

Esta es la carga de respuesta en JSON con metadatos mínimos:

{  
   "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"  
      }  
   ]  
}

Esta es la carga de respuesta en JSON con metadatos completos:

{  
   "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"  
      }  
   ]  
}

Fuente Atom (versiones anteriores al 2015-12-11)

Este es un URI de solicitud de ejemplo para una Query Entities operación en una tabla de clientes:

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

Esta es una respuesta atom de ejemplo para la Query Entities operación:

<?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>

Authorization

Esta operación la puede realizar el propietario de la cuenta y cualquiera que tenga una firma de acceso compartido con permiso para realizar esta operación.

Comentarios

Una consulta en Table Storage puede devolver un máximo de 1000 entidades a la vez y puede ejecutarse durante un máximo de cinco segundos. La respuesta incluye encabezados personalizados que contienen un conjunto de tokens de continuación en cualquiera de los casos siguientes:

El conjunto de resultados contiene más de 1000 entidades.
La consulta no finalizó en cinco segundos.
La consulta supera el límite de la partición.

Puede usar los tokens de continuación para construir una solicitud posterior para la página siguiente de datos. Para obtener más información sobre los tokens de continuación, consulte Tiempo de espera de consulta y paginación.

Nota

Cuando realice solicitudes posteriores que incluyan tokens de continuación, asegúrese de pasar el URI original en la solicitud. Por ejemplo, si ha especificado una $filteropción de consulta , $selecto $top como parte de la solicitud original, incluya esa opción en las solicitudes posteriores. De lo contrario, las solicitudes posteriores podrían devolver resultados inesperados.

La $top opción de consulta en este caso especifica el número máximo de resultados por página. No especifica el número máximo de resultados en todo el conjunto de respuestas.

Para obtener más información, vea Consulta de tablas y entidades.

Para las solicitudes de proyección que usan la $select opción de consulta, la versión debe ser 2011-08-18 o posterior. El número máximo de propiedades devueltas es 255. El cuerpo de la respuesta incluye todas las propiedades proyectadas, incluso si las propiedades no forman parte de la entidad devuelta.

Por ejemplo, si la solicitud incluye una propiedad que la entidad proyectada no contiene, la propiedad que falta se marca con un atributo NULL. El cuerpo de la respuesta de ejemplo anterior incluye la Address propiedad , que no forma parte de la entidad proyectada. Por lo tanto, el valor de la propiedad es NULL: <d:Address m:null="true" />.

El tiempo total asignado a la solicitud de programación y procesamiento de la consulta es de 30 segundos. Ese total incluye los cinco segundos para la ejecución de consultas.

Tenga en cuenta que el lado derecho de una expresión de consulta debe ser una constante. No se puede hacer referencia a una propiedad en el lado derecho de la expresión. Para obtener más información sobre cómo construir expresiones de consulta, consulte Tablas y entidades de consulta.

Una expresión de consulta no puede contener null valores. Los caracteres siguientes deben codificarse si los usa en una cadena de consulta:

Barra diagonal (/)
Signo de interrogación (?)
Dos puntos (:)
Arroba (@)
Símbolo de y comercial (&)
Signo igual (=)
Signo más (+)
Coma (,)
Signo de dólar ($)

Cualquier aplicación que pueda autorizar y enviar una solicitud HTTP GET puede consultar entidades en una tabla.

Para obtener más información sobre las operaciones de consulta admitidas en Table Storage a través de LINQ, consulte Operadores de consulta compatibles con Table Storage y Escritura de consultas LINQ en Table Storage.

Consulte también

Códigos de error de Table Storage
Autorización de solicitudes a Azure Storage
Estado y códigos de error
Direccionamiento de los recursos de Table Storage
Consulta de tablas y entidades
Establecimiento de los encabezados de versión del servicio de datos de OData
Insert Entity
Update Entity
Delete Entity