Créer une collection
L’opération Create Collection crée une collection dans une base de données.
Notes
Ces articles de référence sur les API montrent comment créer des ressources à l’aide de l’API de plan de données Azure Cosmos DB. Avec l’API de plan de données, vous pouvez configurer des options de base telles que la stratégie d’indexation et les clés de partition, comme vous le pouvez avec les SDK Cosmos DB. Si vous avez besoin d’une prise en charge complète des fonctionnalités pour toutes les ressources Azure Cosmos DB, nous vous recommandons d’utiliser le fournisseur de ressources Cosmos DB.
Requête
| Méthode | URI de demande | Description |
|---|---|---|
| POST | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls | Le {databaseaccount} est le nom du compte Azure Cosmos DB créé sous votre abonnement. {db-id} peut être l’ID ou la valeur _rid de la base de données. |
En-têtes
Consultez En-têtes de requête REST Azure Cosmos DB courants pour les en-têtes utilisés par toutes les requêtes Azure Cosmos DB.
Lors de la construction de la signature hachée pour le jeton de clé master, le ResourceType doit être « colls ». ResourceId doit être dbs/{db-id}, où {db-id} peut être l’ID ou la valeur _rid de la base de données.
| Propriété | Obligatoire | Type | Description |
|---|---|---|---|
| x-ms-offer-throughput | Facultatif | Number | L’utilisateur a spécifié un débit manuel (RU/s) pour la collection exprimée en unités de 100 unités de requête par seconde. Le minimum est de 400 à 1 000 000 (ou plus en demandant une augmentation de la limite). Un seul de x-ms-offer-throughput ou x-ms-cosmos-offer-autopilot-settings doit être spécifié. Ces en-têtes ne peuvent pas être spécifiés ensemble. |
| x-ms-cosmos-offer-autopilot-settings | Facultatif | JSON | L’utilisateur a spécifié la mise à l’échelle automatique max RU/s. La valeur est un JSON avec la propriété maxThroughput. Par exemple : {"maxThroughput": 4000}.Un seul de x-ms-offer-throughput ou x-ms-cosmos-offer-autopilot-settings doit être spécifié. Ces en-têtes ne peuvent pas être spécifiés ensemble. Lorsque la mise à l’échelle automatique est utilisée, une définition partitionKey est requise. |
| x-ms-offer-type | Facultatif | String | Il s’agit d’un en-tête hérité pour les niveaux de performances prédéfinis S1, S2 et S3 qui ont été supprimés. Il est recommandé d’utiliser le débit manuel ou de mise à l’échelle automatique, comme décrit ci-dessus. |
body
| Propriété | Obligatoire | Type | Description |
|---|---|---|---|
| id | Obligatoire | String | Nom unique généré par l’utilisateur pour la collection. Deux collections ne peuvent pas avoir les mêmes ID. Il s’agit d’une chaîne qui ne doit pas comporter plus de 255 caractères. |
| indexingPolicy | Facultatif | Object | Cette valeur est utilisée pour configurer la stratégie d'indexation. Par défaut, l'indexation est automatique pour tous les chemins d'accès de documents dans la collection. |
| partitionKey | Obligatoire | Object | Cette valeur est utilisée pour configurer la clé de partition à utiliser pour le partitionnement des données en plusieurs partitions. Pour utiliser une clé de partition volumineuse, spécifiez la version 2 dans la propriété partitionKey. Si la version de l’API REST est 2018-12-31 ou ultérieure, la collection doit inclure une définition partitionKey . Dans les versions antérieures à 2018-12-31, une collection héritée non partitionnée avec un débit manuel peut être créée en omettant la définition partitionKey et en veillant à ce que le débit se situe entre 400 et 10 000 RU/s. Pour optimiser les performances et la scalabilité, il est recommandé de toujours définir une clé de partition. Découvrez comment choisir une bonne clé de partition. |
Exemple de charge utile du corps
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}
response
Create Collection retourne la collection créée sous la forme d’un corps de réponse.
En-têtes
Consultez En-têtes de réponse REST Azure Cosmos DB courants pour les en-têtes retournés par toutes les réponses Azure Cosmos DB.
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 |
|---|---|
| 201 Créé | L'opération a réussi. |
| 400 Demande incorrecte | Le corps au format JSON n'est pas valide. Vérifiez qu'il ne manque pas d'accolades ou de guillemets. |
| 409 Conflit | L’ID fourni pour la nouvelle collection a été pris par une collection existante. |
| 404 avec un code de sous-status de 1013 | L’opération de création de collection est toujours en cours. |
Si vous rencontrez une exception de délai d’expiration lors de la création d’une collection, exécutez une opération de lecture pour vérifier si la collection a été créée avec succès. L’opération de lecture lève une exception jusqu’à ce que l’opération de création de la collection aboutisse. Si l’opération de lecture lève une exception avec status code 404 et sous-status code 1013, cela signifie que l’opération de création de collection est toujours en cours. Réessayez l’opération de lecture jusqu’à ce que vous obteniez 200 ou 201 codes status, ces codes vous informent que la collection a été créée avec succès.
body
| Propriété | Description |
|---|---|
| id | Il s’agit du nom unique qui identifie la nouvelle collection. |
| _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 dans la ressource d'autorisation. |
| _Ts | Il s’agit d’une propriété 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 | Il s’agit d’une propriété 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 représente l’etag de ressources requis pour le contrôle d’accès concurrentiel optimiste. |
| _Doc | Il s’agit d’une propriété générée par le système qui spécifie le chemin d’accès adressable de la ressource documents. |
| _sprocs | Il s’agit d’une propriété générée par le système qui spécifie le chemin d’accès adressable de la ressource de procédures stockées (sprocs). |
| _Déclenche | Il s’agit d’une propriété générée par le système qui spécifie le chemin d’accès adressable de la ressource déclencheurs. |
| _Udf | Il s’agit d’une propriété générée par le système qui spécifie le chemin d’accès adressable de la ressource de fonctions définies par l’utilisateur (udfs). |
| _Conflits | Il s’agit d’une propriété générée par le système qui spécifie le chemin d’accès adressable de la ressource de conflits. Lors d'une opération sur une ressource au sein d'une collection, si un conflit se produit, les utilisateurs peuvent inspecter les ressources en conflit en exécutant une commande GET sur le chemin d'accès à l'URI des conflits. |
| indexingPolicy | Il s’agit des paramètres de stratégie d’indexation pour la collection. |
| partitionKey | Il s’agit des paramètres de configuration de partitionnement pour la collecte. |
Propriétés sous Chemins inclus
| Propriété | Description |
|---|---|
| path | Chemin auquel le comportement d’indexation s’applique. Les chemins d’index commencent par la racine (/) et se terminent généralement par l’opérateur générique de point d’interrogation (?), indiquant qu’il existe plusieurs valeurs possibles pour le préfixe. Par exemple, pour traiter SELECT * FROM Families F WHERE F.familyName = "Andersen", vous devez inclure un chemin d’index pour /familyName/? dans la stratégie d’index de la collection. Les chemins d’index peuvent aussi utiliser l’opérateur générique * pour spécifier le comportement des chemins de manière récursive sous le préfixe. Par exemple, /payload/* permet d’exclure de l’indexation tout ce qui figure sous la propriété « payload ». |
| dataType | Il s’agit du type de données auquel le comportement d’indexation est appliqué. Il peut s’agir de String, Number, Point, Polygon ou LineString. Les valeurs booléennes et null sont automatiquement indexées |
| kind | Type de l'index. Les index de hachage sont utiles pour les comparaisons d’égalité, tandis que les index range sont utiles pour l’égalité, les comparaisons de plages et le tri. Les index spatiaux sont utiles pour les requêtes spatiales. |
| precision | Précision de l’index. Peut être défini sur -1 pour une précision maximale ou entre 1 et 8 pour Nombre et 1-100 pour String. Non applicable aux types de données Point, Polygon etLineString . |
Propriétés sous Chemins d’accès exclus
| Propriété | Description |
|---|---|
| path | Chemin d’accès exclu de l’indexation. Les chemins d’index commencent par la racine (/) et se terminent généralement par l’opérateur générique * . Par exemple, /payload/* permet d’exclure de l’indexation tout ce qui figure sous la propriété « payload ». |
Propriétés sous Clé de partition
| Propriété | Description |
|---|---|
| chemin d’accès | Tableau de chemins d’accès à l’aide desquels les données de la collection peuvent être partitionnée. Les chemins ne doivent pas contenir de caractère générique ou de barre oblique de fin. Par exemple, la propriété JSON « AccountNumber » est spécifiée sous la forme « /AccountNumber ». Le tableau ne doit contenir qu’une seule valeur. |
| kind | Algorithme utilisé pour le partitionnement. Seul le hachage est pris en charge. |
| version | Champ facultatif, s’il n’est pas spécifié, la valeur par défaut est 1. Pour utiliser la clé de partition volumineuse, définissez la version sur 2. Pour en savoir plus sur les clés de partition volumineuses, consultez l’article création de collections avec une clé de partition volumineuse . |
Exemple de corps de réponse
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"kind": "Range",
"dataType": "String",
"precision": -1
},
{
"kind": "Range",
"dataType": "Number",
"precision": -1
}
]
}
],
"excludedPaths": []
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
},
"_rid": "PD5DALigDgw=",
"_ts": 1459200611,
"_self": "dbs/PD5DAA==/colls/PD5DALigDgw=/",
"_etag": "\"00005900-0000-0000-0000-56f9a2630000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
Exemple 1
L’exemple suivant crée une collection avec un débit manuel de 400 RU/s.
x-ms-offer-throughput l’en-tête est utilisé pour définir la valeur de débit (RU/s). Il accepte un nombre avec une valeur minimale de 400 qui incrémente par unités de 100.
POST https://querydemo.documents.azure.com/dbs/testdb/colls HTTP/1.1
x-ms-offer-throughput: 400
x-ms.date: 04/20/2021
authorization: type%3dmaster%26ver%3d1.0%26sig%3dpDOKhfllik0BJijp5apzqHL%2bjtoFhsvdhAGE5F8%2bOiE%3d
Cache-Control: no-cache
User-Agent: contoso/1.0
x-ms-version: 2015-12-16
Accept: application/json
Host: querydemo.documents.azure.com
Content-Length: 235
Expect: 100-continue
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}
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: Mon, 28 Mar 2016 20:00:12.142 GMT
etag: "00005900-0000-0000-0000-56f9a2630000"
collection-partition-index: 0
collection-service-index: 24
x-ms-schemaversion: 1.1
x-ms-alt-content-path: dbs/testdb
x-ms-quorum-acked-lsn: 9
x-ms-current-write-quorum: 3
x-ms-current-replica-set-size: 4
x-ms-request-charge: 4.95
x-ms-serviceversion: version=1.6.52.5
x-ms-activity-id: 05d0a3b5-4504-446a-96f4-bef3a3408595
x-ms-session-token: 0:10
Set-Cookie: x-ms-session-token#0=10; Domain=querydemo.documents.azure.com; Path=/dbs/PD5DAA==/colls/PD5DALigDgw=
Set-Cookie: x-ms-session-token=10; Domain=querydemo.documents.azure.com; Path=/dbs/PD5DAA==/colls/PD5DALigDgw=
x-ms-gatewayversion: version=1.6.52.5
Date: Mon, 28 Mar 2016 21:30:12 GMT
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"kind": "Range",
"dataType": "String",
"precision": -1
},
{
"kind": "Range",
"dataType": "Number",
"precision": -1
}
]
}
],
"excludedPaths": []
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash"
},
"_rid": "PD5DALigDgw=",
"_ts": 1459200611,
"_self": "dbs/PD5DAA==/colls/PD5DALigDgw=/",
"_etag": "\"00005900-0000-0000-0000-56f9a2630000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
Exemple 2
L’exemple suivant crée une collection avec un débit maximal de mise à l’échelle automatique de 4 000 RU/s (elle est mise à l’échelle entre 400 et 4 000 RU/s).
x-ms-cosmos-offer-autopilot-settings l’en-tête est utilisé pour définir la maxThroughput valeur, qui est la valeur maximale ru/s de mise à l’échelle automatique. Il accepte un nombre avec un minimum de 4 000 qui incrémente par unités de 1000. Lorsque la mise à l’échelle automatique est utilisée, une définition de clé de partition est requise, comme illustré dans l’exemple suivant :
Notes
Pour activer la mise à l’échelle automatique sur une base de données ou une collection existante, ou passer de la mise à l’échelle automatique au débit manuel, consultez l’article Remplacer une offre.
POST https://querydemo.documents.azure.com/dbs/testdb/colls HTTP/1.1
x-ms-cosmos-offer-autopilot-settings: {"maxThroughput": 4000}
x-ms-date: Wed, 22 Jul 2020 22:17:39 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3dpDOKhfllik0BJijp5apzqHL%2bjtoFhsvdhAGE5F8%2bOiE%3d
Cache-Control: no-cache
User-Agent: contoso/1.0
x-ms-version: 2018-12-31
Accept: application/json
Host: querydemo.documents.azure.com
Content-Length: 235
Expect: 100-continue
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}