Consultar recursos do Azure Cosmos DB com a API REST

O Azure Cosmos DB é uma base de dados com múltiplos modelos distribuído globalmente com suporte para várias APIs. Este artigo descreve como utilizar o REST para consultar recursos com a API SQL.

Como devo proceder para consultar um recurso com REST?

Para efetuar uma consulta SQL num recurso, faça o seguinte:

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

Para obter um exemplo que mostre como efetuar uma consulta SQL num recurso com .NET, veja REST from .NET Sample (Exemplo REST de .NET).

Exemplo

Segue-se um exemplo de operação de consulta REST nos recursos do documento. Neste exemplo, gostaríamos de encontrar 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 do Pedido

Cabeçalhos do Pedido

A tabela seguinte contém os cabeçalhos comuns utilizados para realizar operações de consulta.

Corpo do Pedido

O corpo do pedido deve ser um documento JSON válido que contenha a consulta SQL e os parâmetros. Se a entrada tiver uma sintaxe SQL incorreta ou inválida, a operação com falha com um erro 400 Pedido Incorreto.

Também receberá um pedido 400 incorreto se não for possível servir uma consulta pelo gateway.

Exemplo de Pedido

O exemplo seguinte faz um pedido SQL parametrizado com um parâmetro de cadeia 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, veja Consultas SQL para o Azure Cosmos DB.

Detalhes da Resposta

Seguem-se os códigos de estado comuns devolvidos por esta operação. Para obter informações sobre os códigos de estado de erro, veja Códigos de Estado HTTP para o Azure Cosmos DB.

Cabeçalhos de Resposta

Esta operação devolve os seguintes cabeçalhos comuns. Podem ser devolvidos cabeçalhos padrão e comuns adicionais.

Corpo da Resposta

O corpo de resposta da operação de consulta consiste na _rid do recurso principal do recurso que está a ser consultado e na matriz de recursos que contém as propriedades do recurso para a projeção e seleção. De acordo com o exemplo, se uma consulta tiver sido efetuada no caminho dos documentos da coleção com uma _rid de XP0mAJ3H-AA=, a resposta será a seguinte:

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

Criar o corpo do pedido de consulta

O pedido de consulta tem de ser um documento JSON válido que contenha uma propriedade de consulta que contenha uma cadeia de consulta SQL válida e uma propriedade de parâmetros que contenha uma matriz de parâmetros opcionais. Cada parâmetro deve ter um nome e uma propriedade de valor de parâmetros especificados na consulta. Os nomes dos parâmetros têm de começar com o caráter "@". Os valores podem ser valores JSON válidos – cadeias, números inteiros, Booleanos e nulos.

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

Alguns exemplos de pedidos de consulta válidos são apresentados abaixo. Por exemplo, a consulta seguinte tem um único parâmetro @id.

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

O exemplo seguinte tem dois parâmetros, um com um valor de cadeia 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 seguinte utiliza parâmetros na cláusula SELECT, bem como uma propriedade acedida através do nome do 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 servidas pelo gateway

Qualquer consulta que necessite de estado entre continuações não pode ser servida pelo gateway. O que está incluído:

• SUPERIOR
• ORDENAR POR
• LIMITE DE DESLOCAMENTO
• Agregados
• DISTINCT
• GROUP BY

As consultas que podem ser servidas pelo gateway incluem:

• Projeções simples
• Filtros

Quando é devolvida uma resposta para uma consulta que não pode ser servida pelo gateway, conterá o código de estado 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 dos resultados da consulta

Os pedidos de consulta suportam a paginação através dos cabeçalhos de pedido x-ms-max-item-count e x-ms-continuation . O cabeçalho x-ms-max-item-count especifica o número máximo de valores que podem ser devolvidos pela execução da consulta. Isto pode ser entre 1 e 1000 e está configurado com uma predefinição de 100.

As consultas devolverão de zero até ao valor máximo especificado 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 devolvidos pela consulta. Se existirem resultados adicionais que possam ser obtidos a partir da consulta, a resposta inclui um valor não vazio para o cabeçalho x-ms-continuation .

Os clientes podem obter páginas de resultados subsequentes ao ecoar o cabeçalho x-ms-continuation como outro pedido. Para ler todos os resultados, os clientes têm de repetir este processo até que seja devolvida uma x-ms-continuation vazia.

As execuções de consultas do Cosmos DB não têm estado no lado do servidor e podem ser retomadas em qualquer altura com o cabeçalho x-ms-continuation . O valor x-ms-continuation utiliza o último ID de recurso de documento processado (_rid) para controlar o progresso da execução. Por conseguinte, se os documentos forem eliminados e reinseridos entre a obtenção de páginas, os documentos poderão potencialmente ser excluídos de qualquer um dos lotes de consulta. No entanto, o comportamento e o formato do cabeçalho x-ms-continuation podem mudar numa futura atualização de serviço.

Consulte também

• BD do Cosmos para o Azure
• API SQL do Azure Cosmos DB
• Azure Cosmos DB SQL API SDKs
• REST a partir do Exemplo de .NET