Interroger des documents
Vous pouvez interroger des documents json arbitraires dans une collection en effectuant un billet sur la ressource « colls » dans Cosmos DB. La syntaxe sql de Cosmos DB fournit des opérateurs de requête hiérarchiques, relationnelles et spatiales pour interroger des documents et des projets. Pour plus d’informations sur l’interrogation de ressources dans Cosmos DB, consultez interrogation de ressources.
Requête
| Méthode | URI de demande | Description |
|---|---|---|
| post | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs | Notez que {databaseaccount} est le nom du compte Cosmos DB créé dans le cadre de votre abonnement. la valeur {db-id} est le nom/id généré par l’utilisateur de la base de données, et non l’ID généré par le système (rid). la valeur {coll-id} est le nom de la collection. |
En-têtes
Consultez En-têtes de requête REST Azure Cosmos DB communs pour les en-têtes utilisés par toutes les requêtes Cosmos DB.
| En-tête | Obligatoire | Type | Description |
|---|---|---|---|
| x-ms-documentdb-isquery | Obligatoire | Boolean | Doit être défini sur True, ce qui indique que post est une requête. |
| Content-Type | Obligatoire | String | Chaîne qui doit être définie sur application/query+json. |
| x-ms-max-item-count | Facultatif | Number | Entier indiquant le nombre maximal d’éléments à retourner par page. Les requêtes ne retournent pas plus que le nombre spécifié d’éléments par page, mais peuvent être inférieures en fonction du niveau de performance de la collection et de leur taille. Une valeur x-ms-max-item-count de -1 peut être spécifiée pour permettre au service de déterminer le nombre d’éléments optimal. Il s’agit de la valeur de configuration recommandée pour x-ms-max-item-count. |
| x-ms-continuation | Facultatif | String | Jeton de chaîne retourné pour les requêtes et les opérations de flux de lecture si d’autres résultats doivent être lus. Les clients peuvent récupérer la page de résultats suivante en renvoyant la demande avec l’en-tête de demande x-ms-continuation défini sur cette valeur. |
| x-ms-documentdb-query-enablecrosspartition | Facultatif | Booléen | Si la collection est partitionnée, elle doit être définie sur True pour permettre l’exécution sur plusieurs partitions. Les requêtes qui filtrent sur une clé de partition unique ou sur des collections à partition unique n’ont pas besoin de définir l’en-tête. |
| x-ms-consistency-level | Facultatif | String | Remplacement de niveau de cohérence. Les valeurs valides sont les suivantes : Strong, Bounded, Session ou Eventual (dans l’ordre du plus fort au plus faible). Le remplacement doit être identique ou plus faible que le niveau de cohérence configuré du compte. |
| x-ms-session-token | Facultatif | String | Jeton de chaîne utilisé avec la cohérence au niveau de la session. Les clients doivent faire écho à la dernière valeur de lecture de cet en-tête lors des demandes de lecture de cohérence de session. |
Important
Pour l’en-tête Content-Type , n’incluez PAS l’ensemble de caractères (c’est-à-dire « application/query+json ; charset-utf-8 »). L’en-tête doit être exactement comme indiqué ci-dessus.
body
| Propriété | Obligatoire | Type | Description |
|---|---|---|---|
| requête | Obligatoire | String | Contient le texte de la requête SQL. Pour plus d’informations sur la grammaire, consultez Grammaire SQL. |
| parameters | Obligatoire | Array | Tableau de valeurs de paramètres pour la requête. |
{
"query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",
"parameters": [
{
"name": "@id",
"value": "AndersenFamily"
},
{
"name": "@city",
"value": "Seattle"
}
]
}
response
Retourne un tableau de documents qui correspondent à la requête demandée.
En-têtes
Consultez En-têtes de réponse REST Azure Cosmos DB communs pour les en-têtes retournés par toutes les réponses Cosmos DB. Les en-têtes de réponse importants sont les suivants :
| Propriété | Type | Description |
|---|---|---|
| x-ms-continuation | String | Retourne un jeton pour extraire d’autres résultats de l’opération. Le client peut renvoyer la demande avec l’en-tête de demande x-ms-continuation contenant cette valeur pour reprendre l’exécution. |
| x-ms-request-charge | Number | Nombre d’unités de requête consommées par l’opération. |
Codes d’état
Le tableau suivant répertorie les codes d'état courants renvoyés par cette opération. Pour obtenir la liste complète des codes status, consultez Codes d’état HTTP.
| Code d'état HTTP | Description |
|---|---|
| 200 OK | L'opération a réussi. |
| 400 Demande incorrecte | La demande spécifiée a été spécifiée avec une syntaxe de SQL incorrecte, ou des en-têtes obligatoires sont manquants. |
body
| Propriété | Description |
|---|---|
| _Débarrasser | Id de ressource généré par le système pour la collection dans laquelle les documents résident. |
| _Compter | Nombre de documents renvoyés par l'opération Liste. |
| Documents | Tableau des documents renvoyés par l'opération. |
Propriétés du document
| Propriété | Description |
|---|---|
| id | Il s’agit du nom unique qui identifie le document, c’est-à-dire qu’aucun document ne peut partager le même ID. L’ID ne doit pas dépasser 255 caractères. |
| <custom> | Tout JSON défini par l'utilisateur. |
| _Débarrasser | Il s’agit d’une propriété générée par le système. L’ID de ressource (_rid) est un identificateur unique qui est également hiérarchique en fonction de la pile de ressources sur le modèle de ressource. Il est utilisé en interne pour le positionnement et la navigation de la ressource de document. |
| _Ts | Cette propriété est générée par le système. Elle spécifie l'horodateur de la dernière mise à jour de la ressource. La valeur est un horodateur. |
| _self | Cette propriété est générée par le système. Il s'agit de l'URI adressable unique pour la ressource. |
| _Etag | Il s’agit d’une propriété générée par le système qui spécifie l’etag de ressources requis pour le contrôle d’accès concurrentiel optimiste. |
| _Pièces jointes | Il s'agit d'une propriété générée par le système qui spécifie le chemin d'accès adressable pour la ressource de pièces jointes. |
{
"_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
}
Exemple
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/"
}