Consulta de recursos de Azure Cosmos DB mediante la API REST

Azure Cosmos DB es una base de datos multimodelo distribuida globalmente que admite varias API. En este artículo se describe cómo usar REST para consultar recursos mediante la API de SQL.

¿Cómo se puede consultar un recurso con REST?

Para realizar una consulta SQL en un recurso, haga lo siguiente:

• Ejecute un POST método en una ruta de acceso de recurso mediante JSON con la query propiedad establecida en la cadena de consulta SQL y la propiedad "parameters" establecida en la matriz de valores de parámetro opcionales.
• Establezca el encabezado x-ms-documentdb-isquery en True.
• Establezca el encabezado Content-Type en application/query+json.

Para obtener un ejemplo en el que se muestra cómo realizar una consulta SQL en un recurso mediante .NET, consulte REST del ejemplo de .NET.

Ejemplo

A continuación se muestra un ejemplo de operación de consulta de REST en los recursos del documento. En este ejemplo, nos gustaría buscar todos los documentos que tienen a "Don" como autor.

POST https://contosomarketing.documents.azure.com/dbs/XP0mAA==/colls/XP0mAJ3H-AA=/docs HTTP/1.1  
x-ms-documentdb-isquery: True  
x-ms-date: Mon, 18 Apr 2015 13:05:49 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dkOU%2bBn2vkvIlHypfE8AA5fulpn8zKjLwdrxBqyg0YGQ%3d  
x-ms-version: 2015-12-16  
x-ms-query-enable-crosspartition: True  
Accept: application/json  
Content-Type: application/query+json  
Host: contosomarketing.documents.azure.com  
Content-Length: 50  

{  
    "query": "SELECT * FROM root WHERE (root.Author.id = 'Don')",  
    "parameters": []  
}  
  

Detalles de la solicitud

Método	URI de solicitud
POST	Requerido. El tipo de autenticación y el token de firma. Solo se permite el token de clave maestra para esta operación. Para más información, consulte Access Control en recursos de Cosmos DB.

Encabezados de solicitud

La tabla siguiente contiene los encabezados comunes utilizados para realizar operaciones de consulta.

Encabezado estándar	Descripción
Autorización	Requerido. El tipo de autenticación y el token de firma. Solo se permite el token de clave maestra para esta operación. Para más información, consulte Access Control en recursos de Cosmos DB.
Content-Type	Requerido. Debe establecerse en application/query+json.
Aceptación	Opcional. En este momento, Cosmos DB siempre devuelve la carga de respuesta en formato JSON estándar. El cliente debe ser capaz de aceptar el cuerpo de respuesta en el formato JSON estándar.
User-Agent	Opcional. El agente de usuario que realiza la solicitud. El formato recomendado es {nombre del agente de usuario}/{versión}. Por ejemplo, el SDK de .NET de la API de SQL establece la cadena de User-Agent en Microsoft.Document.Client/1.0.0.0.

Encabezado personalizado	Descripción
x-ms-date	Requerido. La fecha de la solicitud, tal como se especifica en RFC 1123. El formato de fecha se expresa en hora universal coordinada (UTC), por ejemplo. viernes, 8 de agosto de 2015 03:52:31 GMT.
x-ms-documentdb-isquery	Requerido. Esta propiedad debe establecerse en true.
x-ms-max-item-count	Opcional. Para desplazarse a través de un conjunto de resultados, establezca este encabezado en el número máximo de elementos que se devuelven en una sola página.
x-ms-continuation	Opcional. Para navegar a la siguiente página de elementos, establezca este encabezado en el token de continuación de la página siguiente.
x-ms-version	Opcional. La versión del servicio REST de Cosmos DB. Cuando no se proporciona el encabezado, se utiliza la última versión. Para más información, consulte Referencia de la API REST de Azure Cosmos DB.
x-ms-documentdb-query-enable-scan	Opcional. Use un recorrido de índice para procesar la consulta si la ruta de acceso al índice correcto del tipo no está disponible.
x-ms-session-token	Opcional. El token de sesión para la solicitud. Se usa para coherencia de la sesión.
x-ms-partition-key	Opcional. Si se especifica, la consulta solo se ejecuta en documentos que coinciden con el valor de clave de partición en el encabezado.
x-ms-documentdb-query-enablecrosspartition	Opcional. Debe establecerse en true para las consultas que no filtran por una sola clave de partición. Las consultas que filtran por un solo valor de clave de partición se ejecutarán en una sola partición, incluso si se establece en true.
x-ms-documentdb-populatequerymetrics	Opcional. Debe establecerse True en para devolver métricas de consulta.

Cuerpo de la solicitud

El cuerpo de la solicitud debe ser un documento JSON válido que contenga los parámetros y la consulta SQL. Si la entrada tiene una sintaxis SQL no válida o incorrecta, la operación generará un error 400 Solicitud incorrecta.

También obtendrá una solicitud incorrecta 400 si la puerta de enlace no puede atender una consulta.

Propiedad	Descripción
Query	Requerido. La cadena de consulta SQL para la consulta. Para más información, consulte Referencia de sintaxis sql de Azure Cosmos DB.
parámetros	Requerido. Una matriz JSON de parámetros especificada como pares nombre-valor. La matriz de parámetros puede contener de cero a muchos parámetros. Cada parámetro debe tener los siguientes valores:name: el nombre del parámetro. Los nombres de parámetro deben ser literales de cadena válidos y comenzar por "@". value: el valor del parámetro . Puede ser cualquier valor JSON válido (cadena, número, objeto, matriz, booleano o nulo).

Solicitud de ejemplo

En el ejemplo siguiente se realiza una solicitud SQL parametrizada con un parámetro de cadena para @author.

POST https://contosomarketing.documents.azure.com/dbs/XP0mAA==/colls/XP0mAJ3H-AA=/docs HTTP/1.1  
x-ms-documentdb-isquery: True  
x-ms-date: Mon, 18 Apr 2015 13:05:49 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dkOU%2bBn2vkvIlHypfE8AA5fulpn8zKjLwdrxBqyg0YGQ%3d  
x-ms-version: 2015-04-08  
Accept: application/json  
Content-Type: application/query+json  
Host: contosomarketing.documents.azure.com  
Content-Length: 50  
  
{  
    "query": "SELECT * FROM root WHERE (root.Author.id = @author)",  
    "parameters":   
    [  
        { "name": "@author", "value": "Leo Tolstoy"}  
    ]  
}  

Para más información sobre las consultas SQL, consulte Consultas SQL para Azure Cosmos DB.

Detalles de la respuesta

Los siguientes son códigos de estado comunes devueltos por esta operación. Para obtener información sobre los códigos de estado de error, consulte Códigos de estado HTTP para Azure Cosmos DB.

Código	Descripción
200 Ok	La operación se realizó correctamente.
400 - Solicitud incorrecta	La sintaxis de la instrucción SQL es incorrecta.
401 No autorizado	El encabezado Authorization o x-ms-date no se han establecido. 401 también se devuelve cuando el encabezado Authorization está configurado como un token de autorización no válido.
(403) Prohibido	El token de autorización expiró.
404 No encontrado	La colección ya no es un recurso. Por ejemplo, el recurso puede haberse eliminado.

Encabezados de respuesta

Esta operación devuelve los siguientes encabezados comunes. Puede que se devuelvan más encabezados estándar y comunes.

Encabezado estándar	Descripción
Content-Type	El Content-Type es application/json. Cosmos DB siempre devuelve el cuerpo de la respuesta en formato JSON estándar.
Date	La fecha y la hora de la operación de respuesta. Este formato de fecha hora se ajusta al formato de hora y fecha de RFC 1123 expresado en hora universal coordinada.

Encabezado personalizado	Descripción
x-ms-item-count	El número de elementos devueltos por la operación.
x-ms-continuation	Es una cadena opaca devuelta cuando la consulta tiene potencialmente más elementos que se van a recuperar. x-ms-continuation se puede incluir en solicitudes subsiguientes como un encabezado de solicitud para reanudar la ejecución de la consulta.
x-ms-request-charge	Es el número de unidades de solicitud (RU) consumidas por la operación. Para más información sobre las unidades de solicitud, consulte Unidades de solicitud en Azure Cosmos DB.
x-ms-activity-id	Es un identificador único para la operación. Se puede usar para realizar el seguimiento de la ejecución de solicitudes de Cosmos DB.
x-ms-session-token	El token de sesión que se usará para solicitudes subsiguientes. Se usa para coherencia de la sesión.

Cuerpo de la respuesta

El cuerpo de respuesta para la operación de consulta consta del _rid del recurso principal del recurso que se consulta y la matriz de recursos que contiene las propiedades del recurso para la proyección y la selección. Según el ejemplo, si se realizó una consulta en la ruta docs de la recopilación con un _rid de XP0mAJ3H-AA=,, la respuesta sería la siguiente:

{"_rid":" XP0mAJ3H-AA=","Documents":   [  ….  ….   ],"_count":10}  

Propiedad	Descripción
_rid	Identificador de recurso de la colección usada en la consulta.
_Contar	Número de elementos devueltos.
Matriz de recursos	La matriz que contiene los resultados de consulta.

Creación del cuerpo de solicitud de consulta

La solicitud de consulta debe ser un documento JSON válido que contiene una propiedad query que contiene una cadena de consulta SQL válida y una propiedad parameters que contiene una matriz de parámetros opcionales. Cada parámetro debe tener una propiedad name y value de parámetros que se especifican dentro de la consulta. Los nombres de parámetro deben comenzar con el carácter "@". Los valores pueden ser cualquier valor JSON válido: cadenas, enteros, booleanos y nulos.

Es válido especificar solo un subconjunto de parámetros especificados en el texto de la consulta . Las expresiones que hacen referencia a estos parámetros no especificados evaluarán a undefined. También es válido para especificar parámetros adicionales que no se usan dentro del texto query.

A continuación aparecen algunos ejemplos de solicitudes de consulta válida. Por ejemplo, la consulta siguiente tiene un único parámetro @id.

{  
    "query": "select * from docs d where d.id = @id",   
    "parameters": [   
        {"@id": "newdoc"}   
     ]  
}  
  

El siguiente ejemplo tiene dos parámetros, uno con un valor de cadena y otro con un valor entero.

{  
    "query": "select * from docs d where d.id = @id and d.prop = @prop",   
    "parameters": [   
        {"@id": "newdoc"},  
        {"@prop": 5}   
     ]  
}  

El siguiente ejemplo usa parámetros dentro de la cláusula SELECT, así como una propiedad a la que se tiene acceso a través del nombre de parámetro como parámetro.

{  
    "query": "select @id, d[@propName] from docs d",   
    "parameters": [   
        {"@id": "newdoc"},  
        {"@propName": "prop"}  
     ]  
}  

Consultas que la puerta de enlace no puede atender

La puerta de enlace no puede atender cualquier consulta que requiera estado entre las continuaciones. Esto incluye:

• TOP
• ORDER BY
• OFFSET LIMIT
• Agregados
• DISTINCT
• GROUP BY

Las consultas que puede atender la puerta de enlace incluyen:

• Proyecciones simples
• Filtros

Cuando se devuelve una respuesta para una consulta que no puede servir la puerta de enlace, contendrá el código de estado 400 (BadRequest) y el siguiente mensaje:

{"code":"BadRequest","message":"The provided cross partition query can not be directly served by the gateway. 
This is a first chance (internal) exception that all newer clients will know how to handle gracefully. 
This exception is traced, but unless you see it bubble up as an exception (which only happens on older SDK clients), 
then you can safely ignore this message.\r\nActivityId: db660ee4-350a-40e9-bc2c-99f92f2b445d, Microsoft.Azure.Documents.Common/2.2.0.0",
"additionalErrorInfo":"{\"partitionedQueryExecutionInfoVersion\":2,\"queryInfo\":{\"distinctType\":\"None\",\"top\":null,\"offset\":null,\"limit\":null,
\"orderBy\":[\"Ascending\"],\"orderByExpressions\":[\"c._ts\"],\"aggregates\":[],
\"rewrittenQuery\":\"SELECT c._rid, [{\\\"item\\\": c._ts}] AS orderByItems, 
c AS payload\\nFROM c\\nWHERE ({documentdb-formattableorderbyquery-filter})\\nORDER BY c._ts\"},
\"queryRanges\":[{\"min\":\"\",\"max\":\"FF\",\"isMinInclusive\":true,\"isMaxInclusive\":false}]}"}

Paginación de resultados de consulta

Las solicitudes de consulta admiten la paginación mediante los encabezados x-ms-max-item-count y x-ms-continuation request. El encabezado x-ms-max-item-count especifica el número máximo de valores que la ejecución de consulta puede devolver. El valor puede estar entre 1 y 1000 y está configurado con un valor predeterminado de 100.

Las consultas devolverán desde un valor de cero hasta el valor de x-ms-max-item-count máximo especificado desde los resultados de la ejecución. El resultado de la consulta incluye un encabezado x-ms-item-count que especifica el número real de documentos que devuelve la consulta. Si hay resultados adicionales que se pudieran recuperar desde la consulta, la respuesta incluye un valor no vacío para el encabezado x-ms-continuation.

Los clientes pueden capturar páginas subsiguientes de resultados si reitera el encabezado x-ms-continuation como otra solicitud. Para leer todos los resultados, los clientes deben repetir este proceso hasta que se devuelva un x-ms-continuation vacío.

Las ejecuciones de consultas de Cosmos DB no tienen estado en el lado servidor y se pueden reanudar en cualquier momento mediante el encabezado x-ms-continuation . El valor x-ms-continuation usa identificador de recursos del último documento procesado (_rid) para hacer seguimiento del progreso de la ejecución. Por lo tanto, si los documentos se eliminan y se vuelven a insertar entre la captura de páginas, los documentos podrían excluirse de cualquiera de los lotes de consulta. Sin embargo, el comportamiento y el formato el encabezado x-ms-continuation podría cambiar en una actualización de servicio futura.

Consulte también

• Azure Cosmos DB
• API de SQL de Azure Cosmos DB
• SDK de SQL API de Azure Cosmos DB
• REST desde el ejemplo de .NET