Consultar Documentos
Pode consultar documentos json arbitrários numa coleção ao efetuar uma publicação 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, veja Consultar recursos.
Pedir
| Método | URI do pedido | Description |
|---|---|---|
| publicar | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs | tenha em atenção que {databaseaccount} é o nome da conta do Cosmos DB criada na sua subscrição. o valor {db-id} é o nome/ID gerado pelo utilizador da base de dados, não o ID gerado pelo sistema (rid). o valor {coll-id} é o nome da coleção. |
Cabeçalhos
Veja Common Azure Cosmos DB REST request headers for headers that are used by all Cosmos DB requests (Cabeçalhos de pedido REST do Azure Cosmos DB comuns para cabeçalhos que são utilizados por todos os pedidos do Cosmos DB).
| Cabeçalho | Necessário | Tipo | Description |
|---|---|---|---|
| x-ms-documentdb-isquery | Necessário | Booleano | Tem de ser definido como Verdadeiro a indicar que POST é uma consulta. |
| Tipo de Conteúdo | Necessário | String | Uma cadeia que tem de ser definida como aplicação/consulta+json. |
| x-ms-max-item-count | Opcional | Número | Um número inteiro que indica o número máximo de itens a devolver por página. As consultas não devolverão mais do que o número especificado de itens por página, mas podem ser menos consoante o escalão de desempenho da coleção e os respetivos tamanhos. Pode especificar uma contagem de itens x-ms-max-item-count de -1 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 devolvido para consultas e operações de feed de leitura se existirem mais resultados a ler. Os clientes podem obter a página seguinte dos resultados ao submeter novamente o pedido com o cabeçalho do pedido x-ms-continuation definido para este valor. |
| x-ms-documentdb-query-enablecrosspartition | Opcional | Booleano | Se a coleção estiver particionada, esta tem de ser definida como Verdadeiro para permitir a execução em várias partições. As consultas que filtram numa única chave de partição ou em coleções de partição única não precisam de definir o cabeçalho. |
| x-ms-consistency-level | Opcional | String | Esta é a substituição do nível de consistência. Os valores válidos são: Forte, Vinculado, Sessão ou Eventual (por ordem do mais forte para o mais fraco). A substituição tem de ser igual ou mais fraca do que o nível de consistência configurado da conta. |
| x-ms-session-token | Opcional | String | Um token de cadeia utilizado com consistência ao nível da sessão. Os clientes têm de ecoar o valor de leitura mais recente deste cabeçalho durante os pedidos de leitura para consistência da sessão. |
Importante
Para o cabeçalho Content-Type NÃO inclua o conjunto de carateres (ou seja, "application/query+json; charset-utf-8"). O cabeçalho tem de ser exatamente o mostrado acima.
Corpo
| Propriedade | Necessário | Tipo | Description |
|---|---|---|---|
| consulta | Necessário | String | Contém o texto da consulta SQL. Para obter a gramática, veja Gramática do SQL. |
| parameters | Necessário | Matriz | Uma matriz de valores de parâmetros 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"
}
]
}
Resposta
Devolve uma matriz de documentos que correspondem à consulta pedida.
Cabeçalhos
Veja Common Azure Cosmos DB REST response headers for headers that are returned by all Cosmos DB responses (Cabeçalhos de resposta REST do Azure Cosmos DB comuns para cabeçalhos devolvidos por todas as respostas do Cosmos DB). Os cabeçalhos de resposta importantes são:
| Propriedade | Tipo | Description |
|---|---|---|
| x-ms-continuation | String | Devolve um token para obter mais resultados da operação. O cliente pode submeter novamente o pedido com o cabeçalho do pedido x-ms-continuation que contém este valor para retomar a execução. |
| x-ms-request-charge | Número | O número de unidades de pedido consumidas pela operação. |
Códigos de estado
A tabela seguinte lista os códigos de estado comuns devolvidos por esta operação. Para obter uma lista completa dos códigos de estado, veja Códigos de Estado HTTP.
| Código de estado de HTTP | Descrição |
|---|---|
| 200 OK | A operação foi efetuada com êxito. |
| 400 Pedido Incorreto | O pedido especificado foi especificado com uma sintaxe SQL incorreta ou cabeçalhos necessários em falta. |
Corpo
| Propriedade | Descrição |
|---|---|
| _rid | Este é o ID de recurso gerado pelo sistema para a coleção onde residem os documentos. |
| _count | Este é o número de documentos devolvidos pela operação de lista. |
| Documentos | A matriz de documentos devolvidos pela operação. |
Propriedades do Documento
| Propriedade | Descrição |
|---|---|
| id | Este é o nome exclusivo que identifica o documento, ou seja, nenhum documento pode partilhar o mesmo ID. O ID não pode exceder os 255 carateres. |
| <personalizado> | Qualquer JSON definido pelo utilizador. |
| _rid | Esta é uma propriedade gerada pelo sistema. O ID do recurso (_rid) é um identificador exclusivo que também é hierárquico de acordo com a pilha de recursos no modelo de recursos. É utilizado internamente para posicionamento e navegação do recurso de documento. |
| _ts | Esta é uma propriedade gerada pelo sistema. Especifica o último carimbo de data/hora atualizado do recurso. O valor é um carimbo de data/hora. |
| _self | Esta é uma propriedade gerada pelo sistema. É o URI endereçável exclusivo para o recurso. |
| _etag | Esta é uma propriedade gerada pelo sistema que especifica o etag de recursos necessário para o controlo de simultaneidade otimista. |
| _attachments | Esta é uma propriedade gerada pelo sistema 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
}
Exemplo
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/"
}