Skapa samling

Artikel
07/19/2023

Åtgärden Create Collection skapar en ny samling i en databas.

Anteckning

Dessa API-referensartiklar visar hur du skapar resurser med hjälp av Azure Cosmos DB-dataplans-API:et. Med API:et för dataplanet kan du konfigurera grundläggande alternativ, till exempel indexeringsprincip, partitionsnycklar ungefär som du kan med Cosmos DB-SDK:er. Om du behöver fullständigt funktionsstöd för alla Azure Cosmos DB-resurser rekommenderar vi att du använder Cosmos DB-resursprovidern.

Förfrågan

Metod	URI för förfrågan	Description
POST	https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls	{databaseaccount} är namnet på det Azure Cosmos DB-konto som skapats under din prenumeration. {db-id} kan vara antingen ID:t eller _rid värdet för databasen.

Sidhuvuden

Se Vanliga REST-begärandehuvuden för Azure Cosmos DB för rubriker som används av alla Azure Cosmos DB-begäranden.

När du skapar den hashade signaturen för huvudnyckeltoken ska ResourceType vara "colls". ResourceId ska vara dbs/{db-id}, där {db-id} kan vara antingen ID:t eller _rid värdet för databasen.

Egenskap	Krävs	Typ	Description
x-ms-offer-throughput	Valfritt	Tal	Användaren angav manuellt dataflöde (RU/s) för samlingen uttryckt i enheter om 100 enheter för programbegäran per sekund. Minimivärdet är 400 upp till 1 000 000 (eller högre genom att begära en gränsökning). Endast en av `x-ms-offer-throughput` eller `x-ms-cosmos-offer-autopilot-settings` måste anges. Dessa rubriker kan inte anges tillsammans.
x-ms-cosmos-offer-autopilot-settings	Valfritt	JSON	Användaren har angett maximalt antal RU/s för autoskalning. Värdet är en JSON med egenskapen `maxThroughput`. Exempel: `{"maxThroughput": 4000}`. Endast en av `x-ms-offer-throughput` eller `x-ms-cosmos-offer-autopilot-settings` måste anges. Dessa rubriker kan inte anges tillsammans. När autoskalning används krävs en partitionKey-definition .
x-ms-offer-type	Valfritt	Sträng	Det här är en äldre rubrik för fördefinierade prestandanivåer S1, S2 och S3 som har dragits tillbaka. Vi rekommenderar att du använder antingen manuellt dataflöde eller autoskalningsdataflöde enligt beskrivningen ovan.

Brödtext

Egenskap	Krävs	Typ	Description
id	Obligatorisk	Sträng	Det användargenererade unika namnet för samlingen. Inga två samlingar kan ha samma ID:n. Det är en sträng som inte får innehålla fler än 255 tecken.
indexingPolicy	Valfritt	Objekt	Det här värdet används för att konfigurera indexeringsprincipen. Som standard är indexeringen automatisk för alla dokumentsökvägar i samlingen.
partitionKey	Obligatorisk	Objekt	Det här värdet används för att konfigurera partitionsnyckeln som ska användas för att partitionera data i flera partitioner. Om du vill använda en stor partitionsnyckel anger du versionen som 2 i egenskapen partitionKey. Om REST API-versionen är 2018-12-31 eller högre måste samlingen innehålla en partitionKey-definition . I versioner som är äldre än 2018-12-31 kan en äldre icke-partitionerad samling med manuellt dataflöde skapas genom att utelämna partitionKey-definitionen och se till att dataflödet är mellan 400 och 10 000 RU/s. För bästa prestanda och skalbarhet rekommenderar vi att du alltid anger en partitionsnyckel. Lär dig mer om hur du väljer en bra partitionsnyckel.

Exempel på nyttolast för brödtext

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

  }  
}

Svarsåtgärder

Skapa samling returnerar den skapade samlingen som en svarstext.

Sidhuvuden

Se Vanliga REST-svarshuvuden för Azure Cosmos DB för rubriker som returneras av alla Azure Cosmos DB-svar.

Statuskoder

I följande tabell visas vanliga statuskoder som returneras av den här åtgärden. En fullständig lista över statuskoder finns i HTTP-statuskoder.

HTTP-statuskod	Beskrivning
201 Skapad	Åtgärden lyckades.
400 Felaktig begäran	JSON-brödtexten är ogiltig. Sök efter saknade klammerparenteser eller citattecken.
409 – Konflikt	ID:t för den nya samlingen har tagits av en befintlig samling.
404 med understatuskoden 1013	Insamlingsåtgärden för att skapa pågår fortfarande.

Om du stöter på timeout-undantag när du skapar en samling kör du en läsåtgärd för att kontrollera om samlingen har skapats. Läsåtgärden utlöser ett undantag tills åtgärden för att skapa samlingen lyckas. Om läsåtgärden utlöser ett undantag med statuskoden 404 och understatuskoden 1013 innebär det att åtgärden för att skapa samlingen fortfarande pågår. Försök att läsa igen tills du får statuskoderna 200 eller 201. Dessa koder meddelar dig att samlingen har skapats.

Brödtext

Egenskap	Beskrivning
id	Det är det unika namnet som identifierar den nya samlingen.
_Bli	Det är en systemgenererad egenskap. Resurs-ID (_rid) är en unik identifierare som också är hierarkisk per resursstacken på resursmodellen. Den används internt för placering och navigering av behörighetsresursen.
_Ts	Det är en systemgenererad egenskap. Den anger resursens senast uppdaterade tidsstämpel. Värdet är en tidsstämpel.
_Själv	Det är en systemgenererad egenskap. Det är den unika adresserbara URI:n för resursen.
_Etag	Det är en systemgenererad egenskap som representerar resursetaggen som krävs för optimistisk samtidighetskontroll.
_Doc	Det är en systemgenererad egenskap som anger dokumentresursens adresserbara sökväg.
_sprocs	Det är en systemgenererad egenskap som anger den adresserbara sökvägen för resursen lagrade procedurer (sprocs).
_Utlösare	Det är en systemgenererad egenskap som anger den adresserbara sökvägen för utlösarresursen.
_udfs	Det är en systemgenererad egenskap som anger den adresserbara sökvägen för den användardefinierade funktionsresursen (udfs).
_Konflikter	Det är en systemgenererad egenskap som anger den adresserbara sökvägen för konfliktresursen. Under en åtgärd på en resurs i en samling, om en konflikt inträffar, kan användarna inspektera de resurser som står i konflikt genom att utföra en GET på konflikt-URI-sökvägen.
indexingPolicy	Det är indexeringsprincipinställningarna för samlingen.
partitionKey	Det är konfigurationsinställningarna för partitionering för samlingen.

Egenskaper under Inkluderade sökvägar

Egenskap	Beskrivning
Sökvägen	Sökväg som indexeringsbeteendet gäller för. Indexsökvägar börjar med roten (/) och slutar vanligtvis med frågetecknet (?) jokerteckenoperator, vilket anger att det finns flera möjliga värden för prefixet. Om du till exempel vill visa SELECT * FROM Families F WHERE F.familyName = "Andersen" måste du inkludera en indexsökväg för /familyName/? i samlingens indexprincip. Indexsökvägar kan också använda operatorn * jokertecken för att ange beteendet för sökvägar rekursivt under prefixet. Till exempel kan /payload/* användas för att undanta allt under nyttolastegenskapen från indexering.
Datatyp	Det är den datatyp som indexeringsbeteendet tillämpas på. Kan vara Sträng, Tal, Punkt, Polygon eller LineString. Booleska värden och null-värden indexeras automatiskt
Typ	Typ av index. Hash-index är användbara för likhetsjämförelser medan Intervallindex är användbara för likhet, intervalljämförelser och sortering. Rumsliga index är användbara för rumsliga frågor.
Precision	Indexets precision. Kan antingen anges till -1 för maximal precision eller mellan 1–8 för Tal och 1–100 för Sträng. Gäller inte för datatyperna Point, Polygon och LineString .

Egenskaper under Undantagna sökvägar

Egenskap	Beskrivning
Sökvägen	Sökväg som undantas från indexering. Indexsökvägar börjar med roten (/) och slutar vanligtvis med operatorn * jokertecken. Till exempel kan /payload/* användas för att undanta allt under nyttolastegenskapen från indexering.

Egenskaper under partitionsnyckel

Egenskap	Beskrivning
Sökvägar	En matris med sökvägar som använder vilka data i samlingen som kan partitioneras. Sökvägar får inte innehålla jokertecken eller avslutande snedstreck. JSON-egenskapen "AccountNumber" anges till exempel som "/AccountNumber". Matrisen får bara innehålla ett enda värde.
Typ	Algoritmen som används för partitionering. Endast hash stöds.
Version	Ett valfritt fält, om det inte anges är standardvärdet 1. Om du vill använda den stora partitionsnyckeln anger du versionen till 2. Mer information om stora partitionsnycklar finns i artikeln om hur du skapar samlingar med stor partitionsnyckel .

Exempel på svarstext

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

Exempel 1

I följande exempel skapas en samling med ett manuellt dataflöde på 400 RU/s. x-ms-offer-throughput -huvudet används för att ange dataflödesvärdet (RU/s). Den accepterar ett tal med ett minsta värde på 400 som ökar med enheter på 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/"  
}

Exempel 2

I följande exempel skapas en samling med ett maximalt dataflöde för autoskalning på 4 000 RU/s (den skalas mellan 400 och 4 000 RU/s). x-ms-cosmos-offer-autopilot-settings -huvudet används för att ange maxThroughput värdet, vilket är maxvärdet för autoskalning av RU/s. Den accepterar ett tal med minst 4 000 som ökar med enheter på 1 000. När autoskalning används krävs en partitionsnyckeldefinition, som du ser i följande exempel:

Anteckning

Om du vill aktivera autoskalning för en befintlig databas eller samling eller växla från autoskalning till manuellt dataflöde läser du artikeln Ersätt ett erbjudande.

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

Skapa samling

Förfrågan

Sidhuvuden

Brödtext

Exempel på nyttolast för brödtext

Svarsåtgärder

Sidhuvuden

Statuskoder

Brödtext

Exempel på svarstext

Exempel 1

Exempel 2

Se även

Ytterligare resurser