Tworzenie kolekcji
Operacja Create Collection tworzy nową kolekcję w bazie danych.
Uwaga
Te artykuły referencyjne dotyczące interfejsu API pokazują, jak tworzyć zasoby przy użyciu interfejsu API płaszczyzny danych usługi Azure Cosmos DB. Za pomocą interfejsu API płaszczyzny danych można skonfigurować podstawowe opcje, takie jak zasady indeksowania, klucze partycji, podobnie jak w przypadku zestawów SDK usługi Cosmos DB. Jeśli potrzebujesz pełnej obsługi funkcji dla wszystkich zasobów usługi Azure Cosmos DB, zalecamy użycie dostawcy zasobów usługi Cosmos DB.
Żądanie
| Metoda | Identyfikator URI żądania | Opis |
|---|---|---|
| POST | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls | {databaseaccount} to nazwa konta usługi Azure Cosmos DB utworzonego w ramach subskrypcji. {db-id} może być identyfikatorem lub wartością _rid dla bazy danych. |
Nagłówki
Zobacz Typowe nagłówki żądań REST usługi Azure Cosmos DB dla nagłówków , które są używane przez wszystkie żądania usługi Azure Cosmos DB.
Podczas konstruowania sygnatury skrótu tokenu klucza głównego typ zasobu powinien mieć wartość "colls". Identyfikator ResourceId powinien mieć wartość dbs/{db-id}, gdzie {db-id} może być identyfikatorem lub _rid wartością bazy danych.
| Właściwość | Wymagany | Typ | Opis |
|---|---|---|---|
| x-ms-offer-przepływność | Opcjonalne | Liczba | Użytkownik określił przepływność ręczną (RU/s) dla kolekcji wyrażonej w jednostkach 100 jednostek żądania na sekundę. Minimalna wartość to 400 do 1000 000 (lub wyższa, żądając zwiększenia limitu). Należy określić tylko jeden z x-ms-offer-throughput elementów lub x-ms-cosmos-offer-autopilot-settings . Nie można określić tych nagłówków razem. |
| x-ms-cosmos-offer-autopilot-settings | Opcjonalne | JSON | Użytkownik określił maksymalną wartość RU/s autoskalu. Wartość jest plikiem JSON z właściwością maxThroughput. Na przykład: {"maxThroughput": 4000}.Należy określić tylko jeden z x-ms-offer-throughput elementów lub x-ms-cosmos-offer-autopilot-settings . Nie można określić tych nagłówków razem. Gdy jest używane autoskalowanie, wymagana jest definicja partitionKey . |
| x-ms-offer-type | Opcjonalne | Ciąg | Jest to starszy nagłówek dla wstępnie zdefiniowanych poziomów wydajności S1, S2 i S3, które zostały wycofane. Zaleca się użycie przepływności ręcznej lub automatycznej, zgodnie z powyższym opisem. |
Treść
| Właściwość | Wymagany | Typ | Opis |
|---|---|---|---|
| id | Wymagane | Ciąg | Unikatowa nazwa kolekcji wygenerowana przez użytkownika. Żadne dwie kolekcje nie mogą mieć tych samych identyfikatorów. Jest to ciąg, który nie może zawierać więcej niż 255 znaków. |
| indexingPolicy | Opcjonalne | Obiekt | Ta wartość służy do konfigurowania zasad indeksowania. Domyślnie indeksowanie jest automatyczne dla wszystkich ścieżek dokumentów w kolekcji. |
| partitionKey | Wymagane | Obiekt | Ta wartość służy do konfigurowania klucza partycji, który ma być używany do partycjonowania danych na wiele partycji. Aby użyć dużego klucza partycji, określ wersję jako 2 we właściwości partitionKey. Jeśli wersja interfejsu API REST to 2018-12-31 lub nowsza, kolekcja musi zawierać definicję partitionKey . W wersjach starszych niż 2018-12-31 starsza kolekcja bez partycji z ręczną przepływnością można utworzyć, pomijając definicję partitionKey i zapewniając, że przepływność wynosi od 400 do 10 000 RU/s. Aby uzyskać najlepszą wydajność i skalowalność, zaleca się zawsze ustawienie klucza partycji. Dowiedz się, jak wybrać dobry klucz partycji. |
Przykładowy ładunek treści
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}
Reakcja
Funkcja Create Collection zwraca utworzoną kolekcję jako treść odpowiedzi.
Nagłówki
Zobacz Typowe nagłówki odpowiedzi REST usługi Azure Cosmos DB dla nagłówków zwracanych przez wszystkie odpowiedzi usługi Azure Cosmos DB.
Kody stanu
Poniższa tabela zawiera listę typowych kodów stanu zwracanych przez tę operację. Aby uzyskać pełną listę kodów stanu, zobacz Kody stanu HTTP.
| Kod stanu HTTP | Opis |
|---|---|
| Utworzono 201 | Operacja zakończyła się pomyślnie. |
| 400 Nieprawidłowe żądanie | Treść JSON jest nieprawidłowa. Sprawdź brakujące nawiasy klamrowe lub cudzysłowy. |
| 409 Konflikt | Identyfikator podany dla nowej kolekcji został pobrany przez istniejącą kolekcję. |
| 404 z kodem stanu podrzędnego 1013 | Operacja tworzenia kolekcji jest nadal w toku. |
Jeśli wystąpi wyjątek przekroczenia limitu czasu podczas tworzenia kolekcji, uruchom operację odczytu, aby sprawdzić, czy kolekcja została utworzona pomyślnie. Operacja odczytu zgłasza wyjątek, dopóki operacja tworzenia kolekcji nie powiedzie się. Jeśli operacja odczytu zgłasza wyjątek z kodem stanu 404 i kodem stanu podrzędnego 1013, oznacza to, że operacja tworzenia kolekcji jest nadal w toku. Spróbuj ponownie wykonać operację odczytu, dopóki nie otrzymasz kodów stanu 200 lub 201, te kody poinformują o pomyślnym utworzeniu kolekcji.
Treść
| Właściwość | Opis |
|---|---|
| id | Jest to unikatowa nazwa, która identyfikuje nową kolekcję. |
| _Rid | Jest to właściwość wygenerowana przez system. Identyfikator zasobu (_rid) to unikatowy identyfikator, który jest także identyfikatorem hierarchicznym dla stosu zasobów w modelu zasobów. Jest on używany wewnętrznie do umieszczania i nawigacji zasobu uprawnień. |
| _Ts | Jest to właściwość wygenerowana przez system. Określa ostatni zaktualizowany znacznik czasu zasobu. Wartość jest znacznikiem czasu. |
| _Własny | Jest to właściwość wygenerowana przez system. Jest to unikatowy adresowy identyfikator URI zasobu. |
| _Etag | Jest to właściwość wygenerowana przez system reprezentująca tag zasobu wymagany do optymistycznej kontrolki współbieżności. |
| _Dok | Jest to właściwość wygenerowana przez system, która określa ścieżkę adresową zasobu dokumentów. |
| _sprocs | Jest to właściwość wygenerowana przez system, która określa ścieżkę adresową zasobu procedur składowanych (sprocs). |
| _Wyzwalaczy | Jest to właściwość wygenerowana przez system, która określa ścieżkę adresową zasobu wyzwalaczy. |
| _Udfs | Jest to właściwość wygenerowana przez system, która określa ścieżkę adresową zasobu funkcji zdefiniowanych przez użytkownika (udfs). |
| _Konflikty | Jest to właściwość wygenerowana przez system, która określa ścieżkę adresową zasobu konfliktów. Podczas operacji na zasobie w kolekcji, jeśli wystąpi konflikt, użytkownicy mogą sprawdzić zasoby powodujące konflikt, wykonując polecenie GET na ścieżce identyfikatora URI konfliktów. |
| indexingPolicy | Jest to ustawienia zasad indeksowania dla kolekcji. |
| partitionKey | Jest to ustawienia konfiguracji partycjonowania dla kolekcji. |
Właściwości w obszarze Dołączone ścieżki
| Właściwość | Opis |
|---|---|
| Ścieżka | Ścieżka, do której ma zastosowanie zachowanie indeksowania. Ścieżki indeksu zaczynają się od katalogu głównego (/) i zazwyczaj kończą się operatorem symbolu wieloznakowego (?), co oznacza, że istnieje wiele możliwych wartości prefiksu. Aby na przykład służyć SELECT * FROM Families F WHERE F.familyName = "Andersen", musisz dołączyć ścieżkę indeksu dla /familyName/? w zasadach indeksu kolekcji. Ścieżki indeksów mogą również używać operatora * symboli wieloznacznych, aby określić zachowanie ścieżek cyklicznie pod prefiksem. Na przykład /payload/* można użyć do wykluczenia wszystkiego pod właściwością ładunku z indeksowania. |
| Datatype | Jest to typ danych, do którego zastosowano zachowanie indeksowania. Może to być ciąg, liczba, punkt, wielokąt lub lineString. Wartości logiczne i null są automatycznie indeksowane |
| Rodzaju | Typ indeksu. Indeksy skrótów są przydatne w przypadku porównań równości, podczas gdy indeksy zakresu są przydatne w przypadku równości, porównań zakresów i sortowania. Indeksy przestrzenne są przydatne w przypadku zapytań przestrzennych. |
| Precyzji | Precyzja indeksu. Można ustawić wartość -1 dla maksymalnej dokładności lub od 1 do 8 dla wartości Liczba i 1–100 dla ciągu. Nie dotyczy typów danych Point, Polygon i LineString . |
Właściwości w obszarze Wykluczone ścieżki
| Właściwość | Opis |
|---|---|
| Ścieżka | Ścieżka wykluczona z indeksowania. Ścieżki indeksu zaczynają się od katalogu głównego (/) i zazwyczaj kończą się operatorem * symboli wieloznacznych. Na przykład /payload/* można użyć do wykluczenia wszystkiego pod właściwością ładunku z indeksowania. |
Właściwości w obszarze Klucz partycji
| Właściwość | Opis |
|---|---|
| Ścieżki | Tablica ścieżek, przy użyciu których można partycjonować dane w kolekcji. Ścieżki nie mogą zawierać symbolu wieloznakowego ani ukośnika końcowego. Na przykład właściwość JSON "AccountNumber" jest określona jako "/AccountNumber". Tablica musi zawierać tylko jedną wartość. |
| Rodzaju | Algorytm używany do partycjonowania. Obsługiwane jest tylko skróty. |
| Wersja | Opcjonalne pole, jeśli nie określono wartości domyślnej to 1. Aby użyć dużego klucza partycji, ustaw wersję na 2. Aby dowiedzieć się więcej o dużych kluczach partycji, zobacz artykuł dotyczący tworzenia kolekcji z dużym kluczem partycji . |
Przykładowa treść odpowiedzi
{
"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/"
}
Przykład 1
Poniższy przykład tworzy kolekcję z ręczną przepływnością 400 RU/s.
x-ms-offer-throughput nagłówek służy do ustawiania wartości przepływności (RU/s). Akceptuje liczbę z minimalną wartością 400, która zwiększa się o 100 jednostek.
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/"
}
Przykład 2
W poniższym przykładzie utworzono kolekcję z maksymalną przepływnością autoskalowania 4000 RU/s (skaluje się między 400 a 4000 RU/s).
x-ms-cosmos-offer-autopilot-settings nagłówek służy do ustawiania wartości, która jest wartością maksymalną maxThroughput ru/s autoskalowania. Akceptuje liczbę z co najmniej 4000, która zwiększa się o 1000 jednostek. Gdy jest używane autoskalowanie, wymagana jest definicja klucza partycji, jak pokazano w poniższym przykładzie:
Uwaga
Aby włączyć skalowanie automatyczne w istniejącej bazie danych lub kolekcji lub przełączyć się z autoskalowania do przepływności ręcznej, zobacz artykuł Zastępowanie oferty.
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
}
}