Interrogation de ressources Azure Cosmos DB à l’aide de l’API REST

Azure Cosmos DB est une base de données multimodèle distribuée à l’échelle mondiale avec prise en charge de plusieurs API. Cet article explique comment utiliser REST pour interroger des ressources à l’aide de l’API SQL.

Comment interroger une ressource à l'aide de REST ?

Pour exécuter une requête SQL sur une ressource, procédez comme suit :

• Exécutez une POST méthode sur un chemin d’accès de ressource à l’aide de JSON avec la query propriété définie sur la chaîne de requête SQL et la propriété « parameters » définie sur le tableau de valeurs de paramètre facultatives.
• Attribuez à l’en-tête x-ms-documentdb-isquery la valeur True.
• Attribuez à l’en-tête Content-Type la valeur application/query+json.

Pour obtenir un exemple montrant comment effectuer une requête SQL sur une ressource à l’aide de .NET, consultez EXEMPLE REST à partir de .NET.

Exemple

Vous trouverez ci-dessous un exemple d'opération de requête REST sur des ressources de document. Dans cet exemple, nous souhaitons rechercher tous les documents dont « Don » est l'auteur.

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": []  
}  
  

Détails de la demande

Méthode	URI de demande
POST	Requis. Type d'authentification et jeton de signature. Seul le jeton de clé principale est autorisé pour cette opération. Pour plus d’informations, consultez Access Control sur les ressources Cosmos DB.

En-têtes de requête

Le tableau suivant contient les en-têtes courants utilisés pour effectuer des opérations de requête.

En-tête standard	Description
Autorisation	Requis. Type d'authentification et jeton de signature. Seul le jeton de clé principale est autorisé pour cette opération. Pour plus d’informations, consultez Access Control sur les ressources Cosmos DB.
Content-Type	Requis. Doit être défini sur application/query+json.
Accepter	Facultatif. Pour le moment, Cosmos DB retourne toujours la charge utile de réponse au format JSON standard. Le client doit pouvoir accepter le corps de la réponse au format JSON standard.
User-Agent	Facultatif. Agent utilisateur effectuant la demande. Le format recommandé est {nom de l'agent utilisateur}/{version}. Par exemple, le Kit de développement logiciel (SDK) .NET de l’API SQL définit la chaîne User-Agent sur Microsoft.Document.Client/1.0.0.0.

En-tête personnalisé	Description
x-ms-date	Requis. Date de la demande, comme spécifié dans RFC 1123. Le format de date est exprimé en temps universel coordonné (UTC), par exemple. Vendredi 08 avril 2015 03:52:31 GMT.
x-ms-documentdb-isquery	Requis. Cette propriété doit être définie sur true.
x-ms-max-item-count	Facultatif. Pour parcourir un jeu de résultats, définissez cet en-tête sur le nombre maximal d'éléments à renvoyer dans une seule page.
x-ms-continuation	Facultatif. Pour accéder à la page suivante d'éléments, définissez cet en-tête sur le jeton de liaison de la page suivante.
x-ms-version	Facultatif. Version du service REST Cosmos DB. La dernière version est utilisée quand l'en-tête n'est pas fourni. Pour plus d’informations, consultez Informations de référence sur l’API REST Azure Cosmos DB.
x-ms-documentdb-query-enable-scan	Facultatif. Utiliser une analyse d'index pour traiter la requête si le chemin d'accès d'index approprié du type n'est pas disponible.
x-ms-session-token	Facultatif. Jeton de session pour la demande. Utilisé pour la cohérence de la session.
x-ms-partition-key	Facultatif. Si elle est spécifiée, la requête est exécutée uniquement sur les documents qui correspondent à la valeur de clé de partition dans l’en-tête.
x-ms-documentdb-query-enablecrosspartition	Facultatif. Doit avoir la valeur true pour toutes les requêtes qui ne filtrent pas sur une clé de partition unique. Les requêtes qui filtrent par rapport à une seule valeur de clé de partition sont exécutées sur une seule partition, même si cette valeur est définie sur true.
x-ms-documentdb-populatequerymetrics	Facultatif. Doit être défini sur True pour retourner des métriques de requête

Corps de la requête

Le corps de la demande doit être un document JSON valide contenant la requête SQL et les paramètres. Si l'entrée est mal formée ou si la syntaxe SQL est incorrecte, l'opération échoue en renvoyant une erreur 400 Demande incorrecte.

Vous obtiendrez également une requête incorrecte 400 si une requête ne peut pas être traitée par la passerelle.

Propriété	Description
query	Requis. Chaîne de requête SQL de la requête. Pour plus d’informations, consultez Informations de référence sur la syntaxe SQL Azure Cosmos DB.
parameters	Requis. Tableau JSON de paramètres, spécifié sous la forme de paires nom-valeur. Le tableau de paramètres peut contenir de zéro à plusieurs paramètres. Chaque paramètre doit avoir les valeurs suivantes :name : le nom du paramètre. Les noms de paramètres doivent être des littéraux de chaîne valides et commencer par « @ ». value : valeur du paramètre. Peut être toute valeur JSON valide (string, number, object, array, Boolean ou null).

Exemple de demande

L’exemple suivant crée une requête SQL paramétrable avec un paramètre de chaîne pour @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"}  
    ]  
}  

Pour plus d’informations sur les requêtes SQL, consultez Requêtes SQL pour Azure Cosmos DB.

Détails de la réponse

Voici les codes d'état courants renvoyés par cette opération. Pour plus d’informations sur les codes d’erreur status, consultez Codes d’état HTTP pour Azure Cosmos DB.

Code	Description
200 OK	L'opération a réussi.
400 Demande incorrecte	La syntaxe de l'instruction SQL est incorrecte.
401 Non autorisé	Soit l'en-tête Authorization, soit l'en-tête x-ms-date n'est pas défini. 401 est également renvoyé quand la valeur définie pour l'en-tête Autorization est un jeton d'autorisation non valide.
403 Interdit	Le jeton d'autorisation a expiré.
404 Introuvable	La collection n'est plus une ressource. Par exemple, la ressource a peut-être été supprimée.

En-têtes de réponse

Cette opération renvoie les en-têtes courants suivants. Des en-têtes standard et courants supplémentaires peuvent être renvoyés.

En-tête standard	Description
Content-Type	La valeur Content-Type est application/json. Cosmos DB retourne toujours le corps de la réponse au format JSON standard.
Date	Date/heure de l'opération de réponse. Ce format date/heure est conforme au format date/heure [RFC1123] exprimé en temps universel coordonné (UTC).

En-tête personnalisé	Description
x-ms-item-count	Nombre d'éléments renvoyés par l'opération.
x-ms-continuation	Il s’agit d’une chaîne opaque retournée lorsque la requête a potentiellement plus d’éléments à récupérer. L'en-tête x-ms-continuation peut être inclus dans des demandes suivantes, en tant qu'en-tête de demande pour reprendre l'exécution de la requête.
x-ms-request-charge	Il s’agit du nombre d’unités de requête (RU) consommées par l’opération. Pour plus d’informations sur les unités de requête, consultez Unités de requête dans Azure Cosmos DB.
x-ms-activity-id	Il s’agit d’un identificateur unique pour l’opération. Il peut être utilisé pour le suivi de l’exécution des requêtes Cosmos DB.
x-ms-session-token	Jeton de session à utiliser pour les demandes suivantes. Utilisé pour la cohérence de la session.

Corps de la réponse

Le corps de la réponse correspondant à l'opération de requête se compose de l'ID de ressource _rid de la ressource parent de la ressource en cours d'interrogation et du tableau des ressources contenant les propriétés de ressource pour la projection et la sélection. Selon l'exemple, si une requête a été effectuée sur le chemin d'accès docs de la collection avec un ID de ressource _rid XP0mAJ3H-AA=, la réponse se présente comme suit :

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

Propriété	Description
_rid	ID de ressource pour la collection utilisée dans la requête.
_Compter	Nombre d'éléments renvoyés.
Tableau de ressources	Tableau contenant les résultats de la requête.

Génération du corps de la demande de requête

La demande de requête doit être un document JSON valide comprenant une propriété query contenant une chaîne de requête SQL valide, et une propriété parameters contenant un tableau de paramètres facultatifs. Chaque paramètre doit avoir des propriétés name et value spécifiées dans la requête. Les noms de paramètres doivent commencer par le caractère « @ ». Les valeurs peuvent être toute valeur JSON valide : chaîne, entier, valeur booléenne et valeur NULL.

Il est valide de spécifier uniquement un sous-ensemble de paramètres spécifiés dans le texte de la requête . Les expressions qui font référence à ces paramètres non spécifiés sont évaluées comme undefined. Il est également correct de spécifier des paramètres supplémentaires qui ne sont pas utilisés dans le texte de query.

Voici quelques exemples de demandes de requête valides. Par exemple, la requête suivante a un seul paramètre @id.

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

L'exemple suivant comprend deux paramètres, l'un avec une valeur de chaîne et l'autre avec une valeur entière.

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

L'exemple suivant utilise des paramètres dans la clause SELECT, ainsi qu'une propriété accessible via le nom du paramètre en tant que paramètre.

{  
    "query": "select @id, d[@propName] from docs d",   
    "parameters": [   
        {"@id": "newdoc"},  
        {"@propName": "prop"}  
     ]  
}  

Requêtes qui ne peuvent pas être traitées par la passerelle

Toute requête qui nécessite un état entre les continuations ne peut pas être traitée par la passerelle. notamment :

• Haut de la page
• ORDER BY
• OFFSET LIMIT
• Agrégats
• DISTINCT
• GROUP BY

Les requêtes qui peuvent être traitées par la passerelle sont les suivantes :

• Projections simples
• Filtres

Lorsqu’une réponse est retournée pour une requête qui ne peut pas être traitée par la passerelle, elle contient le code status 400 (BadRequest) et le message suivant :

{"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}]}"}

Pagination des résultats de requête

Les demandes de requête prennent en charge la pagination via les en-têtes x-ms-max-item-count et x-ms-continuation request. L'en-tête x-ms-max-item-count spécifie le nombre maximal de valeurs qui peuvent être renvoyées par l'exécution de la requête. Ce nombre peut être compris entre 1 et 1 000 (inclus), et sa valeur par défaut est 100.

Les requêtes renvoient de zéro aux valeurs x-ms-max-item-count maximales spécifiées à partir des résultats de l'exécution. Le résultat de la requête inclut un en-tête x-ms-item-count qui spécifie le nombre réel de documents renvoyés par la requête. Si des résultats supplémentaires peuvent être récupérés à partir de la requête, la réponse inclut une valeur non vide pour l'en-tête x-ms-continuation.

Les clients peuvent extraire les pages de résultats suivantes en répercutant l'en-tête x-ms-continuation en tant qu'autre demande. Pour lire tous les résultats, les clients doivent répéter ce processus jusqu'à ce qu'un en-tête x-ms-continuation vide soit renvoyé.

Les exécutions de requêtes Cosmos DB sont sans état côté serveur et peuvent être reprises à tout moment à l’aide de l’en-tête x-ms-continuation . La valeur x-ms-continuation utilise le dernier ID de ressource de document traité (_rid) pour suivre la progression de l'exécution. Par conséquent, si des documents sont supprimés et réinscrits entre l’extraction des pages, les documents peuvent potentiellement être exclus de n’importe quel lot de requête. Toutefois, le comportement et le format de l'en-tête x-ms-continuation pourront changer dans une mise à jour future du service.

Voir aussi

• Azure Cosmos DB
• API SQL Azure Cosmos DB
• Kits SDK de l’API SQL Azure Cosmos DB
• EXEMPLE REST à partir de .NET