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

替换集合

项目
08/28/2024

Replace Collection 支持在创建后更改集合的索引策略。不支持更改集合的其他属性，如 ID 或分区键。

注意

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

请求

方法	请求 URI	说明
PUT	https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}	{databaseaccount} 是在订阅下创建的 Azure Cosmos DB 帐户的名称。 {db-id} 值是用户生成的数据库名称/ID，而不是系统生成的 id (rid) 。 {coll-id} 值是要替换的集合的名称。

标头

有关所有 Cosmos DB 请求使用的标头，请参阅常见的 Azure Cosmos DB REST 请求标头。

正文

属性	必选	类型	说明
id	必须	String	用户生成的集合的唯一名称。两个集合不能有同一 ID。它是一个不能超过 255 个字符的字符串。
indexingPolicy	可选	对象	此值用于配置集合项的索引。默认情况下，对于集合中的所有文档路径，索引策略设置为自动。
partitionKey	必需	对象	此值设置用于数据分区的分区键。若要使用大分区键，请在 partitionKey 属性中将版本指定为 2。如果 REST API 版本为 2018-12-31 或更高版本，则集合必须包含 partitionKey 定义。在 2018-12-31 之前的版本中，可以通过省略 partitionKey 定义并确保吞吐量在 400 - 10，000 RU/秒之间来创建具有手动吞吐量的旧版非分区集合。为了获得最佳性能和可伸缩性，建议始终设置分区键。了解如何选择良好的分区键。

注意

在设置自定义索引路径时，需要为由特殊路径“/*”表示的整个文档树指定默认索引规则。

{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "indexingMode": "consistent",  
    "automatic": true,  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "dataType": "Number",  
            "precision": -1,  
            "kind": "Range"  
          },  
          {  
            "dataType": "String",  
            "precision": 3,  
            "kind": "Hash"  
          }  
        ]  
      }  
    ],  
    "excludedPaths": []  
  },  
  "_rid": "XrdaAKx3Hgw=",  
  "_ts": 1459203135,  
  "_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",  
  "_etag": "\"00006c00-0000-0000-0000-56f9ac3f0000\"",  
  "_docs": "docs/",  
  "_sprocs": "sprocs/",  
  "_triggers": "triggers/",  
  "_udfs": "udfs/",  
  "_conflicts": "conflicts/"  
}

响应

Replace Collection 将更新的集合作为响应正文返回。

标头

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

状态代码

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

代码	说明
201 正常	PUT 操作成功。
400 错误的请求	JSON 正文无效。检查是否缺少大括号或引号。

正文

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

包含路径下的属性

属性	描述
path	索引行为适用的路径。索引路径以根 (/) 开头，常以 ? 结尾通配符运算符表示前缀存在多个可能的值。例如，对于 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 数据类型。

排除路径下的属性

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

{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "indexingMode": "consistent",  
    "automatic": true,  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "kind": "Range",  
            "dataType": "Number",  
            "precision": -1  
          },  
          {  
            "kind": "Hash",  
            "dataType": "String",  
            "precision": 3  
          }  
        ]  
      }  
    ],  
    "excludedPaths": []  
  },  
  "_rid": "XrdaAKx3Hgw=",  
  "_ts": 1459203136,  
  "_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",  
  "_etag": "\"00006e00-0000-0000-0000-56f9ac400000\"",  
  "_docs": "docs/",  
  "_sprocs": "sprocs/",  
  "_triggers": "triggers/",  
  "_udfs": "udfs/",  
  "_conflicts": "conflicts/"  
}

示例

PUT https://querydemo.documents.azure.com/dbs/XrdaAA==/colls/XrdaAKx3Hgw= HTTP/1.1  
x-ms.date: 04/20/2021
authorization: type%3dmaster%26ver%3d1.0%26sig%3dZY2s2H1TuPFKk1H2od5qVLbn57vjI9rKz0CMXKOk3GA%3d  
Cache-Control: no-cache  
User-Agent: Microsoft.Azure.Documents.Client/1.6.0.0  
x-ms-version: 2015-12-16  
Accept: application/json  
Host: querydemo.documents.azure.com  
Content-Length: 475  
Expect: 100-continue  
  
{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "indexingMode": "consistent",  
    "automatic": true,  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "dataType": "Number",  
            "precision": -1,  
            "kind": "Range"  
          },  
          {  
            "dataType": "String",  
            "precision": 3,  
            "kind": "Hash"  
          }  
        ]  
      }  
    ],  
    "excludedPaths": []  
  },  
  "_rid": "XrdaAKx3Hgw=",  
  "_ts": 1459203135,  
  "_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",  
  "_etag": "\"00006c00-0000-0000-0000-56f9ac3f0000\"",  
  "_docs": "docs/",  
  "_sprocs": "sprocs/",  
  "_triggers": "triggers/",  
  "_udfs": "udfs/",  
  "_conflicts": "conflicts/"  
}

HTTP/1.1 200 Ok  
Cache-Control: no-store, no-cache  
Pragma: no-cache  
Transfer-Encoding: chunked  
Content-Type: application/json  
Content-Location: https://querydemo.documents.azure.com/dbs/XrdaAA==/colls/XrdaAKx3Hgw=  
Server: Microsoft-HTTPAPI/2.0  
Strict-Transport-Security: max-age=31536000  
x-ms-last-state-change-utc: Fri, 25 Mar 2016 22:54:09.213 GMT  
etag: "00006e00-0000-0000-0000-56f9ac400000"  
x-ms-resource-quota: collections=5000;  
x-ms-resource-usage: collections=28;  
collection-partition-index: 0  
collection-service-index: 0  
x-ms-schemaversion: 1.1  
x-ms-alt-content-path: dbs/testdb  
x-ms-quorum-acked-lsn: 7902  
x-ms-current-write-quorum: 3  
x-ms-current-replica-set-size: 4  
x-ms-request-charge: 9.9  
x-ms-serviceversion: version=1.6.52.5  
x-ms-activity-id: 6050a48c-828d-4016-b73b-5e0ce2ad6271  
x-ms-session-token: M:7903  
Set-Cookie: x-ms-session-token#M=7903; Domain=querydemo.documents.azure.com; Path=/dbs/XrdaAA==/colls/XrdaAKx3Hgw=  
Set-Cookie: x-ms-session-token=7903; Domain=querydemo.documents.azure.com; Path=/dbs/XrdaAA==/colls/XrdaAKx3Hgw=  
x-ms-gatewayversion: version=1.6.52.5  
Date: Mon, 28 Mar 2016 22:12:15 GMT  
  
{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "indexingMode": "consistent",  
    "automatic": true,  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "kind": "Range",  
            "dataType": "Number",  
            "precision": -1  
          },  
          {  
            "kind": "Hash",  
            "dataType": "String",  
            "precision": 3  
          }  
        ]  
      }  
    ],  
    "excludedPaths": []  
  },  
  "_rid": "XrdaAKx3Hgw=",  
  "_ts": 1459203136,  
  "_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",  
  "_etag": "\"00006e00-0000-0000-0000-56f9ac400000\"",  
  "_docs": "docs/",  
  "_sprocs": "sprocs/",  
  "_triggers": "triggers/",  
  "_udfs": "udfs/",  
  "_conflicts": "conflicts/"  
}

通过

替换集合

请求

标头

正文

响应

标头

状态代码

正文

示例

另请参阅

其他资源