Vytvoření kolekce

Článek
05. 08. 2023

Operace Create Collection vytvoří novou kolekci v databázi.

Poznámka

Tyto články s referenčními informacemi o rozhraní API ukazují, jak vytvářet prostředky pomocí rozhraní API roviny dat služby Azure Cosmos DB. S rozhraním API roviny dat můžete nakonfigurovat základní možnosti, jako jsou zásady indexování, klíče oddílů podobně jako u sad SDK služby Cosmos DB. Pokud potřebujete úplnou podporu funkcí pro všechny prostředky Azure Cosmos DB, doporučujeme použít poskytovatele prostředků Cosmos DB.

Žádost

Metoda	Identifikátor URI žádosti	Description
POST	https://{databaseaccount}.documents.azure.com/dbs/{id_databáze}/colls	{databaseaccount} je název účtu služby Azure Cosmos DB vytvořeného v rámci vašeho předplatného. {db-id} může být hodnota ID nebo _rid databáze.

Hlavičky

Projděte si běžné hlavičky požadavků REST služby Azure Cosmos DB pro hlavičky, které používají všechny požadavky služby Azure Cosmos DB.

Při vytváření podpisu hash pro token hlavního klíče by měl být typ ResourceType "colls". ResourceId by měl být dbs/{db-id}, kde {db-id} může být ID nebo _rid hodnota databáze.

Vlastnost	Požaduje se	Typ	Description
x-ms-offer-throughput	Volitelné	Číslo	Uživatel určil ruční propustnost (RU/s) pro kolekci vyjádřenou v jednotkách 100 jednotek žádostí za sekundu. Minimální hodnota je 400 až 1 000 000 (nebo vyšší, pokud požádáte o navýšení limitu). Musí být zadán pouze jeden z hodnot `x-ms-offer-throughput` nebo `x-ms-cosmos-offer-autopilot-settings` . Tyto hlavičky nelze zadat společně.
x-ms-cosmos-offer-autopilot-settings	Volitelné	JSON	Uživatel zadal maximální maximální počet RU/s automatického škálování. Hodnota je JSON s vlastností `maxThroughput`. Příklad: `{"maxThroughput": 4000}`. Musí být zadán pouze jeden z hodnot `x-ms-offer-throughput` nebo `x-ms-cosmos-offer-autopilot-settings` . Tyto hlavičky nelze zadat společně. Při použití automatického škálování se vyžaduje definice partitionKey .
x-ms-offer-type	Volitelné	Řetězec	Toto je starší hlavička pro předdefinované úrovně výkonu S1, S2 a S3, které byly vyřazeny. Doporučujeme použít propustnost ručního nebo automatického škálování, jak je popsáno výše.

Text

Vlastnost	Požaduje se	Typ	Description
id	Vyžadováno	Řetězec	Jedinečný název kolekce vygenerovaný uživatelem. Žádné dvě kolekce nemohou mít stejná ID. Jedná se o řetězec, který nesmí být delší než 255 znaků.
zásady indexování	Volitelné	Objekt	Tato hodnota se používá ke konfiguraci zásad indexování. Ve výchozím nastavení je indexování pro všechny cesty k dokumentům v rámci kolekce automatické.
partitionKey	Vyžadováno	Objekt	Tato hodnota se používá ke konfiguraci klíče oddílu, který se má použít k rozdělení dat do více oddílů. Pokud chcete použít velký klíč oddílu, zadejte verzi jako 2 v rámci vlastnosti partitionKey. Pokud je verze rozhraní REST API 2018-12-31 nebo vyšší, kolekce musí obsahovat definici partitionKey . Ve verzích starších než 2018-12-31 je možné vytvořit starší kolekci bez oddílů s ruční propustností tak, že vynecháte definici partitionKey a zajistíte propustnost mezi 400 a 10 000 RU/s. Pro zajištění nejlepšího výkonu a škálovatelnosti se doporučuje vždy nastavit klíč oddílu. Přečtěte si, jak zvolit vhodný klíč oddílu.

Příklad datové části těla

{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "automatic": true,  
    "indexingMode": "Consistent",  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "dataType": "String",  
            "precision": -1,  
            "kind": "Range"  
          }  
        ]  
      }  
    ]  
  },  
  "partitionKey": {  
    "paths": [  
      "/AccountNumber"  
    ],  
    "kind": "Hash",
     "Version": 2

  }  
}

Odpověď

Create Collection vrátí vytvořenou kolekci jako tělo odpovědi.

Hlavičky

Informace o hlavičkách, které vrací všechny odpovědi služby Azure Cosmos DB, najdete v tématu Běžné hlavičky odpovědi REST služby Azure Cosmos DB.

Stavové kódy

Následující tabulka obsahuje seznam běžných stavových kódů vrácených touto operací. Úplný seznam stavových kódů najdete v tématu Stavové kódy HTTP.

Stavový kód HTTP	Popis
201 Vytvořeno	Operace byla úspěšná.
400 – Chybný požadavek	Text JSON je neplatný. Zkontrolujte, jestli nechybí složené závorky nebo uvozovky.
409 – Konflikt	ID zadané pro novou kolekci bylo převzato existující kolekcí.
404 s dílčím stavovým kódem 1013	Operace vytvoření kolekce stále probíhá.

Pokud při vytváření kolekce dojde k výjimce časového limitu, spusťte operaci čtení a ověřte, jestli se kolekce úspěšně vytvořila. Operace čtení vyvolá výjimku, dokud operace vytvoření kolekce nebude úspěšná. Pokud operace čtení vyvolá výjimku se stavovým kódem 404 a dílčím stavovým kódem 1013, znamená to, že operace vytvoření kolekce stále probíhá. Opakujte operaci čtení, dokud nedostanete stavové kódy 200 nebo 201. Tyto kódy vás upozorní, že se kolekce úspěšně vytvořila.

Text

Vlastnost	Popis
id	Jedná se o jedinečný název, který identifikuje novou kolekci.
_Zbavit	Jedná se o systémově vygenerovanou vlastnost. ID prostředku (_rid) je jedinečný identifikátor, který je také hierarchický pro zásobník prostředků na modelu prostředků. Používá se interně k umístění a navigaci prostředku oprávnění.
_Ts	Jedná se o systémově vygenerovanou vlastnost. Určuje časové razítko poslední aktualizace prostředku. Hodnota je časové razítko.
_Vlastní	Jedná se o systémově vygenerovanou vlastnost. Jedná se o jedinečný adresovatelný identifikátor URI prostředku.
_Etag	Jedná se o systémově vygenerovanou vlastnost představující značku prostředku etag vyžadovanou pro řízení optimistické souběžnosti.
_Doc	Jedná se o systémově vygenerovanou vlastnost, která určuje adresovatelnou cestu k prostředku dokumentů.
_sprocs	Jedná se o systémově vygenerovanou vlastnost, která určuje adresovatelnou cestu k prostředku uložených procedur (sprocs).
_Aktivační události	Jedná se o systémově vygenerovanou vlastnost, která určuje adresovatelnou cestu k prostředku triggerů.
_Udf	Jedná se o systémově vygenerovanou vlastnost, která určuje adresovatelnou cestu k prostředku uživatelem definovaných funkcí (udfs).
_Konflikty	Jedná se o systémově vygenerovanou vlastnost, která určuje adresovatelnou cestu ke konfliktu prostředku. Pokud během operace s prostředkem v rámci kolekce dojde ke konfliktu, můžou uživatelé zkontrolovat konfliktní prostředky provedením get na cestě URI konfliktů.
indexováníZásady	Jedná se o nastavení zásad indexování pro kolekci.
partitionKey	Jedná se o nastavení konfigurace dělení pro kolekci.

Vlastnosti v části Zahrnuté cesty

Vlastnost	Popis
Cestu	Cesta, na kterou se chování indexování vztahuje. Cesty indexu začínají kořenem (/) a obvykle končí operátorem otazníku (?), který označuje, že existuje více možných hodnot pro předponu. Chcete-li například zadat příkaz SELECT * FROM Families F WHERE F.familyName = "Andersen", musíte zahrnout cestu indexu pro /familyName/? v zásadách indexu kolekce. Cesty indexu mohou také použít operátor zástupného znaku * k určení chování cest rekurzivně pod předponou. Například /payload/* lze použít k vyloučení všeho v rámci vlastnosti datové části z indexování.
Datatype	Jedná se o datový typ, pro který se chování indexování používá. Může to být Řetězec, Číslo, Bod, Mnohoúhelník nebo LineString. Logické hodnoty a hodnoty null se automaticky indexují.
Druhu	Typ indexu. Indexy hodnot hash jsou užitečné pro porovnání rovnosti, zatímco indexy rozsahů jsou užitečné pro rovnost, porovnání rozsahů a řazení. Prostorové indexy jsou užitečné pro prostorové dotazy.
Přesnost	Přesnost indexu. Pro maximální přesnost lze nastavit hodnotu -1 nebo 1–8 pro Číslo a 1–100 pro Řetězec. Neplatí pro datové typy Point, Polygon a LineString .

Vlastnosti v části Vyloučené cesty

Vlastnost	Popis
Cestu	Cesta, která je vyloučena z indexování. Cesty indexu začínají kořenem (/) a obvykle končí operátorem zástupných znaků . Například /payload/ lze použít k vyloučení všeho v rámci vlastnosti datové části z indexování.

Vlastnosti v části Klíč oddílu

Vlastnost	Popis
Cesty	Pole cest, pomocí kterých lze data v kolekci rozdělit. Cesty nesmí obsahovat zástupný znak ani koncové lomítko. Například vlastnost JSON AccountNumber je určená jako /AccountNumber. Pole musí obsahovat pouze jednu hodnotu.
Druhu	Algoritmus použitý k dělení. Podporuje se pouze hodnota Hash.
Verze	Volitelné pole, pokud není zadáno, výchozí hodnota je 1. Pokud chcete použít klíč velkého oddílu, nastavte verzi na 2. Další informace o klíčích velkých oddílů najdete v článku o vytváření kolekcí s velkými klíči oddílů .

Příklad textu odpovědi

{  
  "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/"  
}

Příklad 1

Následující příklad vytvoří kolekci s ruční propustností 400 RU/s. x-ms-offer-throughput hlavička slouží k nastavení hodnoty propustnosti (RU/s). Přijímá číslo s minimální hodnotou 400, které se zvýší o jednotky 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/"  
}

Příklad 2

Následující příklad vytvoří kolekci s maximální propustností automatického škálování 4000 RU/s (škáluje se mezi 400 a 4000 RU/s). x-ms-cosmos-offer-autopilot-settings hlavička slouží k nastavení maxThroughput hodnoty, což je hodnota maximálního počtu RU/s automatického škálování. Přijímá číslo s minimálním počtem 4000, které se zvýší o jednotky po 1000. Při použití automatického škálování se vyžaduje definice klíče oddílu, jak je znázorněno v následujícím příkladu:

Poznámka

Pokud chcete povolit automatické škálování u existující databáze nebo kolekce nebo přepnout z automatického škálování na ruční propustnost, přečtěte si článek Nahrazení nabídky.

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

Sdílet prostřednictvím

Vytvoření kolekce

Žádost

Hlavičky

Text

Příklad datové části těla

Odpověď

Hlavičky

Stavové kódy

Text

Příklad textu odpovědi

Příklad 1

Příklad 2

Viz také

Další materiály