Crea raccolta
L'operazione Create Collection crea una nuova raccolta in un database.
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 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 |
|---|---|---|
| POST | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls | {databaseaccount} è il nome dell'account Azure Cosmos DB creato nella sottoscrizione. {db-id} può essere l'ID o il valore _rid per il database. |
Intestazioni
Vedere Intestazioni di richiesta REST di Azure Cosmos DB comuni per le intestazioni usate da tutte le richieste di Azure Cosmos DB.
Quando si costruisce la firma hash per il token della chiave master, ResourceType deve essere "colls". ResourceId deve essere dbs/{db-id}, dove {db-id} può essere l'ID o il valore _rid del database.
| Proprietà | Obbligatoria | Tipo | Descrizione |
|---|---|---|---|
| x-ms-offer-throughput | Facoltativo | Number | L'utente ha specificato la velocità effettiva manuale (UR/s) per la raccolta espressa in unità di 100 unità richiesta al secondo. Il minimo è pari a 400 fino a 1.000.000 (o superiore richiedendo un aumento del limite). È necessario specificare solo uno di x-ms-offer-throughput o x-ms-cosmos-offer-autopilot-settings . Queste intestazioni non possono essere specificate insieme. |
| x-ms-cosmos-offer-autopilot-settings | Facoltativo | JSON | L'utente ha specificato la scalabilità automatica max UR/s. Il valore è json con la proprietà maxThroughput. Ad esempio: {"maxThroughput": 4000}.È necessario specificare solo uno di x-ms-offer-throughput o x-ms-cosmos-offer-autopilot-settings . Queste intestazioni non possono essere specificate insieme. Quando viene usata la scalabilità automatica, è necessaria una definizione partitionKey . |
| x-ms-offer-type | Facoltativo | String | Si tratta di un'intestazione legacy per i livelli di prestazioni predefiniti S1, S2 e S3 ritirati. È consigliabile usare la velocità effettiva manuale o di scalabilità automatica, come descritto in precedenza. |
Corpo
| Proprietà | Obbligatoria | Tipo | Descrizione |
|---|---|---|---|
| id | Necessario | string | Nome univoco generato dall'utente per la raccolta. Nessuna due raccolte può avere gli stessi ID. Si tratta di una stringa che non deve essere superiore a 255 caratteri. |
| indexingPolicy | Facoltativo | Oggetto | Questo valore viene usato per configurare i criteri di indicizzazione. Per impostazione predefinita, l'indicizzazione è automatica per tutti i percorsi di documenti all'interno della raccolta. |
| partitionKey | Necessario | Oggetto | Questo valore viene usato per configurare la chiave di partizione da usare per il partizionamento dei dati in più partizioni. Per usare una chiave di partizione di grandi dimensioni, specificare la versione come 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 una raccolta legacy non partizionata con velocità effettiva manuale può essere creata omettendo la definizione partitionKey e assicurando che la velocità effettiva sia compresa tra 400 - 10.000 UR/s. Per ottenere prestazioni ottimali e scalabilità, è consigliabile impostare sempre una chiave di partizione. Informazioni su come scegliere una chiave di partizione valida. |
Payload del corpo di esempio
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}
Risposta
Create Collection restituisce la raccolta creata come corpo della risposta.
Intestazioni
Vedere Intestazioni di risposta REST di Azure Cosmos DB comuni per le intestazioni restituite da tutte le risposte di Azure 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 di stato HTTP | Descrizione |
|---|---|
| 201 Creato | L'operazione è stata completata. |
| 400 - Richiesta non valida | Il corpo JSON non è valido. Controllare parentesi graffe o virgolette mancanti. |
| 409 - Conflitto | L'ID fornito per la nuova raccolta è stato acquisito da una raccolta esistente. |
| 404 con codice di stato secondario 1013 | L'operazione di creazione della raccolta è ancora in corso. |
Se si verifica un'eccezione di timeout durante la creazione di una raccolta, eseguire un'operazione di lettura per convalidare se la raccolta è stata creata correttamente. L'operazione di lettura genera un'eccezione finché l'operazione di creazione della raccolta non riesce. Se l'operazione di lettura genera un'eccezione con il codice di stato 404 e il codice di stato secondario 1013, significa che l'operazione di creazione della raccolta è ancora in corso. Ripetere l'operazione di lettura fino a ottenere 200 o 201 codici di stato, questi codici consentono di sapere che la raccolta è stata creata correttamente.
Corpo
| Proprietà | Descrizione |
|---|---|
| id | È il nome univoco che identifica la nuova raccolta. |
| _rid | È 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 | È una proprietà generata dal sistema. Indica il timestamp dell'ultimo aggiornamento della risorsa. Il valore è un timestamp. |
| _stesso | È 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 di 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). |
| _Trigger | Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa trigger. |
| _udfs | Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa di funzioni definite dall'utente (udfs). |
| _Conflitti | Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile della risorsa dei 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 in genere terminano con l'operatore jolly punto interrogativo (?), denotando che per il prefisso sono presenti più valori possibili. Ad esempio, per usare SELECT * FROM Families F WHERE F.familyName = "Andersen", è necessario includere un percorso di indice per /"familyName"/? nei criteri di indice 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 booleani e i valori Null vengono indicizzati automaticamente |
| gentile | 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 jolly *. È ad esempio possibile usare /payload/* per escludere dall'indicizzazione qualsiasi elemento al di sotto della proprietà payload. |
Proprietà in Chiave di partizione
| Proprietà | Descrizione |
|---|---|
| Percorsi | Matrice di percorsi che usano i dati all'interno della raccolta possono essere partizionati. I percorsi non devono contenere un carattere jolly o una barra finale. Ad esempio, la proprietà JSON "AccountNumber" viene specificata come "/AccountNumber". La matrice deve contenere solo un singolo valore. |
| gentile | Algoritmo usato per il partizionamento. È supportato solo hash. |
| version | Un campo facoltativo, se non specificato il valore predefinito è 1. Per usare la chiave di partizione di grandi dimensioni, impostare la versione su 2. Per informazioni sulle chiavi di partizione di grandi dimensioni, vedere come creare raccolte con un articolo di chiave di partizione di grandi dimensioni . |
Corpo della risposta di esempio
{
"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/"
}
Esempio 1
Nell'esempio seguente viene creata una raccolta con velocità effettiva manuale di 400 UR/s.
x-ms-offer-throughput intestazione viene usata per impostare il valore della velocità effettiva (UR/s). Accetta un numero con valore minimo di 400 che aumenta per unità pari a 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/"
}
Esempio 2
Nell'esempio seguente viene creata una raccolta con una velocità effettiva massima di scalabilità automatica pari a 4000 UR/s (scala tra 400 - 4000 UR/s).
x-ms-cosmos-offer-autopilot-settings intestazione viene usata per impostare il maxThroughput valore, ovvero il valore massimo di UR/s di scalabilità automatica. Accetta un numero con un minimo di 4000 che incrementa per unità di 1000. Quando viene usata la scalabilità automatica, è necessaria una definizione della chiave di partizione, come illustrato nell'esempio seguente:
Nota
Per abilitare la scalabilità automatica in un database o una raccolta esistente o passare dalla scalabilità automatica alla velocità effettiva manuale, vedere l'articolo Sostituire un'offerta.
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
}
}