Share via

Consultar recursos do Azure Cosmos DB usando a API REST

  • Artigo

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

Método URI da solicitação
POST Obrigatório. O tipo de autenticação e o token de assinatura. Apenas o token da chave mestra é permitido para esta operação. Para obter mais informações, consulte Controle de Acesso em Recursos do Cosmos DB.

Cabeçalhos de solicitação

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

Cabeçalho padrão Descrição
Autorização Obrigatório. O tipo de autenticação e o token de assinatura. Apenas o token da chave mestra é permitido para esta operação. Para obter mais informações, consulte Controle de Acesso em Recursos do Cosmos DB.
Content-Type Obrigatório. Deve ser definido como application/query+json.
Aceitar Opcional. No momento, o Cosmos DB sempre retorna o conteúdo da resposta no formato JSON padrão. O cliente deve ser capaz de aceitar o corpo da resposta no formato JSON padrão.
User-Agent Opcional. O agente do usuário que está executando a solicitação. O formato recomendado é {nome do agente usuário}/{versão}. Por exemplo, o SDK do .NET da API do SQL define a cadeia de User-Agent como Microsoft.Document.Client/1.0.0.0.
Cabeçalho personalizado Descrição
x-ms-date Obrigatório. A data da solicitação, conforme especificado no RFC 1123. O formato de data é expresso em UTC (Tempo Universal Coordenado), por exemplo. Sexta-feira, 8 de abril de 2015, 03:52:31 GMT.
x-ms-documentdb-isquery Obrigatório. Esta propriedade deve ser definida como true.
x-ms-max-item-count Opcional. Para ver um conjunto de resultados, defina este cabeçalho como o número máximo de itens a serem retornados em uma única página.
x-ms-continuation Opcional. Para navegar para a próxima página de itens, defina esse cabeçalho como token de continuação para a próxima página.
x-ms-version Opcional. A versão do serviço REST do Cosmos DB. A versão mais recente é usada quando o cabeçalho não é fornecido. Para obter mais informações, consulte Referência da API REST do Azure Cosmos DB.
x-ms-documentdb-query-enable-scan Opcional. Use uma verificação de índice para processar a consulta se o caminho do índice de tipo certo não estiver disponível.
x-ms-session-token Opcional. O token de sessão para a solicitação. Usado para consistência de sessão.
x-ms-partition-key Opcional. Se especificada, a consulta será executada somente em documentos que correspondam ao valor da chave de partição no cabeçalho.
x-ms-documentdb-query-enablecrosspartition Opcional. Deve ser definido como true para todas as consultas que não filtram em uma única chave de partição. As consultas que filtram em relação a um único valor de chave de partição serão executadas em apenas uma única partição, mesmo que isso seja definido como true.
x-ms-documentdb-populatequerymetrics Opcional. Deve ser definido como True para retornar métricas 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.

Propriedade Descrição
Consulta Obrigatório. A cadeia de consulta SQL para a consulta. Para obter mais informações, consulte Referência de sintaxe sql do Azure Cosmos DB.
parameters Obrigatório. Uma matriz JSON de parâmetros especificados como pares de valor de nome. A matriz de parâmetros pode conter de zero a muitos parâmetros. Cada parâmetro deve ter os seguintes valores:name: o nome do parâmetro. Os nomes de parâmetro devem ser literais de cadeia de caracteres válida e começar com "@".value: o valor do parâmetro. Pode ser qualquer valor JSON válido (cadeia de caracteres, número, objeto, matriz, Booliano ou null).

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.

Código Descrição
200 Ok A operação teve êxito.
400 Solicitação Inválida A sintaxe da instrução SQL está incorreta.
401 Não Autorizado O cabeçalho Autorização ou x-ms-data não está definido. 401 também é retornado quando o cabeçalho Autorização é definido para um token de autorização inválido.
403 Forbidden O token de autorização expirou.
404 Não Encontrado A coleção não é mais um recurso. Por exemplo, o recurso pode ter sido excluído.

Cabeçalhos de resposta

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

Cabeçalho padrão Descrição
Content-Type O Content-Type é aplicativo/json. O Cosmos DB sempre retorna o corpo da resposta no formato JSON padrão.
Data A data e hora da operação de resposta. Esse formato de data e hora está de acordo com o formato de hora de data [RFC1123] expresso em UTC.
Cabeçalho personalizado Descrição
x-ms-item-count O número de item retornado pela operação.
x-ms-continuation É uma cadeia de caracteres opaca retornada quando a consulta tem potencialmente mais itens a serem recuperados.

A x-ms-continuation pode ser incluída nas solicitações subsequentes, como um cabeçalho de solicitação para retomar a execução da consulta.
x-ms-request-charge É o número de RU (unidades de solicitação) consumidas pela operação. Para obter mais informações sobre unidades de solicitação, consulte Unidades de solicitação no Azure Cosmos DB.
x-ms-activity-id É um identificador exclusivo para a operação. Ele pode ser usado para rastrear a execução de solicitações do Cosmos DB.
x-ms-session-token O token de sessão a ser usado para solicitações subsequentes. Usado para consistência de sessão.

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}
Propriedade Descrição
_Livrar A ID do recurso para a coleção usada na consulta.
_Contar O número de itens retornados.
Matriz de recursos A matriz que contém os resultados da consulta.

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