Consultar Documentos
Você pode consultar documentos json arbitrários em uma coleção executando uma postagem no recurso "colls" no Cosmos DB. A sintaxe sql do Cosmos DB fornece operadores de consulta hierárquica, relacional e espacial para consultar e projetar documentos. Para obter mais informações sobre como consultar recursos no Cosmos DB, consulte consultando recursos.
Método | URI da solicitação | Descrição |
---|---|---|
post | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs | observe que {databaseaccount} é o nome da conta do Cosmos DB criada em sua assinatura. o valor {db-id} é o nome/id gerado pelo usuário do banco de dados, não a ID gerada pelo sistema (rid). o valor {coll-id} é o nome da coleção. |
Confira Cabeçalhos comuns de solicitação REST do Azure Cosmos DB para cabeçalhos usados por todas as solicitações do Cosmos DB.
Cabeçalho | Obrigatório | Type | Descrição |
---|---|---|---|
x-ms-documentdb-isquery | Obrigatório | Boolean | Deve ser definido como True indicando que POST é uma consulta. |
Content-Type | Obrigatório | String | Uma cadeia de caracteres que deve ser definida como application/query+json. |
x-ms-max-item-count | Opcional | Número | Um inteiro que indica o número máximo de itens a serem retornados por página. As consultas não retornarão mais do que o número especificado de itens por página, mas podem ser menos dependendo da camada de desempenho da coleção e de seus tamanhos. Uma contagem de itens x-ms-max de -1 pode ser especificada para permitir que o serviço determine a contagem de itens ideal. É o valor de configuração recomendado para x-ms-max-item-count. |
x-ms-continuation | Opcional | String | Um token de cadeia de caracteres retornado para consultas e operações de feed de leitura se houver mais resultados a serem lidos. Os clientes podem recuperar a próxima página de resultados reenviando a solicitação com o cabeçalho de solicitação x-ms-continuation definido como esse valor. |
x-ms-documentdb-query-enablecrosspartition | Opcional | Boolean | Se a coleção for particionada, isso deverá ser definido como True para permitir a execução em várias partições. Consultas que filtram em uma única chave de partição ou em coleções particionadas única não precisam definir o cabeçalho. |
x-ms-consistency-level | Opcional | String | Esta é a substituição de nível consistente. Os valores válidos são: Strong, Bounded, Session ou Eventual (na ordem de mais forte para mais fraco). A substituição deve ser a mesma ou mais fraca do que o nível de consistência configurado da conta. |
x-ms-session-token | Opcional | String | Um token de cadeia de caracteres usado com consistência de nível de sessão. Os clientes devem ecoar o valor de leitura mais recente desse cabeçalho durante solicitações de leitura para consistência de sessão. |
Importante
Para o Content-Type
cabeçalho, NÃO inclua o conjunto de caracteres (ou seja, "application/query+json; charset-utf-8"). O cabeçalho deve ser exatamente como mostrado acima.
Propriedade | Obrigatório | Type | Descrição |
---|---|---|---|
consulta | Obrigatório | String | Contém o texto da consulta SQL. Para gramática, consulte Gramática sql. |
parameters | Obrigatório | Array | Uma matriz de valores de parâmetro para a consulta. |
{
"query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",
"parameters": [
{
"name": "@id",
"value": "AndersenFamily"
},
{
"name": "@city",
"value": "Seattle"
}
]
}
Retorna uma matriz de documentos que correspondem à consulta solicitada.
Consulte Cabeçalhos comuns de resposta REST do Azure Cosmos DB para obter cabeçalhos retornados por todas as respostas do Cosmos DB. Os cabeçalhos de resposta importantes são:
Propriedade | Type | Descrição |
---|---|---|
x-ms-continuation | String | Retorna um token para buscar mais resultados da operação. O cliente pode reenviar a solicitação com o cabeçalho de solicitação x-ms-continuation que contém esse valor para retomar a execução. |
x-ms-request-charge | Número | O número de unidades de solicitação consumidas pela operação. |
A tabela a seguir lista os códigos de status comuns retornados por esta operação. Para obter uma lista completa de códigos de status, consulte Códigos de status HTTP.
Código de status HTTP | Descrição |
---|---|
200 OK | A operação foi bem-sucedida. |
400 Solicitação Inválida | A solicitação especificada foi definida com uma sintaxe de SQL incorreta ou com cabeçalhos necessários ausentes. |
Propriedade | Descrição |
---|---|
_Livrar | Essa é a ID de recursos gerada pelo sistema para a coleção onde residem os documentos. |
_Contar | Esse é o número de documentos retornados pela operação de lista. |
Documentos | A matriz de documentos retornada pela operação. |
Propriedades do Documento
Propriedade | Descrição |
---|---|
id | Esse é o nome exclusivo que identifica o documento, ou seja, nenhum documento pode compartilhar a mesma ID. A ID não deve exceder 255 caracteres. |
<custom> | Qualquer JSON definido pelo usuário. |
_Livrar | Essa é uma propriedade gerada pelo sistema. A ID do recurso (_rid) é um identificador exclusivo que também é hierárquico de acordo com a pilha de recursos no modelo de recurso. Ela é usada internamente para posicionamento e navegação do recurso de documento. |
_Ts | Essa é uma propriedade gerada pelo sistema. Especifica o último carimbo de data/hora atualizado do recurso. O valor é um carimbo de data/hora. |
_Auto | Essa é uma propriedade gerada pelo sistema. É o URI endereçável exclusivo do recurso. |
_Etag | Essa é uma propriedade gerada pelo sistema que especifica a etag de recurso necessária para o controle de simultaneidade otimista. |
_Anexos | Esta é uma propriedade gerada adequadamente que especifica o caminho endereçável para o recurso de anexos. |
{
"_rid": "1KtjAImkcgw=",
"Documents": [
{
"id": "AndersenFamily",
"LastName": "Andersen",
"Parents": [
{
"FamilyName": null,
"FirstName": "Thomas"
},
{
"FamilyName": null,
"FirstName": "Mary Kay"
}
],
"Children": [
{
"FamilyName": null,
"FirstName": "Henriette Thaulow",
"Gender": "female",
"Grade": 5,
"Pets": [
{
"GivenName": "Fluffy"
}
]
}
],
"Address": {
"State": "WA",
"County": "King",
"City": "Seattle"
},
"IsRegistered": true,
"_rid": "1KtjAImkcgwBAAAAAAAAAA==",
"_self": "dbs/1KtjAA==/colls/1KtjAImkcgw=/docs/1KtjAImkcgwBAAAAAAAAAA==/",
"_etag": "\"00003200-0000-0000-0000-56f9e84d0000\"",
"_ts": 1459218509,
"_attachments": "attachments/"
}
],
"_count": 1
}
POST https://querydemo.documents.azure.com/dbs/1KtjAA==/colls/1KtjAImkcgw=/docs HTTP/1.1
x-ms-continuation:
x-ms-documentdb-isquery: True
x-ms-documentdb-query-enablecrosspartition: True
x-ms-date: Tue, 29 Mar 2016 02:28:32 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3drOlOhFh9plfC0ggZfmHtS3XepVitiIRsd6i1d9PnuW8%3d
Cache-Control: no-cache
User-Agent: Microsoft.Azure.Documents.Client/1.6.0.0
x-ms-version: 2015-12-16
Accept: application/json
Content-Type: application/query+json
Host: querydemo.documents.azure.com
Cookie: x-ms-session-token#0=604; x-ms-session-token=604
Content-Length: 170
Expect: 100-continue
{
"query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",
"parameters": [
{
"name": "@id",
"value": "AndersenFamily"
},
{
"name": "@city",
"value": "Seattle"
}
]
}
HTTP/1.1 201 Created
Cache-Control: no-store, no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Server: Microsoft-HTTPAPI/2.0
Strict-Transport-Security: max-age=31536000
x-ms-last-state-change-utc: Fri, 25 Mar 2016 22:39:02.501 GMT
etag: "00003200-0000-0000-0000-56f9e84d0000"
x-ms-resource-quota: documentSize=10240;documentsSize=10485760;collectionSize=10485760;
x-ms-resource-usage: documentSize=0;documentsSize=1;collectionSize=1;
x-ms-schemaversion: 1.1
x-ms-alt-content-path: dbs/testdb/colls/testcoll
x-ms-quorum-acked-lsn: 602
x-ms-current-write-quorum: 3
x-ms-current-replica-set-size: 4
x-ms-request-charge: 12.38
x-ms-serviceversion: version=1.6.52.5
x-ms-activity-id: 856acd38-320d-47df-ab6f-9761bb987668
x-ms-session-token: 0:603
Set-Cookie: x-ms-session-token#0=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=
Set-Cookie: x-ms-session-token=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=
x-ms-gatewayversion: version=1.6.52.5
Date: Tue, 29 Mar 2016 02:28:30 GMT
{
"id": "AndersenFamily",
"LastName": "Andersen",
"Parents": [
{
"FamilyName": null,
"FirstName": "Thomas"
},
{
"FamilyName": null,
"FirstName": "Mary Kay"
}
],
"Children": [
{
"FamilyName": null,
"FirstName": "Henriette Thaulow",
"Gender": "female",
"Grade": 5,
"Pets": [
{
"GivenName": "Fluffy"
}
]
}
],
"Address": {
"State": "WA",
"County": "King",
"City": "Seattle"
},
"IsRegistered": true,
"_rid": "1KtjAImkcgwBAAAAAAAAAA==",
"_self": "dbs/1KtjAA==/colls/1KtjAImkcgw=/docs/1KtjAImkcgwBAAAAAAAAAA==/",
"_etag": "\"00003200-0000-0000-0000-56f9e84d0000\"",
"_ts": 1459218509,
"_attachments": "attachments/"
}