Remplacer une collection
Remplacer la collection prend en charge la modification de la stratégie d’indexation d’une collection après sa création. La modification d’autres propriétés d’une collection comme l’ID ou la clé de partition n’est pas prise en charge.
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 |
|---|---|---|
| PUT | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id} | Le {databaseaccount} est le nom du compte Azure Cosmos DB créé sous 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 à remplacer. |
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 Cosmos DB.
body
| Propriété | Obligatoire | Type | Description |
|---|---|---|---|
| id | Obligatoire | String | L'utilisateur a généré un nom unique 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 les index sur les éléments de la collection. Par défaut, la stratégie d’indexation est définie sur automatique pour tous les chemins de document au sein de la collection. |
| partitionKey | Obligatoire | Object | Cette valeur définit la clé de partition utilisée pour le partitionnement des données. 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. |
Notes
Quand vous définissez des chemins d’index personnalisé, vous devez spécifier la règle d’indexation par défaut pour la totalité de l’arborescence du document, désignée par le chemin spécial « /* ».
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "Number",
"precision": -1,
"kind": "Range"
},
{
"dataType": "String",
"precision": 3,
"kind": "Hash"
}
]
}
],
"excludedPaths": []
},
"_rid": "XrdaAKx3Hgw=",
"_ts": 1459203135,
"_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",
"_etag": "\"00006c00-0000-0000-0000-56f9ac3f0000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
response
Replace Collection retourne la collection mise à jour sous forme de 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 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 | Description |
|---|---|
| 201 OK | L’opération PUT 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. |
body
| Propriété | Description |
|---|---|
| id | Il s’agit du nom unique qui identifie la nouvelle collection. |
| _rid | 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). |
| _triggers | 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. |
| _udfs | 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). |
| _conflicts | 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. Le chemin des index commence par la racine et se termine généralement par l’opérateur générique ?, ce qui signifie qu’il y a 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. |
| précision | Précision de l’index. Peut être défini sur -1 pour la précision maximale ou entre 1 et 8 pour Nombre et 1-100 pour String. Non applicable aux types de données Point, Polygon et LineString . |
Propriétés sous Chemins 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 ». |
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"kind": "Range",
"dataType": "Number",
"precision": -1
},
{
"kind": "Hash",
"dataType": "String",
"precision": 3
}
]
}
],
"excludedPaths": []
},
"_rid": "XrdaAKx3Hgw=",
"_ts": 1459203136,
"_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",
"_etag": "\"00006e00-0000-0000-0000-56f9ac400000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
Exemple
PUT https://querydemo.documents.azure.com/dbs/XrdaAA==/colls/XrdaAKx3Hgw= HTTP/1.1
x-ms.date: 04/20/2021
authorization: type%3dmaster%26ver%3d1.0%26sig%3dZY2s2H1TuPFKk1H2od5qVLbn57vjI9rKz0CMXKOk3GA%3d
Cache-Control: no-cache
User-Agent: Microsoft.Azure.Documents.Client/1.6.0.0
x-ms-version: 2015-12-16
Accept: application/json
Host: querydemo.documents.azure.com
Content-Length: 475
Expect: 100-continue
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "Number",
"precision": -1,
"kind": "Range"
},
{
"dataType": "String",
"precision": 3,
"kind": "Hash"
}
]
}
],
"excludedPaths": []
},
"_rid": "XrdaAKx3Hgw=",
"_ts": 1459203135,
"_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",
"_etag": "\"00006c00-0000-0000-0000-56f9ac3f0000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
HTTP/1.1 200 Ok
Cache-Control: no-store, no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Content-Location: https://querydemo.documents.azure.com/dbs/XrdaAA==/colls/XrdaAKx3Hgw=
Server: Microsoft-HTTPAPI/2.0
Strict-Transport-Security: max-age=31536000
x-ms-last-state-change-utc: Fri, 25 Mar 2016 22:54:09.213 GMT
etag: "00006e00-0000-0000-0000-56f9ac400000"
x-ms-resource-quota: collections=5000;
x-ms-resource-usage: collections=28;
collection-partition-index: 0
collection-service-index: 0
x-ms-schemaversion: 1.1
x-ms-alt-content-path: dbs/testdb
x-ms-quorum-acked-lsn: 7902
x-ms-current-write-quorum: 3
x-ms-current-replica-set-size: 4
x-ms-request-charge: 9.9
x-ms-serviceversion: version=1.6.52.5
x-ms-activity-id: 6050a48c-828d-4016-b73b-5e0ce2ad6271
x-ms-session-token: M:7903
Set-Cookie: x-ms-session-token#M=7903; Domain=querydemo.documents.azure.com; Path=/dbs/XrdaAA==/colls/XrdaAKx3Hgw=
Set-Cookie: x-ms-session-token=7903; Domain=querydemo.documents.azure.com; Path=/dbs/XrdaAA==/colls/XrdaAKx3Hgw=
x-ms-gatewayversion: version=1.6.52.5
Date: Mon, 28 Mar 2016 22:12:15 GMT
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"kind": "Range",
"dataType": "Number",
"precision": -1
},
{
"kind": "Hash",
"dataType": "String",
"precision": 3
}
]
}
],
"excludedPaths": []
},
"_rid": "XrdaAKx3Hgw=",
"_ts": 1459203136,
"_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",
"_etag": "\"00006e00-0000-0000-0000-56f9ac400000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}