コレクションの作成

[アーティクル]
07/19/2023

この操作により 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
  }  
}

次の方法で共有

コレクションの作成

Request

ヘッダー

Body

本文ペイロードの例

[応答]

ヘッダー

状態コード

Body

応答本文の例

例 1

例 2

参照

その他のリソース