你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

创建集合

项目
08/05/2023

操作 Create Collection 在数据库中创建新集合。

注意

这些 API 参考文章介绍如何使用 Azure Cosmos DB 数据平面 API 创建资源。使用数据平面 API，可以配置基本选项，例如索引策略、分区键，就像使用 Cosmos DB SDK 一样。如果需要对所有 Azure Cosmos DB 资源提供完整的功能支持，建议使用 Cosmos DB 资源提供程序。

请求

方法	请求 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值。

属性	必选	类型	说明
x-ms-offer-throughput	可选	Number	用户为集合指定的手动吞吐量 (RU/秒) ，以每秒 100 个请求单位为单位表示。通过) 请求提高限制，最小值为 400 到 1，000，000 (或更高。只能指定或 `x-ms-cosmos-offer-autopilot-settings` 中的`x-ms-offer-throughput`一个。不能一起指定这些标头。
x-ms-cosmos-offer-autopilot-settings	可选	JSON	用户指定了自动缩放最大 RU/秒。该值是具有属性 `maxThroughput`的 JSON。例如：`{"maxThroughput": 4000}`。只能指定或 `x-ms-cosmos-offer-autopilot-settings` 中的`x-ms-offer-throughput`一个。不能一起指定这些标头。使用自动缩放时，需要 partitionKey 定义。
x-ms-offer-type	可选	字符串	这是已停用的预定义性能级别 S1、S2 和 S3 的旧标头。建议使用手动或自动缩放吞吐量，如上所述。

正文

属性	必选	类型	说明
id	必须	字符串	用户为集合生成的唯一名称。不能有两个集合具有相同的 ID。它是一个不能超过 255 个字符的字符串。
indexingPolicy	可选	对象	此值用于配置索引策略。默认情况下，索引自动应用于集合中的所有文档路径。
partitionKey	必需	对象	此值用于配置要用于将数据分区到多个分区的分区键。若要使用大分区键，请在 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

  }  
}

响应

创建集合将创建的集合作为响应正文返回。

标头

有关所有 Azure Cosmos DB 响应返回的标头，请参阅常见的 Azure Cosmos DB REST 响应标头。

状态代码

下表列出了此操作返回的常见状态代码。有关状态代码的完整列表，请参阅 HTTP 状态代码。

HTTP 状态代码	说明
201 Created	操作成功。
400 错误的请求	JSON 正文无效。检查是否缺少大括号或引号。
409 冲突	为新集合提供的 ID 已被现有集合采用。
404，子状态代码为 1013	集合创建操作仍在进行中。

如果在创建集合时遇到超时异常，请运行读取操作以验证是否已成功创建集合。成功完成集合创建操作之前，读取操作将引发异常。如果读取操作引发状态代码为 404 的异常，子状态代码为 1013，则表示集合创建操作仍在进行中。重试读取操作，直到获得 200 或 201 状态代码，这些代码会告知你已成功创建集合。

正文

属性	说明
id	它是标识新集合的唯一名称。
_摆脱	它是系统生成的属性。资源 ID (_rid) 是一个唯一标识符，它在资源模型中也是按资源堆栈分层的。它可供内部用于放置和导航权限资源。
_ts	它是系统生成的属性。它指定资源的上次更新时间戳。高值是一个时间戳。
_自我	它是系统生成的属性。它是资源的唯一可寻址 URI。
_Etag	它是一个系统生成的属性，表示乐观并发控制所需的资源 etag 。
_医生	它是一个系统生成的属性，用于指定文档资源的可寻址路径。
_sprocs	它是一个系统生成的属性，指定 (sprocs) 资源的存储过程的可寻址路径。
_触发器	它是一个系统生成的属性，用于指定触发器资源的可寻址路径。
_Udf	它是一个系统生成的属性，指定用户定义函数 (udfs) 资源的可寻址路径。
_冲突	它是一个系统生成的属性，用于指定冲突资源的可寻址路径。针对某个集合中的资源进行操作时，如果发生冲突，用户可以通过对冲突 URI 路径执行 GET 操作来检查发生冲突的资源。
indexingPolicy	它是集合的索引策略设置。
partitionKey	它是集合的分区配置设置。

包含路径下的属性

属性	说明
路径	索引行为适用的路径。索引路径以根 (/) 开头，通常以问号 (？) 通配符运算符结尾，表示前缀有多个可能值。例如，对于 SELECT * FROM Families F WHERE F.familyName = "Andersen"，必须在集合的索引策略中包含 /familyName/? 的索引路径。索引路径还可以使用 * 通配符操作符以递归方式指定路径在前缀下的行为。例如，/payload/* 可用于从索引中排除有效负载属性下的所有内容。
dataType	它是对其应用索引行为的数据类型。可以是 String、 Number、 Point、 Polygon 或 LineString。布尔值和 null 自动编制索引
kind	索引的类型。哈希索引可用于相等比较，而范围索引可用于相等、范围比较和排序。空间索引对于空间查询很有用。
精度	索引的精度。对于最大精度，可以设置为 -1;对于 Number，可以设置为 1-8;对于 String，可以设置为 1-100。不适用于 Point、 Polygon 和 LineString 数据类型。

排除路径下的属性

属性	说明
路径	从索引中排除的路径。索引路径以根 (/) 开头，通常以 * 通配符运算符结尾。例如，/payload/* 可用于从索引中排除有效负载属性下的所有内容。

分区键下的属性

属性	说明
路径	一个路径数组，使用集合中的数据可以分区。路径不得包含通配符或尾随斜杠。例如，JSON 属性“AccountNumber”指定为“/AccountNumber”。数组必须仅包含单个值。
kind	用于分区的算法。仅支持哈希。
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/秒值。它接受至少为 4000 的数字，该数字以 1000 的单位递增。使用自动缩放时，需要分区键定义，如以下示例所示：

注意

若要在现有数据库或集合上启用自动缩放，或者从自动缩放切换到手动吞吐量，请参阅替换套餐一文。

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

通过