En-têtes de requête REST Azure Cosmos DB courants
Les en-têtes de requête suivants sont communs à toutes les tâches que vous pouvez effectuer avec l’API SQL :
| En-tête | Obligatoire | Type | Description |
|---|---|---|---|
| Autorisation | Obligatoire | String | Jeton d’autorisation pour la demande. Pour plus d’informations sur la génération d’un jeton d’autorisation valide, consultez Access Control sur les ressources Cosmos DB |
| Content-Type | Obligatoire (sur PUT, PATCH et POST) | String | Pour POST sur les opérations de requête, il doit s’agir d’application/query+json. Pour les opérations PATCH, il doit s’agir d’application/json_patch+json. Pour les pièces jointes, doit être défini sur le type Mime de la pièce jointe. Pour plus d’informations sur les types MIME, consultez Créer une pièce jointe. Pour toutes les autres tâches, doit être application/json. |
| If-Match | Facultatif (applicable uniquement sur PUT et DELETE) | String | Utilisé pour rendre l’opération conditionnelle pour l’accès concurrentiel optimiste. La valeur doit être la valeur etag de la ressource. |
| If-None-Match | Facultatif (applicable uniquement sur GET) | String | Rend l’opération conditionnelle pour s’exécuter uniquement si la ressource a changé. La valeur doit être l’etag de la ressource. |
| If-Modified-Since | Facultatif (applicable uniquement sur GET) | Date | Retourne l’etag de la ressource modifiée après la date spécifiée au format RFC 1123. Ignoré lorsque If-None-Match est spécifié |
| User-Agent | Facultatif | String | Chaîne qui spécifie l’agent utilisateur client effectuant la demande. Le format recommandé est {nom de l'agent utilisateur}/{version}. Par exemple, le SDK .NET de l’API SQL officielle définit la chaîne User-Agent sur Microsoft.Document.Client/1.0.0.0. Un agent utilisateur personnalisé peut être quelque chose comme ContosoMarketingApp/1.0.0. |
| x-ms-activity-id | Facultatif | String | Un identificateur fourni par le client pour l’opération, qui est repris dans la réponse du serveur. La valeur recommandée est un identificateur unique. |
| x-ms-consistency-level | Facultatif | String | Remplacement du niveau de cohérence pour les options de lecture par rapport aux documents et aux pièces jointes. 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-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-date | Obligatoire | Date | Date de la demande par format de date RFC 1123 exprimée en temps universel coordonné, par exemple, le vendredi 08 avril 2015 03:52:31 GMT. |
| x-ms-max-item-count | Facultatif | Number | Entier indiquant le nombre maximal d’éléments à retourner par page. 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-documentdb-partitionkey | Facultatif | Array | Valeur de clé de partition pour l’opération de document ou de pièce jointe demandée. Obligatoire pour les opérations sur des documents et des pièces jointes lorsque la définition de collection inclut une définition de clé de partition. Cette valeur est utilisée pour étendre votre requête à des documents qui correspondent aux critères de clé de partition. Par conception, il s’agit d’une requête de partition unique. Pris en charge dans les versions d’API 2015-12-16 et ultérieures. Actuellement, l’API SQL prend en charge une clé de partition unique. Il s’agit donc d’un tableau contenant une seule valeur. |
| x-ms-documentdb-query-enablecrosspartition | Facultatif | Booléen | Lorsque cet en-tête a la valeur true et que votre requête n’a pas de clé de partition, Azure Cosmos DB diffuse la requête sur plusieurs partitions. L’exécution est réalisée en envoyant des requêtes à toutes les partitions. Pour lire les résultats des requêtes, les applications clientes doivent consommer les résultats à partir de FeedResponse et vérifier la propriété ContinuationToken. Pour lire tous les résultats, poursuivez l’itération des données jusqu’à ce que la valeur de ContinuationToken soit null. |
| x-ms-session-token | Obligatoire (pour la cohérence de session uniquement) | String | Jeton de chaîne utilisé avec la cohérence au niveau de la session. Pour plus d'informations, consultez la rubrique Utilisation des niveaux de cohérence dans Cosmos DB |
| x-ms-version | Obligatoire | String | Version du service REST Cosmos DB. Pour obtenir la liste des versions d’API prises en charge, consultez Référence de l’API REST Azure Cosmos DB |
| A-IM | Facultatif | String | Indique une demande de flux de modification . Doit être défini sur « Flux incrémentiel » ou omis dans le cas contraire. |
| x-ms-documentdb-partitionkeyrangeid | Facultatif | Number | Utilisé dans les demandes de flux de modification . ID de la plage de clés de partition pour la lecture des données. |
| x-ms-cosmos-allow-tentative-writes | Facultatif | Booléen | Lorsque cet en-tête est défini sur true pour les comptes Azure Cosmos configurés avec plusieurs emplacements d’écriture, Azure Cosmos DB autorise les écritures dans tous les emplacements. Les demandes d’écriture dont la valeur de cet en-tête est définie sur false (ou si l’en-tête est absent) échouent avec le code d’état de la réponse 403 avec le message d’erreur « Les écritures ne sont pas autorisées dans la région ». |
Voir aussi