Verzameling maken
Met de Create Collection bewerking wordt een nieuwe verzameling in een database gemaakt.
Notitie
Deze API-referentieartikelen laten zien hoe u resources maakt met behulp van de Azure Cosmos DB-gegevensvlak-API. Met de gegevensvlak-API kunt u basisopties configureren, zoals indexeringsbeleid en partitiesleutels, net als met Cosmos DB SDK's. Als u volledige functieondersteuning nodig hebt voor alle Azure Cosmos DB-resources, raden we u aan de Cosmos DB-resourceprovider te gebruiken.
Aanvraag
| Methode | Aanvraag-URI | Beschrijving |
|---|---|---|
| POST | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls | {databaseaccount} is de naam van het Azure Cosmos DB-account dat is gemaakt onder uw abonnement. {db-id} kan de id of de _rid waarde voor de database zijn. |
Kopteksten
Zie Algemene Azure Cosmos DB REST-aanvraagheaders voor headers die worden gebruikt door alle Azure Cosmos DB-aanvragen.
Bij het samenstellen van de gehashte handtekening voor het hoofdsleuteltoken moet het ResourceType 'colls' zijn. De ResourceId moet zijn dbs/{db-id}, waarbij {db-id} de id of de _rid waarde van de database kan zijn.
| Eigenschap | Vereist | Type | Beschrijving |
|---|---|---|---|
| x-ms-offer-throughput | Optioneel | Aantal | De gebruiker heeft handmatige doorvoer (RU/s) opgegeven voor de verzameling, uitgedrukt in eenheden van 100 aanvraageenheden per seconde. Het minimum is 400 tot 1.000.000 (of hoger door een verhoging van de limiet aan te vragen). Er moet slechts één van x-ms-offer-throughput of x-ms-cosmos-offer-autopilot-settings worden opgegeven. Deze headers kunnen niet samen worden opgegeven. |
| x-ms-cosmos-offer-autopilot-settings | Optioneel | JSON | De gebruiker heeft het maximum aantal RU/s voor automatisch schalen opgegeven. De waarde is een JSON met de eigenschap maxThroughput. Bijvoorbeeld: {"maxThroughput": 4000}.Er moet slechts één van x-ms-offer-throughput of x-ms-cosmos-offer-autopilot-settings worden opgegeven. Deze headers kunnen niet samen worden opgegeven. Wanneer automatische schaalaanpassing wordt gebruikt, is een partitionKey-definitie vereist. |
| x-ms-offer-type | Optioneel | Tekenreeks | Dit is een verouderde header voor vooraf gedefinieerde prestatieniveaus S1, S2 en S3 die buiten gebruik zijn gesteld. Het wordt aanbevolen om handmatige doorvoer of automatische schaalaanpassing te gebruiken, zoals hierboven wordt beschreven. |
Hoofdtekst
| Eigenschap | Vereist | Type | Beschrijving |
|---|---|---|---|
| id | Vereist | Tekenreeks | De door de gebruiker gegenereerde unieke naam voor de verzameling. Geen twee verzamelingen kunnen dezelfde id's hebben. Het is een tekenreeks die niet meer dan 255 tekens mag bevatten. |
| indexingPolicy | Optioneel | Object | Deze waarde wordt gebruikt om het indexeringsbeleid te configureren. Standaard wordt de indexering automatisch uitgevoerd voor alle documentpaden binnen de verzameling. |
| partitionKey | Vereist | Object | Deze waarde wordt gebruikt om de partitiesleutel te configureren die moet worden gebruikt voor het partitioneren van gegevens in meerdere partities. Als u een grote partitiesleutel wilt gebruiken, geeft u versie 2 op in de eigenschap partitionKey. Als de REST API-versie 2018-12-31 of hoger is, moet de verzameling een partitionKey-definitie bevatten. In versies ouder dan 2018-12-31 kan een verouderde niet-gepartitioneerde verzameling met handmatige doorvoer worden gemaakt door de definitie partitionKey weg te laten en ervoor te zorgen dat de doorvoer tussen 400 - 10.000 RU/s ligt. Voor de beste prestaties en schaalbaarheid is het raadzaam om altijd een partitiesleutel in te stellen. Meer informatie over het kiezen van een goede partitiesleutel. |
Voorbeeld van nettolading van hoofdtekst
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}
Antwoord
Verzameling maken retourneert de gemaakte verzameling als antwoordtekst.
Kopteksten
Zie Algemene Azure Cosmos DB REST-antwoordheaders voor headers die worden geretourneerd door alle Azure Cosmos DB-antwoorden.
Statuscodes
De volgende tabel bevat algemene statuscodes die door deze bewerking worden geretourneerd. Zie HTTP-statuscodes voor een volledige lijst met statuscodes.
| HTTP-statuscode | Beschrijving |
|---|---|
| 201 Gemaakt | De bewerking is geslaagd. |
| 400 Ongeldige aanvraag | De JSON-hoofdtekst is ongeldig. Controleer of er accolades of aanhalingstekens ontbreken. |
| 409 Conflict | De id die voor de nieuwe verzameling is opgegeven, is overgenomen door een bestaande verzameling. |
| 404 met de substatuscode 1013 | De bewerking voor het maken van de verzameling wordt nog uitgevoerd. |
Als er een time-outuitzondering optreedt bij het maken van een verzameling, voert u een leesbewerking uit om te controleren of de verzameling is gemaakt. De leesbewerking genereert een uitzondering totdat het maken van de verzameling is voltooid. Als de leesbewerking een uitzondering genereert met statuscode 404 en substatuscode 1013, betekent dit dat de bewerking voor het maken van de verzameling nog steeds wordt uitgevoerd. Voer de leesbewerking opnieuw uit totdat u 200- of 201-statuscodes krijgt. Deze codes laten u weten dat de verzameling is gemaakt.
Hoofdtekst
| Eigenschap | Beschrijving |
|---|---|
| id | Het is de unieke naam die de nieuwe verzameling aangeeft. |
| _Ontdoen | Het is een door het systeem gegenereerde eigenschap. De resource-id (_rid) is een unieke id die ook hiërarchisch is voor de resourcestack van het resourcemodel. Deze wordt intern gebruikt voor de plaatsing en navigatie van de machtigingsresource. |
| _Ts | Het is een door het systeem gegenereerde eigenschap. Hiermee geeft u de laatst bijgewerkte tijdstempel van de resource op. De waarde is een tijdstempel. |
| _Zelf | Het is een door het systeem gegenereerde eigenschap. Dit is de unieke adresseerbare URI voor de resource. |
| _etag | Het is een door het systeem gegenereerde eigenschap die de resource-etag vertegenwoordigt die is vereist voor optimistisch gelijktijdigheidsbeheer. |
| _Doc | Het is een door het systeem gegenereerde eigenschap die het adresseerbare pad van de documentresource aangeeft. |
| _sprocs | Het is een door het systeem gegenereerde eigenschap die het adresseerbare pad van de resource opgeslagen procedures (sprocs) specificeert. |
| _Triggers | Het is een door het systeem gegenereerde eigenschap die het adresseerbare pad van de triggers-resource aangeeft. |
| _udfs | Het is een door het systeem gegenereerde eigenschap die het adresseerbare pad van de door de gebruiker gedefinieerde functiesresource (udfs) specificeert. |
| _Conflicten | Het is een door het systeem gegenereerde eigenschap die het adresseerbare pad van de conflictresource aangeeft. Tijdens een bewerking op een resource in een verzameling kunnen gebruikers, als er een conflict optreedt, de conflicterende resources inspecteren door een GET uit te voeren op het conflicterende URI-pad. |
| indexingPolicy | Dit zijn de indexeringsbeleidsinstellingen voor verzameling. |
| partitionKey | Dit zijn de configuratie-instellingen voor partitionering voor verzameling. |
Eigenschappen onder Opgenomen paden
| Eigenschap | Beschrijving |
|---|---|
| path | Pad waarop het indexeringsgedrag van toepassing is. Indexpaden beginnen met de hoofdmap (/) en eindigen meestal met de jokertekenoperator vraagteken (?), wat aangeeft dat er meerdere mogelijke waarden zijn voor het voorvoegsel. Als u bijvoorbeeld SELECT * FROM Families F WAAR F.familyName = "Andersen" wilt gebruiken, moet u een indexpad voor /familyName/? in het indexbeleid van de verzameling. Indexpaden kunnen ook de operator * met jokertekens gebruiken om het gedrag voor paden recursief op te geven onder het voorvoegsel. /payload/* kan bijvoorbeeld worden gebruikt om alles onder de nettoladingeigenschap uit te sluiten van indexering. |
| Datatype | Dit is het gegevenstype waarop het indexeringsgedrag wordt toegepast. Dit kan tekenreeks, getal, punt, veelhoek of lijntekenreeks zijn. Booleaanse waarden en null-waarden worden automatisch geïndexeerd |
| Soort | Het type index. Hash-indexen zijn handig voor gelijkheidsvergelijkingen, terwijl bereikindexen handig zijn voor gelijkheid, bereikvergelijkingen en sorteren. Ruimtelijke indexen zijn handig voor ruimtelijke query's. |
| Precisie | De precisie van de index. Kan worden ingesteld op -1 voor maximale precisie of tussen 1-8 voor Getal en 1-100 voor Tekenreeks. Niet van toepassing op gegevenstypen Punt, Veelhoek en Lijntekenreeks . |
Eigenschappen onder Uitgesloten paden
| Eigenschap | Beschrijving |
|---|---|
| path | Pad dat is uitgesloten van indexering. Indexpaden beginnen met de hoofdmap (/) en eindigen meestal met de jokertekenoperator *. /payload/* kan bijvoorbeeld worden gebruikt om alles onder de nettoladingeigenschap uit te sluiten van indexering. |
Eigenschappen onder Partitiesleutel
| Eigenschap | Beschrijving |
|---|---|
| Paden | Een matrix met paden waarmee gegevens in de verzameling kunnen worden gepartitioneerd. Paden mogen geen jokerteken of slash bevatten. De JSON-eigenschap 'AccountNumber' is bijvoorbeeld opgegeven als '/AccountNumber'. De matrix mag slechts één waarde bevatten. |
| Soort | Het algoritme dat wordt gebruikt voor partitionering. Alleen hash wordt ondersteund. |
| version | Een optioneel veld, indien niet opgegeven, is de standaardwaarde 1. Als u de grote partitiesleutel wilt gebruiken, stelt u de versie in op 2. Zie het artikel Verzamelingen maken met grote partitiesleutels voor meer informatie over grote partitiesleutels. |
Voorbeeld van antwoordtekst
{
"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/"
}
Voorbeeld 1
In het volgende voorbeeld wordt een verzameling gemaakt met een handmatige doorvoer van 400 RU/s.
x-ms-offer-throughput header wordt gebruikt om de waarde voor doorvoer (RU/s) in te stellen. Het accepteert een getal met een minimumwaarde van 400 dat wordt verhoogd met eenheden van 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/"
}
Voorbeeld 2
In het volgende voorbeeld wordt een verzameling gemaakt met een maximale doorvoer voor automatische schaalaanpassing van 4000 RU/s (deze schaalt tussen 400 - 4000 RU/s).
x-ms-cosmos-offer-autopilot-settings header wordt gebruikt om de maxThroughput waarde in te stellen. Dit is de waarde voor het maximum aantal RU/s voor automatisch schalen. Het accepteert een getal met een minimum van 4000 dat wordt verhoogd met eenheden van 1000. Wanneer automatische schaalaanpassing wordt gebruikt, is een definitie van een partitiesleutel vereist, zoals wordt weergegeven in het volgende voorbeeld:
Notitie
Als u automatische schaalaanpassing wilt inschakelen voor een bestaande database of verzameling, of wilt overschakelen van automatische schaalaanpassing naar handmatige doorvoer, raadpleegt u het artikel Een aanbieding vervangen.
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
}
}