Auflistung erstellen

Artikel
07/19/2023

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
  }  
}

Freigeben über

Auflistung erstellen

Anforderung

Header

Body

Beispielnutzlast für den Text

Antwort

Header

Statuscodes

Body

Beispielantworttext

Beispiel 1

Beispiel 2

Weitere Informationen

Zusätzliche Ressourcen