Auflistung erstellen
Der Create Collection Vorgang erstellt eine neue Auflistung in einer Datenbank.
Hinweis
In diesen API-Referenzartikeln wird gezeigt, wie Ressourcen mithilfe der Azure Cosmos DB-Datenebenen-API erstellt werden. Mit der Datenebenen-API können Sie grundlegende Optionen wie Indizierungsrichtlinie und Partitionsschlüssel wie bei Cosmos DB SDKs konfigurieren. Wenn Sie vollständige Featureunterstützung für alle Azure Cosmos DB-Ressourcen benötigen, empfiehlt es sich, den Cosmos DB-Ressourcenanbieter zu verwenden.
Anforderung
| Methode | Anforderungs-URI | BESCHREIBUNG |
|---|---|---|
| POST | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls | {databaseaccount} ist der Name des Azure Cosmos DB-Kontos, das unter Ihrem Abonnement erstellt wurde. {db-id} kann entweder die ID oder der _rid Wert für die Datenbank sein. |
Header
Informationen zu Headern, die von allen Azure Cosmos DB-Anforderungen verwendet werden, finden Sie unter Allgemeine Azure Cosmos DB-REST-Anforderungsheader .
Beim Erstellen der Hashsignatur für das master Schlüsseltokens sollte der ResourceType "colls" sein. Die ResourceId sollte sein dbs/{db-id}, wobei {db-id} entweder die ID oder der _rid Wert der Datenbank sein kann.
| Eigenschaft | Erforderlich | type | BESCHREIBUNG |
|---|---|---|---|
| x-ms-offer-throughput | Optional | Number | Der vom Benutzer angegebene manuelle Durchsatz (RU/s) für die Sammlung, ausgedrückt in Einheiten von 100 Anforderungseinheiten pro Sekunde. Das Minimum beträgt 400 bis 1.000.000 (oder höher durch Anfordern einer Grenzwerterhöhung). Es muss nur einer von x-ms-offer-throughput oder x-ms-cosmos-offer-autopilot-settings angegeben werden. Diese Header können nicht zusammen angegeben werden. |
| x-ms-cosmos-offer-autopilot-settings | Optional | JSON | Der vom Benutzer angegebene automatische Skalierung max. RU/s. Der Wert ist ein JSON-Code mit der Eigenschaft maxThroughput. Beispiel: {"maxThroughput": 4000}.Es muss nur einer von x-ms-offer-throughput oder x-ms-cosmos-offer-autopilot-settings angegeben werden. Diese Header können nicht zusammen angegeben werden. Wenn die automatische Skalierung verwendet wird, ist eine partitionKey-Definition erforderlich. |
| x-ms-offer-type | Optional | String | Hierbei handelt es sich um einen Legacyheader für vordefinierte Leistungsstufen S1, S2 und S3, die eingestellt wurden. Es wird empfohlen, entweder den manuellen Durchsatz oder den automatischen Skalierungsdurchsatz zu verwenden, wie oben beschrieben. |
Body
| Eigenschaft | Erforderlich | type | BESCHREIBUNG |
|---|---|---|---|
| id | Erforderlich | String | Der vom Benutzer generierte eindeutige Name für die Sammlung. Keine zwei Sammlungen können dieselben IDs aufweisen. Es ist eine Zeichenfolge, die nicht mehr als 255 Zeichen sein darf. |
| indexingPolicy | Optional | Object | Dieser Wert wird zur Konfigurierung der Indizierungsrichtlinie verwendet. Die Indizierung erfolgt standardmäßig automatisch für alle Dokumentenpfade innerhalb der Auflistung. |
| partitionKey | Erforderlich | Object | Dieser Wert wird verwendet, um den Partitionsschlüssel für die Partitionierung von Daten in mehrere Partitionen zu konfigurieren. Um einen großen Partitionsschlüssel zu verwenden, geben Sie die Version 2 in der partitionKey-Eigenschaft an. Wenn die REST-API-Version 2018-12-31 oder höher ist, muss die Auflistung eine partitionKey-Definition enthalten. In Versionen, die älter als 2018-12-31 sind, kann eine nicht partitionierte Legacysammlung mit manuellem Durchsatz erstellt werden, indem die partitionKey-Definition weggelassen und sichergestellt wird, dass der Durchsatz zwischen 400 und 10.000 RU/s liegt. Um eine optimale Leistung und Skalierbarkeit zu erzielen, wird empfohlen, immer einen Partitionsschlüssel festzulegen. Erfahren Sie, wie Sie einen guten Partitionsschlüssel auswählen. |
Beispielnutzlast für den Text
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}
Antwort
Create Collection gibt die erstellte Auflistung als Antworttext zurück.
Header
Informationen zu Headern, die von allen Azure Cosmos DB-Antworten zurückgegeben werden, finden Sie unter Allgemeine Azure Cosmos DB-REST-Antwortheader .
Statuscodes
In der folgenden Tabelle sind die allgemeinen Statuscodes aufgeführt, die von diesem Vorgang zurückgegeben werden. Eine vollständige Liste der status Codes finden Sie unter HTTP-Statuscodes.
| HTTP-Statuscode | BESCHREIBUNG |
|---|---|
| 201 – Erstellt | Der Vorgang wurde durchgeführt. |
| 400 – Ungültige Anforderung | Der JSON-Text ist ungültig. Überprüfen Sie, ob geschweifte Klammern oder Anführungszeichen fehlen. |
| 409 – Konflikt | Die für die neue Sammlung bereitgestellte ID wurde von einer vorhandenen Sammlung übernommen. |
| 404 mit einem Unter-status Code von 1013 | Der Vorgang zum Erstellen der Sammlung wird noch ausgeführt. |
Wenn beim Erstellen einer Sammlung eine Timeoutausnahme auftritt, führen Sie einen Lesevorgang aus, um zu überprüfen, ob die Sammlung erfolgreich erstellt wurde. Der Lesevorgang gibt eine Ausnahme zurück, bis der Vorgang zum Erstellen der Sammlung erfolgreich war. Wenn der Lesevorgang eine Ausnahme mit status Code 404 und unter status Code 1013 auslöst, bedeutet dies, dass der Vorgang zum Erstellen der Sammlung noch ausgeführt wird. Wiederholen Sie den Lesevorgang, bis Sie 200- oder 201-status-Codes erhalten. Diese Codes informieren Sie darüber, dass die Sammlung erfolgreich erstellt wurde.
Body
| Eigenschaft | BESCHREIBUNG |
|---|---|
| id | Es ist der eindeutige Name, der die neue Sammlung identifiziert. |
| _los | Es handelt sich um eine vom System generierte Eigenschaft. Die Ressourcen-ID (_rid) ist ein eindeutiger Bezeichner, der auch gemäß dem Ressourcenstapel für das Ressourcenmodell hierarchisch ist. Sie wird intern für die Platzierung und Navigation der Berechtigungsressource verwendet. |
| _Ts | Es handelt sich um eine vom System generierte Eigenschaft. Sie gibt den zuletzt aktualisierten Zeitstempel der Ressource an. Der Wert ist ein Zeitstempel. |
| _Selbst | Es handelt sich um eine vom System generierte Eigenschaft. Es handelt sich um den eindeutigen, adressierbaren URI für die Ressource. |
| _Etag | Es handelt sich um eine vom System generierte Eigenschaft, die das Ressourcen-Etag darstellt, das für die Steuerung der optimistischen Parallelität erforderlich ist. |
| _Doc | Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der Dokumentressource angibt. |
| _sprocs | Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der Ressource gespeicherte Prozeduren (Sprocs) angibt. |
| _Trigger | Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der Triggerressource angibt. |
| _Udfs | Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der benutzerdefinierten Funktionsressource (udfs) angibt. |
| _Konflikte | Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der Konfliktressource angibt. Wenn während eines Vorgangs für eine Ressource in einer Auflistung ein Konflikt auftritt, können Benutzer Ressourcen überprüfen, die einen Konflikt verursachen, indem sie einen GET-Aufruf für den URI-Pfad des Konflikts ausführen. |
| indexingPolicy | Dies sind die Indizierungsrichtlinieneinstellungen für die Sammlung. |
| partitionKey | Dies sind die Partitionierungskonfigurationseinstellungen für die Sammlung. |
Eigenschaften unter Eingeschlossene Pfade
| Eigenschaft | BESCHREIBUNG |
|---|---|
| path | Pfad, für den das Indizierungsverhalten gilt. Indexpfade beginnen mit dem Stamm (/) und enden in der Regel mit dem Fragezeichen-Operator (?), der angibt, dass es mehrere mögliche Werte für das Präfix gibt. Für SELECT * FROM Families F WHERE F.familyName = "Andersen" müssen Sie z. B. einen Indexpfad für /familyName/? in der Indexrichtlinie der Sammlung. Indexpfade können auch das Platzhalterzeichen * verwenden, um das Verhalten für Pfade rekursiv unter dem Präfix anzugeben. Beispielsweise kann „/payload/*“ dazu verwendet werden, um sämtliche Elemente unter der payload-Eigenschaft von der Indizierung auszuschließen. |
| dataType | Dies ist der Datentyp, auf den das Indizierungsverhalten angewendet wird. Kann String, Number, Point, Polygon oder LineString sein. Booleane und NULL-Werte werden automatisch indiziert |
| kind | Der Indextyp. Hashindizes sind für Gleichheitsvergleiche nützlich, während Bereichsindizes für Gleichheit, Bereichsvergleiche und Sortierung nützlich sind. Räumliche Indizes sind für räumliche Abfragen nützlich. |
| precision | Die Genauigkeit des Indexes. Kann entweder auf -1 für maximale Genauigkeit oder zwischen 1-8 für Zahl und 1-100 für String festgelegt werden. Gilt nicht für dieDatentypen Point, Polygon und LineString . |
Eigenschaften unter Ausgeschlossene Pfade
| Eigenschaft | BESCHREIBUNG |
|---|---|
| path | Pfad, der von der Indizierung ausgeschlossen ist. Indexpfade beginnen mit dem Stamm (/) und enden in der Regel mit dem Platzhalteroperator *. Beispielsweise kann „/payload/*“ dazu verwendet werden, um sämtliche Elemente unter der payload-Eigenschaft von der Indizierung auszuschließen. |
Eigenschaften unter Partitionsschlüssel
| Eigenschaft | BESCHREIBUNG |
|---|---|
| Pfade | Ein Array von Pfaden, mit denen Daten innerhalb der Sammlung partitioniert werden können. Pfade dürfen keinen Wildcard oder einen nachgestellten Schrägstrich enthalten. Beispielsweise wird die JSON-Eigenschaft "AccountNumber" als "/AccountNumber" angegeben. Das Array darf nur einen einzelnen Wert enthalten. |
| kind | Der algorithmus, der für die Partitionierung verwendet wird. Nur Hash wird unterstützt. |
| version | Ein optionales Feld, wenn der Standardwert nicht angegeben ist, ist 1. Um den großen Partitionsschlüssel zu verwenden, legen Sie die Version auf 2 fest. Informationen zu großen Partitionsschlüsseln finden Sie im Artikel Erstellen von Sammlungen mit großen Partitionsschlüsseln . |
Beispielantworttext
{
"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/"
}
Beispiel 1
Im folgenden Beispiel wird eine Auflistung mit einem manuellen Durchsatz von 400 RU/s erstellt. x-ms-offer-throughput header wird verwendet, um den Durchsatzwert (RU/s) festzulegen. Sie akzeptiert eine Zahl mit dem Mindestwert 400, die um Einheiten von 100 erhöht wird.
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/"
}
Beispiel 2
Im folgenden Beispiel wird eine Auflistung mit einem automatisch skaliertem maximalen Durchsatz von 4000 RU/s erstellt (sie wird zwischen 400 und 4000 RU/s skaliert). x-ms-cosmos-offer-autopilot-settings header wird verwendet, um den maxThroughput Wert festzulegen, bei dem es sich um den wert für die automatische Skalierung von max RU/s handelt. Sie akzeptiert eine Zahl mit mindestens 4000, die um Einheiten von 1000 erhöht wird. Wenn die automatische Skalierung verwendet wird, ist eine Partitionsschlüsseldefinition erforderlich, wie im folgenden Beispiel gezeigt:
Hinweis
Informationen zum Aktivieren der automatischen Skalierung für eine vorhandene Datenbank oder Sammlung oder zum Wechsel von der automatischen Skalierung zum manuellen Durchsatz finden Sie im Artikel Ersetzen eines Angebots.
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
}
}