Sostituire una raccolta
Replace Collection supporta la modifica dei criteri di indicizzazione di una raccolta dopo la creazione. La modifica di altre proprietà di una raccolta, ad esempio l'ID o la chiave di partizione, non sono supportate.
Nota
Questi articoli di riferimento sulle API illustrano come creare risorse usando l'API del piano dati di Azure Cosmos DB. Con l'API del piano dati è possibile configurare opzioni di base, ad esempio criteri di indicizzazione, chiavi di partizione molto simili a quelle che è possibile usare con gli SDK di Cosmos DB. Se è necessario il supporto completo delle funzionalità per tutte le risorse di Azure Cosmos DB, è consigliabile usare il provider di risorse Cosmos DB.
Richiesta
| Metodo | URI richiesta | Descrizione |
|---|---|---|
| PUT | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id} | {databaseaccount} è il nome dell'account Azure Cosmos DB creato nella sottoscrizione. Il valore {db-id} è il nome/ID generato dall'utente del database, non l'ID generato dal sistema (rid). Il valore {coll-id} è il nome della raccolta da sostituire. |
Intestazioni
Vedere Intestazioni di richiesta REST comuni di Azure Cosmos DB per le intestazioni usate da tutte le richieste di Cosmos DB.
Corpo
| Proprietà | Obbligatoria | Tipo | Descrizione |
|---|---|---|---|
| id | Necessario | string | L'utente ha generato un nome univoco per la raccolta. Due raccolte non possono avere gli stessi ID. Si tratta di una stringa che non deve contenere più di 255 caratteri. |
| indexingPolicy | Facoltativo | Oggetto | Questo valore viene usato per configurare gli indici sugli elementi della raccolta. Per impostazione predefinita, i criteri di indicizzazione sono impostati su automatico per tutti i percorsi dei documenti all'interno della raccolta. |
| partitionKey | Necessario | Oggetto | Questo valore imposta la chiave di partizione usata per il partizionamento dei dati. Per usare una chiave di partizione di grandi dimensioni, specificare la versione 2 all'interno della proprietà partitionKey. Se la versione dell'API REST è 2018-12-31 o successiva, la raccolta deve includere una definizione partitionKey . Nelle versioni precedenti al 2018-12-31 è possibile creare una raccolta legacy non partizionata con velocità effettiva manuale omettendo la definizione partitionKey e assicurando che la velocità effettiva sia compresa tra 400 e 10.000 UR/sec. Per ottenere prestazioni e scalabilità ottimali, è consigliabile impostare sempre una chiave di partizione. Informazioni su come scegliere una chiave di partizione valida. |
Nota
Quando si impostano percorsi di indice personalizzati, è necessario specificare la regola di indicizzazione predefinita per l'intero albero del documento, indicato dal percorso speciale "/*".
{
"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/"
}
Risposta
Replace Collection restituisce la raccolta aggiornata come corpo della risposta.
Intestazioni
Vedere Intestazioni di risposta REST comuni di Azure Cosmos DB per le intestazioni restituite da tutte le risposte di Cosmos DB.
Codici di stato
La seguente tabella elenca i codici di stato comuni restituiti da questa operazione. Per un elenco completo dei codici di stato, vedere Codici di stato HTTP.
| Codice | Descrizione |
|---|---|
| 201 OK | L'operazione PUT ha avuto esito positivo. |
| 400 - Richiesta non valida | Il corpo JSON non è valido. Controllare parentesi graffe o virgolette mancanti. |
Corpo
| Proprietà | Descrizione |
|---|---|
| id | È il nome univoco che identifica la nuova raccolta. |
| _rid | Si tratta di una proprietà generata dal sistema. L'ID risorsa (_rid) è un identificatore univoco e anche gerarchico per ogni stack di risorse nel modello di risorsa. Viene usato internamente per il posizionamento e l'esplorazione della risorsa di autorizzazione. |
| _ts | Si tratta di una proprietà generata dal sistema. Indica il timestamp dell'ultimo aggiornamento della risorsa. Il valore è un timestamp. |
| _self | Si tratta di una proprietà generata dal sistema. URI indirizzabile univoco per la risorsa. |
| _etag | Si tratta di una proprietà generata dal sistema che rappresenta l'etag della risorsa necessaria per il controllo della concorrenza ottimistica. |
| _doc | Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa documenti. |
| _sprocs | Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa stored procedure (sprocs). |
| _triggers | Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa triggers. |
| _udfs | Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa funzioni definite dall'utente (udfs). |
| _conflicts | Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa conflitti. Se durante un'operazione su una risorsa all'interno di una raccolta si verifica un conflitto, gli utenti possono controllare le risorse in conflitto eseguendo un'operazione GET sul percorso URI dei conflitti. |
| indexingPolicy | Si tratta delle impostazioni dei criteri di indicizzazione per la raccolta. |
| partitionKey | Si tratta delle impostazioni di configurazione del partizionamento per la raccolta. |
Proprietà in Percorsi inclusi
| Proprietà | Descrizione |
|---|---|
| path | Percorso a cui si applica il comportamento di indicizzazione. I percorsi di indice iniziano con la radice (/) e terminano in genere con il carattere jolly ?, che indica la possibilità di molteplici valori per il prefisso. Ad esempio, per usare SELECT * FROM Families F WHERE F.familyName = "Andersen", è necessario includere un percorso di indice per /"familyName"/? nei criteri di indicizzazione della raccolta. I percorsi di indice possono anche usare il carattere jolly * per specificare un comportamento ricorsivo dei percorsi al di sotto del prefisso. È ad esempio possibile usare /payload/* per escludere dall'indicizzazione qualsiasi elemento al di sotto della proprietà payload. |
| dataType | È il tipo di dati a cui viene applicato il comportamento di indicizzazione. Può essere String, Number, Point*, Polygon o LineString. I valori booleani e null vengono indicizzati automaticamente |
| kind | Tipo di indice. Gli indici hash sono utili per i confronti di uguaglianza, mentre gli indici Range sono utili per l'uguaglianza, i confronti tra intervalli e l'ordinamento. Gli indici spaziali sono utili per le query spaziali. |
| precisione | Precisione dell'indice. Può essere impostato su -1 per la precisione massima o tra 1-8 per Number e 1-100 per String. Non applicabile per i tipi di dati Point, Polygon e LineString . |
Proprietà in Percorsi esclusi
| Proprietà | Descrizione |
|---|---|
| path | Percorso escluso dall'indicizzazione. I percorsi di indice iniziano con la radice (/) e in genere terminano con l'operatore * con caratteri jolly. È ad esempio possibile usare /payload/* per escludere dall'indicizzazione qualsiasi elemento al di sotto della proprietà 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/"
}
Esempio
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/"
}