コレクションの作成
この操作により Create Collection 、データベースに新しいコレクションが作成されます。
注意
これらの API リファレンス記事では、Azure Cosmos DB データ プレーン API を使用してリソースを作成する方法について説明します。 データ プレーン API を使用すると、Cosmos DB SDK と同様に、インデックス作成ポリシー、パーティション キーなどの基本的なオプションを構成できます。 すべての Azure Cosmos DB リソースの完全な機能サポートが必要な場合は、 Cosmos DB リソース プロバイダーを使用することをお勧めします。
Request
| Method | 要求 URI | 説明 |
|---|---|---|
| POST | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls | {databaseaccount} は、サブスクリプションの下に作成された Azure Cosmos DB アカウントの名前です。 {db-id} には、データベースの ID または_rid値を指定できます。 |
ヘッダー
すべての Azure Cosmos DB 要求 で使用されるヘッダーについては、「共通の Azure Cosmos DB REST 要求ヘッダー」を参照してください。
マスター キー トークンのハッシュ署名を構築する場合、ResourceType は "colls" である必要があります。 ResourceId は である dbs/{db-id}必要があります。{db-id} には、データベースの ID または_rid値を指定できます。
| プロパティ | 必須 | Type | 説明 |
|---|---|---|---|
| x-ms-offer-throughput | 省略可能 | Number | ユーザーは、1 秒あたり 100 要求ユニットの単位で表されるコレクションに手動スループット (RU/秒) を指定しました。 最小値は 400 から 1,000,000 までです (制限の引き上げを要求することで、以上)。 または x-ms-cosmos-offer-autopilot-settings の x-ms-offer-throughput 1 つだけを指定する必要があります。 これらのヘッダーを一緒に指定することはできません。 |
| x-ms-cosmos-offer-autopilot-settings | 省略可能 | JSON | ユーザーが指定した自動スケーリングの最大 RU/秒。 値は、 プロパティを持つ JSON です maxThroughput。 たとえば、{"maxThroughput": 4000} のように指定します。または x-ms-cosmos-offer-autopilot-settings の x-ms-offer-throughput 1 つだけを指定する必要があります。 これらのヘッダーを一緒に指定することはできません。 自動スケーリングを使用する場合は、 partitionKey 定義が必要です。 |
| x-ms-offer-type | 省略可能 | String | これは、廃止された定義済みのパフォーマンス レベル S1、S2、S3 の レガシ ヘッダー です。 前述のように、手動または自動スケーリングのスループットを使用することをお勧めします。 |
Body
| プロパティ | 必須 | Type | 説明 |
|---|---|---|---|
| id | 必須 | String | コレクションのユーザーが生成した一意の名前。 同じ ID を持つ 2 つのコレクションはありません。 255 文字以下の文字列です。 |
| indexingPolicy | 省略可能 | Object | この値は、インデックス作成ポリシーの構成に使用されます。 既定では、コレクション内のすべてのドキュメント パスに対して自動でインデックス作成が行われます。 |
| partitionKey | 必須 | Object | この値は、データを複数のパーティションにパーティション分割するために使用されるパーティション キーを構成するために使用されます。 大きなパーティション キーを使用するには、partitionKey プロパティ内でバージョンを 2 として指定します。 REST API バージョンが 2018-12-31 以降の場合、コレクションには partitionKey 定義を含める必要があります。 2018-12-31 より前のバージョンでは、 partitionKey 定義を省略し、スループットが 400 から 10,000 RU/秒であることを確認することで、手動スループットを持つ従来の非パーティションコレクションを作成できます。 最適なパフォーマンスとスケーラビリティを実現するには、常にパーティション キーを設定することをお勧めします。 適切なパーティション キーを選択する方法について説明します。 |
本文ペイロードの例
{
"id": "testcoll",
"indexingPolicy": {
"automatic": true,
"indexingMode": "Consistent",
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"dataType": "String",
"precision": -1,
"kind": "Range"
}
]
}
]
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash",
"Version": 2
}
}
[応答]
Create Collection は、作成されたコレクションを応答本文として返します。
ヘッダー
すべての Azure Cosmos DB 応答 によって返されるヘッダーについては、「共通の Azure Cosmos DB REST 応答ヘッダー」を参照してください。
状態コード
次の表に、この操作で返される一般的なステータス コードを示します。 状態コードの完全な一覧については、「 HTTP 状態コード」を参照してください。
| HTTP 状態コード | 説明 |
|---|---|
| 201 Created | 操作に成功しました。 |
| 400 Bad Request | JSON の本文が無効です。 中かっこや引用符の不足がないか確認してください。 |
| 409 競合 | 新しいコレクションに指定された ID は、既存のコレクションによって取得されています。 |
| サブ状態コードが 1013 の 404 | コレクションの作成操作はまだ進行中です。 |
コレクションの作成時にタイムアウト例外が発生した場合は、読み取り操作を実行して、コレクションが正常に作成されたかどうかを検証します。 この読み取り操作では、コレクションの作成操作が成功するまで例外がスローされます。 読み取り操作で状態コード 404、サブ状態コード 1013 の例外がスローされた場合は、コレクションの作成操作がまだ進行中であることを意味します。 200 または 201 の状態コードが表示されるまで、読み取り操作を再試行します。これらのコードにより、コレクションが正常に作成されたことが通知されます。
Body
| プロパティ | 説明 |
|---|---|
| id | これは、新しいコレクションを識別する一意の名前です。 |
| _解消 | システムによって生成されるプロパティです。 リソース ID (_rid) は一意の識別子であり、リソース モデルのリソース スタックごとの階層も示します。 アクセス許可リソースの配置およびナビゲーションのために内部的に使用されます。 |
| _Ts | システムによって生成されるプロパティです。 リソースの最終更新タイムスタンプを示します。 値は、タイムスタンプです。 |
| _自己 | システムによって生成されるプロパティです。 リソースの一意のアドレス指定が可能な URI です。 |
| _Etag | これは、オプティミスティック コンカレンシー制御に必要なリソース etag を表すシステム生成プロパティです。 |
| _ドキュメント | これは、ドキュメント リソースのアドレス指定可能パスを指定するシステム生成のプロパティです。 |
| _Sprocs | ストアド プロシージャ (sprocs) リソースのアドレス指定可能パスを指定するシステム生成のプロパティです。 |
| _トリガー | トリガー リソースのアドレス指定可能パスを指定するシステム生成のプロパティです。 |
| _Udf | これは、ユーザー定義関数 (udfs) リソースのアドレス指定可能パスを指定するシステム生成のプロパティです。 |
| _競合 | 競合するリソースのアドレス指定可能パスを指定するシステム生成のプロパティです。 コレクション内のリソースに対する操作で競合が発生した場合は、ユーザーが競合の URI パスに GET を実行して、競合しているリソースを検査することができます。 |
| indexingPolicy | コレクションのインデックス作成ポリシー設定です。 |
| partitionKey | コレクションのパーティション分割構成設定です。 |
[インクルード パス] のプロパティ
| プロパティ | 説明 |
|---|---|
| path | インデックス作成の動作が適用されるパス。 インデックス パスはルート (/) で始まり、通常は疑問符 (?) ワイルドカード演算子で終わり、プレフィックスに複数の値が指定可能であることを示します。 たとえば、SELECT * FROM Families F WHERE F.familyName = "Andersen" を処理するには、コレクションのインデックス ポリシーに /familyName/? の をコレクションのインデックス ポリシーに格納します。 インデックスのパスは * ワイルドカード演算子を使用して、プレフィックスの後ろに続くパスの動作を再帰的に指定することもできます。 たとえば、/payload/* を使用して、ペイロード プロパティの下に属するものをすべてインデックス作成から除外できます。 |
| dataType | インデックス作成の動作が適用されるデータ型です。 String、Number、Point、Polygon、LineString のいずれかを指定できます。 ブール値と null 値は自動的にインデックスが作成されます |
| kind | インデックスの種類です。 ハッシュ インデックスは等値比較に役立ちますが、 Range インデックスは等値、範囲比較、並べ替えに役立ちます。 空間 インデックスは、空間クエリに役立ちます。 |
| 有効桁数 (precision) | インデックスの有効桁数。 最大有効桁数の場合は -1、 Number の場合は 1 から 8、 String の場合は 1 から 100 に設定できます。 Point、Polygon、LineString のデータ型には適用されません。 |
[除外されたパス] のプロパティ
| プロパティ | 説明 |
|---|---|
| path | インデックス作成から除外されるパス。 インデックス パスはルート (/) で始まり、通常は * ワイルドカード演算子で終わる。 たとえば、/payload/* を使用して、ペイロード プロパティの下に属するものをすべてインデックス作成から除外できます。 |
[パーティション キー] のプロパティ
| プロパティ | 説明 |
|---|---|
| パス | コレクション内のデータをパーティション分割できるパスの配列。 パスには、ワイルドカードまたは末尾のスラッシュを含めてはいけません。 たとえば、JSON プロパティ "AccountNumber" は "/AccountNumber" として指定されます。 配列には 1 つの値のみを含む必要があります。 |
| kind | パーティション分割に使用されるアルゴリズム。 Hash のみがサポートされています。 |
| version | 省略可能なフィールド (指定されていない場合)、既定値は 1 です。 大きなパーティション キーを使用するには、バージョンを 2 に設定します。 大きなパーティション キーの詳細については、 大きなパーティション キーを使用してコレクションを作成する方法に関する 記事を参照してください。 |
応答本文の例
{
"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/"
}
例 1
次の例では、手動スループットが 400 RU/秒のコレクションを作成します。 x-ms-offer-throughput ヘッダーは、スループット (RU/秒) の値を設定するために使用されます。 最小値が 400 の数値を受け取り、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/"
}
例 2
次の例では、自動スケーリングの最大スループットが 4000 RU/秒 (400 ~ 4000 RU/秒) のコレクションを作成します。 x-ms-cosmos-offer-autopilot-settings ヘッダーは、値を maxThroughput 設定するために使用されます。これは、自動スケーリングの最大 RU/秒の値です。 1000 単位ずつ増加する 4000 以上の数値を受け入れます。 自動スケーリングを使用する場合は、次の例に示すようにパーティション キー定義が必要です。
注意
既存のデータベースまたはコレクションで自動スケーリングを有効にするか、自動スケーリングから手動スループットに切り替えるには、オファーの置換に関 する記事を参照してください。
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
}
}