Consultar recursos do Azure Cosmos DB usando a API REST

O Azure Cosmos DB é um serviço de banco de dados multimodelo globalmente distribuído compatível com várias APIs. Este artigo descreve como usar REST para consultar recursos usando a API do SQL.

Como consultar um recurso usando REST?

Para executar uma consulta SQL em um recurso, faça o seguinte:

• Execute um POST método em um caminho de recurso usando JSON com a query propriedade definida como a cadeia de caracteres de consulta SQL e a propriedade "parameters" definida como a matriz de valores de parâmetro opcionais.
• Defina o cabeçalho x-ms-documentdb-isquery como True.
• Defina o cabeçalho Content-Type como application/query+json.

Para obter um exemplo que mostra como executar uma consulta SQL em um recurso usando o .NET, consulte REST do exemplo do .NET.

Exemplo

Veja a seguir um exemplo de operação de consulta REST em recursos de documento. Neste exemplo, queremos localizar todos os documentos que têm “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": []  
}  
  

Detalhes da solicitação

Cabeçalhos de solicitação

A tabela a seguir contém os cabeçalhos comuns usados para executar operações de consulta.

Corpo da solicitação

O corpo da solicitação deve ser um documento válido de JSON que contém a consulta SQL e parâmetros. Se a entrada for uma sintaxe SQL malformada ou inválida, a operação falha com um erro 400 Solicitação Incorreta.

Você também receberá uma solicitação 400 incorreta se uma consulta não puder ser atendida pelo gateway.

Exemplo de solicitação

O exemplo a seguir faz uma solicitação SQL parametrizada com um parâmetro de cadeia de caracteres 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 obter mais informações sobre as consultas SQL, consulte Consultas SQL para o Azure Cosmos DB.

Detalhes da resposta

A seguir estão os códigos de status comuns retornados por esta operação. Para obter informações sobre códigos de status de erro, consulte Códigos de status HTTP para o Azure Cosmos DB.

Cabeçalhos de resposta

Esta operação retorna os seguintes cabeçalhos comuns. Pode existir cabeçalhos padrão e comuns adicionais retornados.

Corpo da resposta

O corpo da resposta para a operação de consulta consiste em _rid do recurso pai do recurso do recurso que está sendo consultado e a matriz de recursos que contém as propriedades do recurso para projeção e seleção. Por exemplo, se uma consulta tiver sido executada no caminho documentos da coleção com um _rid XP0mAJ3H AA =, a resposta seria a seguinte:

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

Criando o corpo da solicitação de consulta

A solicitação de consulta deve ser um documento válido de JSON que contém um propriedade query que contém uma cadeia de caracteres de consulta SQL válida e uma propriedade parameters que contém uma matriz de parâmetros opcionais. Cada parâmetro deve ter uma propriedades name e value de parâmetros que são especificados na consulta. Os nomes de parâmetro devem começar com o caractere "@". Os valores podem ser quaisquer valores JSON válidos: cadeias de caracteres, números inteiros, Boolianos e valores nulos.

É válido especificar apenas um subconjunto de parâmetros especificados no texto da consulta . As expressões que referenciam esses parâmetros não especificados serão avaliada como indefinidas. Também é válido para especificar parâmetros adicionais que não são usados dentro do texto query.

Alguns exemplos de solicitações de consulta válida são mostrados abaixo. Por exemplo, a consulta a seguir tem um único parâmetro @id.

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

O exemplo a seguir tem dois parâmetros, um com um valor de cadeia de caracteres e outro com um valor inteiro.

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

O exemplo a seguir usa os parâmetros na cláusula SELECT, bem como uma propriedade acessada pelo nome de parâmetro como um parâmetro.

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

Consultas que não podem ser atendidas pelo gateway

Qualquer consulta que exija estado entre continuações não pode ser atendida pelo gateway. Isso inclui:

• INÍCIO
• ORDER BY
• OFFSET LIMIT
• Agregações
• DISTINTO
• GROUP BY

As consultas que podem ser atendidas pelo gateway incluem:

• Projeções simples
• Filtros

Quando uma resposta é retornada para uma consulta que não pode ser atendida pelo gateway, ela conterá o código status 400 (BadRequest) e a seguinte mensagem:

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

Paginação de resultados da consulta

As solicitações de consulta dão suporte à paginação por meio dos cabeçalhos x-ms-max-item-count e x-ms-continuation request. O cabeçalho x-ms-max-item-count especifica o número máximo de valores que podem ser retornados pela execução de consulta. Esse número pode ser entre 1 e 1000 e está configurado com um padrão de 100.

As consultas retornam de zero até o máximo especificado dos valores x-ms-max-item-count dos resultados da execução. O resultado da consulta inclui um cabeçalho x-ms-item-count que especifica o número real de documentos retornados pela consulta. Se há resultados adicionais que podem ser recuperados da consulta, a resposta inclui um valor não vazio para o cabeçalho x-ms-continuation.

Os clientes podem buscar páginas subsequentes de resultados exibindo o cabeçalho x-ms-continuation como outra solicitação. Para ler todos os resultados, os clientes devem repetir este processo até que um x-ms-continuation seja retornado.

As execuções de consulta do Cosmos DB são sem estado no lado do servidor e podem ser retomadas a qualquer momento usando o cabeçalho x-ms-continuation . O valor x-ms-continuation usa a última ID de recurso de documentos processados (_rid) para acompanhar o andamento da execução. Portanto, se os documentos forem excluídos e reinseridos entre a busca de páginas, os documentos poderão ser excluídos de qualquer um dos lotes de consulta. No entanto, o comportamento e o formato do cabeçalho x-ms-continuation pode ser alterado em uma atualização futura do serviço.

Consulte Também

• Azure Cosmos DB
• API de SQL do Azure Cosmos DB
• Azure Cosmos DB SQL API SDKs
• Rest do exemplo do .NET